Request BKN from the Faucet

Request 100 BKN on Ethereum Sepolia

curl --request POST \
  --url https://api.sandbox.brickken.com/faucet/bkn \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "recipientAddress": "<string>"
}
'

import requests

url = "https://api.sandbox.brickken.com/faucet/bkn"

payload = { "recipientAddress": "<string>" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({recipientAddress: '<string>'})
};

fetch('https://api.sandbox.brickken.com/faucet/bkn', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.brickken.com/faucet/bkn",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'recipientAddress' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.brickken.com/faucet/bkn"

	payload := strings.NewReader("{\n  \"recipientAddress\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.brickken.com/faucet/bkn")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"recipientAddress\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.brickken.com/faucet/bkn")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"recipientAddress\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "claimId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "confirmed",
  "chainId": "11155111",
  "recipientAddress": "<string>",
  "amount": "100",
  "amountRaw": "100000000000000000000",
  "token": {
    "address": "0x2458fB1620ff84019d73216fF20aA1F82Bc8E4CC",
    "symbol": "BKN",
    "decimals": 18
  },
  "transactionHash": "<string>",
  "explorerUrl": "<string>",
  "cooldownEndsAt": "2023-11-07T05:31:56Z"
}

{
  "claimId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "confirmed",
  "chainId": "11155111",
  "recipientAddress": "<string>",
  "amount": "100",
  "amountRaw": "100000000000000000000",
  "token": {
    "address": "0x2458fB1620ff84019d73216fF20aA1F82Bc8E4CC",
    "symbol": "BKN",
    "decimals": 18
  },
  "transactionHash": "<string>",
  "explorerUrl": "<string>",
  "cooldownEndsAt": "2023-11-07T05:31:56Z"
}

POST

faucet

bkn

Request 100 BKN on Ethereum Sepolia

curl --request POST \
  --url https://api.sandbox.brickken.com/faucet/bkn \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "recipientAddress": "<string>"
}
'

import requests

url = "https://api.sandbox.brickken.com/faucet/bkn"

payload = { "recipientAddress": "<string>" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({recipientAddress: '<string>'})
};

fetch('https://api.sandbox.brickken.com/faucet/bkn', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.brickken.com/faucet/bkn",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'recipientAddress' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.brickken.com/faucet/bkn"

	payload := strings.NewReader("{\n  \"recipientAddress\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.brickken.com/faucet/bkn")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"recipientAddress\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.brickken.com/faucet/bkn")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"recipientAddress\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "claimId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "confirmed",
  "chainId": "11155111",
  "recipientAddress": "<string>",
  "amount": "100",
  "amountRaw": "100000000000000000000",
  "token": {
    "address": "0x2458fB1620ff84019d73216fF20aA1F82Bc8E4CC",
    "symbol": "BKN",
    "decimals": 18
  },
  "transactionHash": "<string>",
  "explorerUrl": "<string>",
  "cooldownEndsAt": "2023-11-07T05:31:56Z"
}

{
  "claimId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "confirmed",
  "chainId": "11155111",
  "recipientAddress": "<string>",
  "amount": "100",
  "amountRaw": "100000000000000000000",
  "token": {
    "address": "0x2458fB1620ff84019d73216fF20aA1F82Bc8E4CC",
    "symbol": "BKN",
    "decimals": 18
  },
  "transactionHash": "<string>",
  "explorerUrl": "<string>",
  "cooldownEndsAt": "2023-11-07T05:31:56Z"
}

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

REST
SDK
CLI
MCP

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"}'

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

brickken faucet bkn \
  --recipient-address 0x1111111111111111111111111111111111111111 \
  --idempotency-key 4d0f91d8-453d-4fb5-a8e1-c722bc7b75a1 \
  --json

{
  "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.

{
  "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.

Authorizations

x-api-key

string

header

required

Headers

Idempotency-Key

string<uuid>

required

UUID v4. Reuse only for a retry of the same logical claim.

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}$

Body

application/json

recipientAddress

string

required

Non-zero Ethereum Sepolia recipient address.

Pattern: ^0x[a-fA-F0-9]{40}$

Response

The mint transaction was confirmed during the request.

claimId

string<uuid>

required

status

enum<string>

required

Available options:

confirmed,

submitted

chainId

string

required

Allowed value: "11155111"

recipientAddress

string

required

Pattern: ^0x[a-fA-F0-9]{40}$

amount

string

required

Allowed value: "100"

amountRaw

string

required

Allowed value: "100000000000000000000"

token

object

required

Show child attributes

transactionHash

string

required

Pattern: ^0x[a-fA-F0-9]{64}$

explorerUrl

string<uri>

required

cooldownEndsAt

string<date-time>

required

Overview

Developer Build Programme

First call

BKN Faucet

Client examples

Response

Authorizations

Headers

Body

Response

​Client examples

​Response

Authorizations

Headers

Body

Response

Client examples

Response