Authentication

Brickken accepts two credentials, and they are alternatives rather than layers. Which one you use decides which parts of the platform you can reach and who pays for the transaction.

The two credentials

	API key	x402 payment
Header	`x-api-key`	`X-PAYMENT`
Who issues it	Brickken, on request	Nobody — you pay per call
What it costs	Your plan’s credits	USDC per operation
Needs a Brickken account	Yes	No
Reaches the Dapp API	Yes	No
Reaches the Agentic API	Yes, client-signed only	Yes, including relayed

There is a third secret in play that is not a Brickken credential: your private key. It never leaves your machine and is never sent to the API. It signs the x402 payment authorization and, in client-signed mode, the blockchain transaction itself.

Never send a private key or seed phrase to the Brickken API, and never paste one into a ticket, a shared terminal, or a chat. No Brickken endpoint or employee will ever ask for one.

Which credential works where

What you are calling	API key	x402
Dapp API writes (`/prepare-transactions/*` for tokenization and STO methods)	Required	Not accepted
Dapp API reads (excluding agent getters)	Required, with exceptions below	Not accepted
`POST /create-kyc-link`	Required	Not accepted
`POST /faucet/bkn` (Sandbox/Forge)	Accepted: 10 dedicated lifetime claims	Accepted: 0.01 USDC
Agent getters (`/get-agents`, `/get-agent-info`, `/get-agent-transactions`)	Accepted	Accepted
`PATCH /patch-token-docs`	Required	Not accepted
`POST /prepare-transactions` for x402-eligible agentic methods	Optional in client-controlled modes	Required for client-controlled prepare without a key; relayed prepare is credential-free
Agentic writes in `client-signed` mode	Accepted	Accepted
Agentic sends in `brickken-relayed` mode	Rejected	Required
RAMS reads and typed data (`/rams/*`)	Accepted	Accepted
`GET /get-transaction-status` for a relayed transaction	Not needed	Not needed
`GET /.well-known/x402`, `GET /openapi.json`	Not needed	Not needed

Sending both does not help you. If x-api-key is present it is validated and the whole x402 path is skipped, so no payment is taken — which also means no relayed execution. To pay with x402, omit the key entirely.

brickken-relayed sends reject API keys outright, with brickken-relayed execution requires x402 payment; API keys are not accepted. Because the /x402/... facades force relayed mode, the facade → send round trip cannot be paid for with a key at all. If you want to use a key on an agentic method, prepare it in client-signed mode.

Using an API key

Send it as a header on every request:

x-api-key: YOUR_BRICKKEN_API_KEY

curl --request GET \
  'https://api.sandbox.brickken.com/get-token-info?chainId=11155111&tokenSymbol=EXMPL' \
  --header 'x-api-key: YOUR_BRICKKEN_API_KEY'

No key yet? Request one — the form opens a prefilled email to tech@brickken.com.

Your signer address must be whitelisted

An API key alone is not enough to write. The wallet you pass as signerAddress must be whitelisted by Brickken before any prepare-transactions call will accept it. Ask for the whitelist in the same request as the key — the form has a field for it. Once that wallet performs a newTokenization, it becomes the tokenizer for the resulting token. Only the tokenizer can mint it, distribute its dividends, or manage its investor whitelist.

Sandbox and production keys are separate

Environment	API base URL	App URL
Sandbox	`https://api.sandbox.brickken.com`	`https://dapp.sandbox.brickken.com`
Production	`https://api.brickken.com`	`https://dapp.brickken.com`

Sandbox and production are separate deployments with separate databases. An API key issued for one does not work on the other.

There is no environment flag on a key. Separation comes from the deployment: a key issued against sandbox is unknown to production and vice versa. Request both if you need both.

Plans and credits

Every key belongs to a plan, and the plan grants a separate credit balance for each write method — not one shared pool.

Plan	Initial credits per method
Starter	10
Professional	100
Enterprise	10 000

Metered methods: newTokenization, whitelist, mintToken, burnToken, transferTo, transferFrom, approve, dividendDistribution, newSto, newInvest, claimTokens, closeOffer, and patch-token-docs. When a balance runs out, the call fails with Out of credits for <method>. The BKN faucet has a separate fixed balance: 10 lifetime claims per API key, for every plan. Faucet claims never consume mintToken credits. When this balance is spent, the call fails with Out of credits for faucet. The alternative x402 path costs 0.01 USDC and does not use the API-key balance.

Per-tier request throttles and quotas are configured on the usage plan attached to your key and are not published here. Ask tech@brickken.com for the limits on your tier.

Your key is scoped to the tokens it created

A key may only act on token symbols whose tokenizer email matches a newTokenization performed under that same key. Anything else returns Unauthorized token symbol. This affects get-stos, get-sto-by-id, get-investor-info, get-whitelist-status, get-allowance, and get-token-info. The payment tokens HAI, BKN, USDC, USDt, and USDT are exempt and readable by any key.

Rate limits

Rate limiting applies to POST /prepare-transactions only.

	Burst	Per minute	Concurrent
Without a key	30 per IP	10 per IP, 5 per wallet	20
With a key	120	60	500

Exceeding a limit returns 429 with Retry-After: 60.

Not every endpoint enforces a key the same way

Authentication is applied per endpoint rather than globally, and the behaviour is not uniform. Three examples from sandbox:

Call	Without a key
`GET /get-network-info`	`200` — this read is public
`GET /get-token-info`	`401 API key is required for this endpoint`
`GET /get-stos`	`400 API key is missing from headers.`

Treat both 400 and 401 as “you need a key here”, and do not assume a read is public because a neighbouring one is.

Using x402 payment

x402 lets a client pay per call in USDC instead of holding an account. It is the only way to use brickken-relayed execution, where Brickken signs and broadcasts the blockchain transaction and pays the native gas.

Choose the execution mode

brickken-relayed makes prepare free and charges the full operation at send; client-signed and client-broadcast split the operation charge between prepare and send. The Agentic pricing reference shows the matrix.

Prepare — quote depends on the mode

Call a facade such as POST /x402/agent/register, or POST /prepare-transactions with an eligible method. Relayed preparation needs no credential. A client-controlled prepare without an API key receives a 402 challenge and must complete the x402 payment handshake. The response returns txId, transactions, and an x402Requirements preview.

Send — get the challenge

Call POST /send-transactions. The API answers 402 Payment Required with a PAYMENT-REQUIRED header describing the exact chain, asset, transfer method, amount, recipient, and timeout.

Sign the payment locally

Sign the payment authorization with the payer’s private key. The key stays on your machine.

Retry with the payment

Repeat the send with the payment header attached.

X-PAYMENT: BASE64_ENCODED_X402_PAYMENT_PAYLOAD

Read the settlement

Brickken verifies the payment, runs the operation, and returns the settlement in the PAYMENT-RESPONSE header.

Header names

The API accepts four spellings of the payment header — X-PAYMENT, X-Payment, x-payment, and payment-signature. Use whichever your HTTP client produces. Browser clients can read the handshake: both PAYMENT-REQUIRED and PAYMENT-RESPONSE are listed in Access-Control-Expose-Headers.

The payment is reserved, then settled

Your payment is reserved when you pay, the operation runs, and only then is it settled. If the operation reverts, errors, or its authorization expires before confirmation, the reservation is released instead of charged. Polling a relayed operation with GET /get-transaction-status needs no credential. A status: "pending" means it was broadcast but not yet confirmed — do not pay or resubmit the same txId.

Payment asset

On Base Sepolia the x402 payment asset is Circle USDC:

0x036CbD53842c5426634e7929541eC2318f3dCF7e

It has 6 decimals and uses the EIP-3009 transfer method (EIP-712 name USDC, version 2, 300-second authorization window). The signed authorization carries the transfer, so no separate ERC-20 approve transaction is required. A live sandbox quote looks like this:

{
  "scheme": "exact",
  "network": "eip155:84532",
  "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  "amount": "10000",
  "payTo": "0x6b0173489007dE9E2e619eccd98E8fa9c610849a",
  "maxTimeoutSeconds": 300,
  "extra": {
    "tokenSymbol": "USDC",
    "displayPrice": "0.010000000000000000 USDC",
    "assetTransferMethod": "eip3009",
    "routeKey": "POST /send-transactions"
  }
}

Read the chain, asset, transfer method, amount, and recipient from the PAYMENT-REQUIRED header of the live 402 response. Never hardcode the values above — they are an illustration, not a contract.

Per surface

Surface	API key	x402	How you configure it
REST	Yes	Yes	`x-api-key` / `X-PAYMENT` headers
SDK	Yes	Yes	`new Brickken({ apiKey, signer })`, or `Brickken.fromEnv(process.env)`
MCP	Yes	Yes	`configure` tool, or `BRICKKEN_API_KEY` / `BRICKKEN_PRIVATE_KEY`
CLI	KYC and supported reads	Yes	`BRICKKEN_API_KEY` / `BRICKKEN_PRIVATE_KEY`, or `--api-key` / `--private-key`
Skill	Yes	Yes	Environment variables, per the agent client

Variable	Alias	Purpose
`BRICKKEN_API_KEY`	`BKN_API_KEY`	Brickken API key
`BRICKKEN_PRIVATE_KEY`	`BKN_PRIVATE_KEY`	Signs x402 payments and client-signed transactions
`BRICKKEN_ENV`	`BKN_ENV`	`sandbox` or `production`
`BRICKKEN_BASE_URL`	`BKN_BASE_URL`	Override the API base URL
`BRICKKEN_RPC_URL`	`BKN_RPC_URL`	RPC used to wait for deployment receipts

Brickken.fromEnv(process.env) reads the same variables and the same aliases, with one deliberate exception: it does not read BRICKKEN_PRIVATE_KEY. Turning a key into a signer is an explicit choice in the SDK — see SDK authentication.

Using the Dapp API from the SDK, the CLI, and MCP

The Dapp API is not only reachable over plain HTTP. This is what each client can actually do with an API key today.

SDK — full Dapp API access with an API key

The SDK is the client to use when your own code holds the credential. An API key alone reaches every Dapp read and write, typed, with the credential rules enforced locally before a request leaves your process.

import { Brickken } from 'brickken-sdk'

const bkn = new Brickken({ env: 'production', apiKey: process.env.BRICKKEN_API_KEY })

await bkn.tokenization.info({ tokenSymbol: 'EXMPL' })
await bkn.sto.list({ tokenSymbol: 'EXMPL' })

Dapp writes default to client-signed, so they also need a signer and a whitelisted signerAddress. See SDK for the full surface.

MCP — full Dapp API access with an API key

The hosted MCP server is the client to use when you want an AI agent to drive the Dapp API. Configure it with an API key and nothing else, and every Dapp tool works: the existing Dapp reads and prepare-based writes, create_kyc_link, and the three agent getters (get_agents, get_agent_info, get_agent_transactions).

{
  "env": "production",
  "apiKey": "YOUR_BRICKKEN_API_KEY"
}

The MCP server attaches x-api-key to every outbound request when one is configured, and it only falls back to the x402 handshake when the key is absent. So a session is either API-key mode or x402 mode, never both — set "apiKey": "" to force x402. See MCP for the connection details and the full tool list.

CLI — Dapp API, KYC, faucet, and supported reads

The CLI sends x-api-key for Dapp API transaction methods, Dapp API JSON endpoints, KYC, the Sandbox/Forge BKN faucet, and, when configured, agent getters and RAMS reads/typed-data fetches. Use brickken tx prepare --method <method> for Dapp tokenization, STO, and security-token transactions, and brickken dapp get or brickken dapp request for JSON endpoints.Relayed sends still require x402, and multipart endpoints such as /patch-token-docs remain REST-only.

Set the key for KYC and authenticated reads like this:

export BRICKKEN_API_KEY=...
brickken kyc create-link --email investor@example.com --need-kyc true
brickken agent list --chain 84532 --limit 20
brickken rams status --chain 11155111 --agent 0x… --principal 0x…
brickken dapp get --path /get-token-info --query tokenSymbol=EXMPL

Error reference

Response	Meaning
`401 API key is required for this endpoint`	This endpoint needs a key and none was sent
`400 API key is missing from headers.`	Same cause, different endpoint, different status code
`401 API key is required for this method`	This method is not x402-eligible, so a key is mandatory
`401 API key is required. x402 payment is not enabled.`	x402 is switched off on this deployment
`401 API key is required for this endpoint on the requested chain.`	x402 is not enabled for that `chainId`
`400 brickken-relayed execution requires x402 payment; API keys are not accepted`	Drop the key, or prepare in `client-signed` mode
`402 Payment Required`	Read `PAYMENT-REQUIRED`, sign, and retry with `X-PAYMENT`
`Out of credits for <method>`	Your plan’s balance for that method is exhausted
`Out of credits for faucet`	The API key has spent its 10 dedicated lifetime faucet claims
`Unauthorized token symbol`	Your key did not tokenize that symbol
`429` with `Retry-After: 60`	Rate limited on `prepare-transactions`

These are authentication and quota errors. For request validation, preflight failures, and raw on-chain revert data, see Troubleshooting.

Security rules

Never transmit a private key or seed phrase to any Brickken endpoint.
Keep API keys out of source control, tickets, screenshots, and chat. Use environment variables or a secret store.
Use sandbox keys for development. A production key can move real value.
Verify chainId, signerAddress, the token address, and every recipient before signing — on-chain actions and x402 payments are non-refundable.
Read the amount, asset, and chain from PAYMENT-REQUIRED rather than hardcoding them.
Rotate a key by requesting a replacement from tech@brickken.com and retiring the old one.

Request an API key

Start here if you do not have a key yet.

Quickstart

Make your first call on any surface.

Overview

Developer Build Programme

First call

BKN Faucet

The two credentials

Which credential works where

Using an API key

Your signer address must be whitelisted

Sandbox and production keys are separate

Plans and credits

Your key is scoped to the tokens it created

Rate limits

Not every endpoint enforces a key the same way

Using x402 payment

Header names

The payment is reserved, then settled

Payment asset

Per surface

Using the Dapp API from the SDK, the CLI, and MCP

SDK — full Dapp API access with an API key

MCP — full Dapp API access with an API key

CLI — Dapp API, KYC, faucet, and supported reads

Error reference

Security rules

Request an API key

Quickstart

​The two credentials

​Which credential works where

​Using an API key

​Your signer address must be whitelisted

​Sandbox and production keys are separate

​Plans and credits

​Your key is scoped to the tokens it created

​Rate limits

​Not every endpoint enforces a key the same way

​Using x402 payment

​Header names

​The payment is reserved, then settled

​Payment asset

​Per surface

​Using the Dapp API from the SDK, the CLI, and MCP

​SDK — full Dapp API access with an API key

​MCP — full Dapp API access with an API key

​CLI — Dapp API, KYC, faucet, and supported reads

​Error reference

​Security rules

Request an API key

Quickstart

The two credentials

Which credential works where

Using an API key

Your signer address must be whitelisted

Sandbox and production keys are separate

Plans and credits

Your key is scoped to the tokens it created

Rate limits

Not every endpoint enforces a key the same way

Using x402 payment

Header names

The payment is reserved, then settled

Payment asset

Per surface

Using the Dapp API from the SDK, the CLI, and MCP

SDK — full Dapp API access with an API key

MCP — full Dapp API access with an API key

CLI — Dapp API, KYC, faucet, and supported reads

Error reference

Security rules