> ## Documentation Index > Fetch the complete documentation index at: https://docs.brickken.com/llms.txt > Use this file to discover all available pages before exploring further. # Request BKN from the Faucet > Request 100 BKN on Ethereum Sepolia with an API key or a 0.01 USDC x402 payment. `POST /faucet/bkn` is available in Sandbox and Forge. It mints **100 BKN on Ethereum Sepolia** to `recipientAddress`. Use exactly one authentication mode: * `x-api-key`: consumes one of the key's **10 dedicated lifetime faucet credits**. * `X-PAYMENT`: settles the live **0.01 USDC** x402 challenge and consumes no API-key credit. Every request needs `Idempotency-Key`, and its value must be a UUID v4. Create a new UUID v4 for every new logical claim. If a request times out or its response is lost, retry the same claim with the same UUID. Reusing that UUID with a different recipient returns `409 Conflict`. The recipient address has a separate 24-hour cooldown. An idempotent retry does not spend another faucet credit, and a request rejected by validation or cooldown does not spend one either. ## Client examples ```bash theme={null} curl --request POST 'https://api.sandbox.brickken.com/faucet/bkn' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_BRICKKEN_API_KEY' \ --header 'Idempotency-Key: 4d0f91d8-453d-4fb5-a8e1-c722bc7b75a1' \ --data '{"recipientAddress":"0x1111111111111111111111111111111111111111"}' ``` ```ts theme={null} const result = await bkn.faucet.requestBkn({ recipientAddress: '0x1111111111111111111111111111111111111111', // Optional: generated as UUID v4 when omitted. idempotencyKey: '4d0f91d8-453d-4fb5-a8e1-c722bc7b75a1', }) console.log(result.idempotencyKey) console.log(result.payment) // present only when the SDK paid through x402 ``` ```bash theme={null} brickken faucet bkn \ --recipient-address 0x1111111111111111111111111111111111111111 \ --idempotency-key 4d0f91d8-453d-4fb5-a8e1-c722bc7b75a1 \ --json ``` ```json theme={null} { "name": "request_bkn_faucet", "arguments": { "recipientAddress": "0x1111111111111111111111111111111111111111", "idempotencyKey": "4d0f91d8-453d-4fb5-a8e1-c722bc7b75a1" } } ``` SDK, CLI, and MCP generate a UUID v4 when you omit it and return the actual value used. If crash recovery matters, generate and persist the UUID before the first call so it remains available even if the client never receives a response. ## Response The API returns `200` when confirmation completed within the request and `202` when the mint was submitted and can finish asynchronously. ```json theme={null} { "claimId": "1d0f91d8-453d-4fb5-a8e1-c722bc7b75a2", "status": "submitted", "chainId": "11155111", "recipientAddress": "0x1111111111111111111111111111111111111111", "amount": "100", "amountRaw": "100000000000000000000", "token": { "address": "0x2458fB1620ff84019d73216fF20aA1F82Bc8E4CC", "symbol": "BKN", "decimals": 18 }, "transactionHash": "0x...", "explorerUrl": "https://sepolia.etherscan.io/tx/0x...", "cooldownEndsAt": "2026-08-26T12:00:00.000Z" } ``` `429` means the recipient is still in cooldown and includes `Retry-After`. `Out of credits for faucet` means the API key has spent all 10 lifetime claims; use x402 for a paid request or contact Brickken. ## OpenAPI ````yaml api-reference/openapi.json POST /faucet/bkn openapi: 3.1.0 info: title: Brickken API V2 description: >- Welcome to the Brickken API documentation. This API allows customers to create and manage tokenization processes, including creating new tokenizations, minting/burning/transferring tokens, whitelisting users, manage tokens approvals. This documentation provides detailed information on how to use the API, including the necessary endpoints, request formats, and expected responses.
**Authentication**All API requests require an API key for authentication. Include your API key in the `x-api-key` header of each request:
```
      x-api-key: YOUR_API_KEY
    ```
Ensure that your API key is kept secure and not shared publicly. A common parameter for all requests is the `signerAddress`. Such address MUST be whitelisted in our factory. To whitelist an address and/or request an API key either for sandbox/production environment please contact with: tech@brickken.com. Once a `signerAddress` performs a `newTokenization` we refer to that address as the tokenizer. The tokenizer will be the only one allowed to mint such token, distribute dividends on such token and whitelist/blacklist investors of such token. Regarding actions like transferring tokens or burning tokens, the `signerAddress` can be any user and not only the tokenizer.
**Supported Networks & Addresses**
Sepolia (sandbox environment only)
```
      Chain Id: "aa36a7"
      Factory Address: "0x933ABAA95a7Fd0Bc683bDe2adB89f4C5EA64897b"
      BKN Address: "0x97a13487f889dc770Ac925Be2d3b6c833FA7746a"
      USDT Address: "0x28d2B01854D0aBec267a3DDcad9163580E6E8604"
      USDC Address: "0xb10cE8e28aEb1ae27b968Fb3bfed2FD7dd52daCb"
    ```
Base Sepolia (sandbox / testing)
```
      Chain Id: "84532" (hex "14a34")
      x402 USDC (Circle, EIP-3009): "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
      ERC-8004 Identity Registry: "0x8004A818BFB912233c491871b3d84c89A494BD9e"
      ERC-8004 Reputation Registry: "0x8004B663056A597Dffe9eCcC1965A193B7388713"
    ```
Ethereum mainnet (production environment only)
```
      Chain Id: "1"
      Factory Address: "0x91af681C85Ca98Efc5D69C1B62E6F435030969Db"
      BKN Address: "0x0A638F07ACc6969abF392bB009f216D22aDEa36d"
      USDT Address: "0xdac17f958d2ee523a2206206994597c13d831ec7"
      USDC Address: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
    ```
Base mainnet (production environment only)
```
      Chain Id: "2105"
      Factory Address: "0x278D7bdc2451B0Fa4087A68ce084a86cB91D4d83"
      BKN Address: "0xddB293BB5C5258F7484A94a0fBd5c8B2F6E4e376"
      USDT Address: N/A
      USDC Address: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
    ```
BNB Smart Chain mainnet (production environment only)
```
      Chain Id: "38"
      Factory Address: "0xCe4529Fe88df480BD777d3e32dfD7032e6C685ff"
      BKN Address: "0x0e28bC9B03971E95acF9ae1326E51ecF9C55B498"
      USDT Address: "0x55d398326f99059fF775485246999027B3197955"
      USDC Address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
    ```
Avalance C Chain mainnet (production environment only)
```
      Chain Id: "a86a"
      Factory Address: "0xc6c230FA8F40022dE997727436Fae01caAbcDe61"
      BKN Address: "0xd44E4Dc8bdF7C1c62CfDBb182022097BA42Ac6bC"
      USDT Address: "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7"
      USDC Address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"
    ```
**Usage Workflow**
1. **Prepare Transactions:**- Use the `POST /prepare-transactions` endpoint with the desired method (e.g., `newTokenization`, `mintToken`, etc...) to prepare the transaction(s). - The response will include an array of unsigned transactions that needs to be signed.
**Example Of An Endpoint Response:**```json { "transactions": [ { "from": "0xSignerAddress", "to": "0xTargetAddress", "value": { "type": "BigNumber", "hex": "0x00" }, "nonce": 1, "chainId": 11155111, "data": "0x...", "type": 2, "maxPriorityFeePerGas": { "type": "BigNumber", "hex": "0x..." }, "maxFeePerGas": { "type": "BigNumber", "hex": "0x..." }, "gasLimit": { "type": "BigNumber", "hex": "0x..." } } ] } ```
2. **Sign the Transactions:**- Use your preferred method or wallet to sign the transaction data provided in the response. - Ensure that the signer address matches the `signerAddress` provided in the initial request.
**Example Of signing a transaction with typescript and `ethers-js`:**```typescript const tx = {...} // One of the object in the array returned by the `/prepare-transactions` endpoint const privateKey = process.env.PRIVATE_KEY; const wallet = new ethers.Wallet(privateKey); const signedTx = await wallet.signTransaction(tx); console.log('Signed Transaction:', signedTx); ```
**NOTE:** Be sure to have enough funds in the signer wallet to cover for the transaction cost
3. **Submit Signed Transactions:**- Use the `POST /send-transactions` endpoint to submit the signed transaction(s) along with the required parameters. - The API will process the transactions, send them to the blockchain, and update the Brickken database accordingly.
4. **Check Transaction Status:**- Use the `GET /get-transaction-status` endpoint to check the status of your transaction. - Provide either the on-chain transaction hash (`hash`) or the internal transaction ID (`txId`) to retrieve the status.
**Environments**The API is available in several environments for testing and production purposes:- Sandbox: `https://api.sandbox.brickken.com/` - Master (Production): `https://api.brickken.com/`
The API also exposes x402scan discovery facade endpoints under /x402/... The public discovery target is https://api.brickken.com, with /.well-known/x402 returning resource URLs and /openapi.json returning the generated OpenAPI 3.1 document. version: 2.0.0 servers: - url: https://api.sandbox.brickken.com description: Sandbox Environment - url: https://api.brickken.com description: Production Environment security: - apiKeyAuth: [] paths: /faucet/bkn: post: tags: - BKN Faucet summary: Request 100 BKN on Ethereum Sepolia description: >- Sandbox/Forge only. Uses one of the API key's 10 dedicated lifetime faucet credits, separate from mintToken, or a 0.01 USDC x402 payment. Recipients have a 24-hour cooldown. A new logical claim needs a new UUID v4; retry the same claim with the same UUID. operationId: mintSepoliaBkn parameters: - name: Idempotency-Key in: header required: true description: UUID v4. Reuse only for a retry of the same logical claim. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - recipientAddress properties: recipientAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ not: const: '0x0000000000000000000000000000000000000000' description: Non-zero Ethereum Sepolia recipient address. responses: '200': description: The mint transaction was confirmed during the request. content: application/json: schema: $ref: '#/components/schemas/BknFaucetResponse' '202': description: The mint transaction was submitted and may confirm asynchronously. content: application/json: schema: $ref: '#/components/schemas/BknFaucetResponse' '400': description: Invalid recipient, UUID, or exhausted API-key faucet balance. '402': description: x402 payment required when no API key is sent. headers: PAYMENT-REQUIRED: description: Base64-encoded x402 payment request. schema: type: string '409': description: >- The UUID was already used with another recipient or authentication identity. '429': description: The recipient is still within its 24-hour cooldown. headers: Retry-After: schema: type: integer '503': description: The faucet could not prepare or reconcile the mint safely. security: - apiKeyAuth: [] - x402Payment: [] components: schemas: BknFaucetResponse: type: object additionalProperties: false required: - claimId - status - chainId - recipientAddress - amount - amountRaw - token - transactionHash - explorerUrl - cooldownEndsAt properties: claimId: type: string format: uuid status: type: string enum: - confirmed - submitted chainId: type: string const: '11155111' recipientAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ amount: type: string const: '100' amountRaw: type: string const: '100000000000000000000' token: type: object additionalProperties: false required: - address - symbol - decimals properties: address: type: string const: '0x2458fB1620ff84019d73216fF20aA1F82Bc8E4CC' symbol: type: string const: BKN decimals: type: integer const: 18 transactionHash: type: string pattern: ^0x[a-fA-F0-9]{64}$ explorerUrl: type: string format: uri cooldownEndsAt: type: string format: date-time securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key x402Payment: type: apiKey in: header name: X-Payment description: >- Base64-encoded x402 payment payload. Supported for x402-eligible agentic methods on /x402/... facades, /prepare-transactions, and eligible /send-transactions retries. ````