Brickken CLI

Public CLI for the Brickken Dapp API, Agentic API, KYC, faucet, and RAMS workflows.

It covers:

• API-key-authenticated Dapp API transaction and JSON endpoint workflows
• ERC-8004 agent identity operations
• ERC-8004 reputation feedback operations
• ERC-8226 RAMS mandate lifecycle, compliance, executor, read, and EIP-712 signing operations
• x402-capable agentic token create, mint, burn, transfer, transfer-from, and approve operations
• raw transaction preparation, signing, sending, and one-shot execution

Repository: https://github.com/Brickken/brickken-api-cli

Install

npm install -g brickken-cli

AI Agent Skill

The npm package includes the Brickken Codex skill at skills/brickken.

Install it into the default Codex skills directory:

brickken skill install

Install it into a custom skills directory:

brickken skill install --path ~/.codex/skills --force

Print the bundled skill path:

brickken skill path

Authentication

Dapp API requests use BRICKKEN_API_KEY. Agentic and RAMS client-controlled requests use the API key when configured, or x402 otherwise. brickken-relayed sends always use x402 because Brickken is the transaction relayer. KYC link creation requires an API key. Agent getters cost 0.000001 USDC through x402; RAMS reads cost 0.001 USDC:

export BRICKKEN_API_KEY=...

Provide a private key for local transaction signing and x402 payment signing:

export BRICKKEN_PRIVATE_KEY=0x...

Sandbox BKN Faucet

Request 100 BKN on Ethereum Sepolia with either an API key (10 dedicated lifetime claims, separate from mintToken) or a private key that pays 0.01 USDC through x402:

brickken faucet bkn \
  --recipient-address 0x1111111111111111111111111111111111111111 \
  --json

The CLI generates a UUID v4 and returns it as idempotencyKey. To retry the same logical claim, reuse it explicitly:

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

Use a new UUID for a new claim; the same UUID with another recipient is rejected. Recipients have a 24-hour cooldown. This command is for Sandbox/Forge and exposes API-key or x402 auth only, not the public bearer flow. Do not configure both --api-key and --private-key for it.

Dapp API

Use the CLI with an API key for legacy Dapp API tokenization, STO, security-token, and read workflows. Transaction methods use brickken tx prepare and brickken tx send; read endpoints use brickken dapp get. Use brickken dapp request for JSON POST or PATCH endpoints.

Prepare a tokenization with a payload file:

export BRICKKEN_API_KEY=...

brickken tx prepare \
  --method newTokenization \
  --file new-tokenization.json \
  --json

Read token information:

brickken dapp get \
  --path /get-token-info \
  --query tokenSymbol=EXMPL \
  --json

The CLI preserves the Dapp API prepare → sign → send flow. The signer wallet must be whitelisted, and the API key must have credits and access to the requested token or method. Multipart file uploads such as /patch-token-docs remain REST-only.

Quick Start

The high-level commands are wallet-first and prepare-only by default. With an API key, client-controlled requests use API-key authentication; without one, x402 is used for eligible Agentic API methods. Add --execute to prepare, sign locally, and send in one step. Relayed sends always use x402.

Agentic operations do not require a tokenizer user in the Brickken database. --owner-email is optional metadata and can be omitted.

For a QA-oriented terminal walkthrough, see QA_TERMINAL_DEMO.md.

Example setup:

export BASE_URL="https://api.sandbox.brickken.com"
export CHAIN="11155111"
export WALLET="0xYourWallet"
export BRICKKEN_RPC_URL="https://ethereum-sepolia-rpc.publicnode.com"

The CLI accepts chain identifiers as decimal or hex-like values. For example, Sepolia can be passed as 11155111 or aa36a7.

Sanity checks:

brickken --version
test -n "$BRICKKEN_PRIVATE_KEY" && echo "private key ok" || echo "private key missing"
test -n "$BRICKKEN_RPC_URL" && echo "rpc ok" || echo "rpc missing"
command -v jq

Environment Notes

• Prefer sandbox or another environment with agent persistence enabled for the full register -> set-uri -> set-metadata flow.
• Public explorers such as 8004scan may not index non-public environments even when the on-chain transaction succeeded.
• Budget Sepolia USDC accordingly. A full QA run with retries can consume roughly 0.02 USDC per executed command because both prepare and send are x402-priced.

Input Safety

The CLI supports --json. When a command appears to "drop" fields, the usual cause is shell expansion, empty variables, or inline JSON quoting, not the JSON output flag itself.

• Quote every variable that can contain spaces.
• Prefer --file for nested JSON, long text, automation, or values assembled by shell scripts.
• Echo critical variables such as AGENT_UUID and TOKEN_ADDRESS before reusing them in the next command.
• Do not continue from create-token into mint or burn unless tokenAddress is present in the output.

Agent Flow

Register the agent:

brickken agent register \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --name "Research Agent" \
  --description "On-chain AI research agent" \
  --image https://example.com/agent.png \
  --service-name A2A \
  --service-endpoint https://agent.example/.well-known/agent-card.json \
  --service-version 0.3.0 \
  --ai-model-provider OpenAI \
  --ai-model-name "Research Model" \
  --x402-support true \
  --execute \
  --json | tee register-output.json

Capture the returned UUID:

export AGENT_UUID="$(jq -r '.prepared.info.agentUuid' register-output.json)"

Finalize the agent profile:

brickken agent set-uri \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --agent-uuid "$AGENT_UUID" \
  --name "Research Agent" \
  --description "On-chain AI research agent" \
  --image https://example.com/agent.png \
  --service-name A2A \
  --service-endpoint https://agent.example/.well-known/agent-card.json \
  --service-version 0.3.0 \
  --ai-model-provider OpenAI \
  --ai-model-name "Research Model" \
  --tag ai-agent \
  --tag terminal-demo \
  --documentation https://docs.brickken.com \
  --source-code https://github.com/Brickken/brickken-api-cli \
  --license MIT \
  --agent-type research \
  --supported-trust feedback \
  --x402-support true \
  --active true \
  --execute \
  --json

Set structured agent metadata:

brickken agent set-metadata \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --agent-uuid "$AGENT_UUID" \
  --metadata-key capabilities \
  --metadata-value '{"tasks":["research","summarization","token-operations"]}' \
  --metadata-encoding json \
  --execute \
  --json

For more complex metadata payloads, prefer a file:

cat > metadata.json <<'EOF'
{
  "chain": "11155111",
  "signerAddress": "0xYourWallet",
  "agentUuid": "00000000-0000-0000-0000-000000000000",
  "metadataKey": "capabilities",
  "metadataValue": "{\"tasks\":[\"research\",\"summarization\",\"token-operations\"]}",
  "metadataEncoding": "json"
}
EOF

brickken tx prepare \
  --method agentSetMetadata \
  --file metadata.json \
  --execute \
  --json

Token Flow

Deploy an agentic token through the high-level command:

brickken create-token \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --name "Research Agent Token" \
  --symbol RAGT \
  --agent-wallet "$WALLET" \
  --premint 1000 \
  --decimals 18 \
  --execute \
  --json | tee create-token-output.json

When create-token --execute succeeds, the CLI waits for the deployment receipt and adds tokenAddress to the JSON output. Sepolia has a built-in public RPC fallback; for other chains set --rpc-url, BRICKKEN_RPC_URL, or BKN_RPC_URL.

export TOKEN_ADDRESS="$(jq -r '.tokenAddress' create-token-output.json)"

Mint more tokens:

brickken mint \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --to 0xRecipientWallet \
  --amount 100 \
  --decimals 18 \
  --execute \
  --json

Burn tokens:

brickken burn \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --from 0xHolderWallet \
  --amount 25 \
  --decimals 18 \
  --execute \
  --json

Approve allowance:

brickken approve \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --spender-address 0xSpenderWallet \
  --amount 50 \
  --decimals 18 \
  --execute \
  --json

Transfer tokens:

brickken transfer \
  --chain "$CHAIN" \
  --signer-address "$WALLET" \
  --token-address 0xDeployedAgentToken \
  --to 0xRecipientWallet \
  --amount 10 \
  --decimals 18 \
  --execute \
  --json

Transfer through allowance:

brickken transfer-from \
  --chain "$CHAIN" \
  --signer-address 0xApprovedSpenderWallet \
  --token-address 0xDeployedAgentToken \
  --from 0xTokenHolderWallet \
  --to 0xRecipientWallet \
  --amount 5 \
  --decimals 18 \
  --execute \
  --json

The high-level create-token, mint, burn, transfer, transfer-from, and approve commands use the agentic backend methods agentCreateToken, agentMintToken, agentBurnToken, agentTransferToken, agentTransferFromToken, and agentApproveToken.

Command Groups

• brickken agent: ERC-8004 identity and reputation operations
• brickken dapp: API-key-authenticated Dapp API GET and JSON request operations
• brickken kyc: API-key-authenticated investor KYC link creation
• brickken rams: ERC-8226 mandate lifecycle, executor/compliance administration, reads, and EIP-712 signing
• brickken create-token: deploy an agentic ERC-20 through the x402 flow
• brickken mint: mint an agentic ERC-20 through the x402 flow
• brickken burn: burn an agentic ERC-20 through the x402 flow
• brickken approve: approve ERC-20 allowance through the x402 flow
• brickken transfer: transfer ERC-20 tokens through the x402 flow
• brickken transfer-from: transfer ERC-20 allowance through the x402 flow
• brickken tx: raw prepare, sign, send, status, and one-shot execute flows

KYC and Agent Getters

Create or reuse an investor and return a Sumsub verification link. This command always requires BRICKKEN_API_KEY:

brickken kyc create-link \
  --email [email protected] \
  --need-kyc true \
  --json

List agents visible to the API key, then fetch a profile and its transaction history:

brickken agent list --chain 84532 --limit 20 --offset 0 --json
brickken agent info --agent-uuid "$AGENT_UUID" --json
brickken agent transactions --agent-uuid "$AGENT_UUID" --limit 20 --offset 0 --json

Agent getters accept either API-key authentication or x402. In x402 mode, agent list requires both --chain and --owner-wallet-address, and the payment signer must own that wallet. Detail and transaction calls accept either --agent-uuid, or --agent-id together with --chain. Pagination limits are 1-100 and offsets must be non-negative.

RAMS Mandate Flow

RAMS is the Regulated Agent Mandate Standard (ERC-8226): a principal grants an agent a scoped, time-bounded, value-capped authority over a specific asset, enforced on-chain by AgentMandate (the mandate registry), ComplianceProvider (principal eligibility), and AgentExecutor (the gated call surface). It is currently deployed on Ethereum Sepolia only (11155111).

brickken rams exposes ten write commands, five API-key-or-x402 read commands, and local EIP-712 signing. Writes prepare only by default; add --execute to sign/send and settle x402. Online typed-data fetching follows the same API-key-or-0.001-USDC-x402 policy.

A mandate can only be granted to a principal that is already eligible on the ComplianceProvider. Check that first, because rams grant-principal requires the provider owner key:

brickken rams compliance-status \
  --chain 11155111 \
  --principal "$PRINCIPAL" \
  --identity-ref "$IDENTITY_REF" \
  --json

Fetch typed data and sign it with the principal key:

brickken rams sign \
  --operation grant-mandate \
  --chain 11155111 \
  --agent "$AGENT" \
  --principal "$PRINCIPAL" \
  --valid-until 1789000000 \
  --identity-ref "$IDENTITY_REF" \
  --asset "$ASSET" \
  --max-transaction-value 1000000 \
  --max-cumulative-value 5000000 \
  --action 0x23b872dd \
  --json > rams-signature.json

Then request Brickken-relayed execution (omit --signer-address; the backend supplies its operation signer):

brickken rams grant \
  --chain 11155111 \
  --agent "$AGENT" \
  --principal "$PRINCIPAL" \
  --valid-until 1789000000 \
  --identity-ref "$IDENTITY_REF" \
  --asset "$ASSET" \
  --max-transaction-value 1000000 \
  --max-cumulative-value 5000000 \
  --action 0x23b872dd \
  --signature "$(jq -r .signature rams-signature.json)" \
  --deadline "$(jq -r .deadline rams-signature.json)" \
  --execution-mode brickken-relayed \
  --execute --json

The private key configured for this second command authorizes the x402 payment; it does not need to be the principal key.

Inspect the resulting mandate. The CLI sends the configured API key when available; without one, it uses the configured private key to pay 0.001 USDC through x402:

brickken rams inspect --chain 11155111 --agent "$AGENT" --principal "$PRINCIPAL" --json

Preflight an execution before spending gas on it. can-execute returns the authoritative on-chain canExecute result plus a per-check breakdown explaining any refusal:

brickken rams can-execute \
  --chain 11155111 \
  --agent "$AGENT" \
  --principal "$PRINCIPAL" \
  --asset "$ASSET" \
  --amount 1000000 \
  --selector 0x23b872dd \
  --json

The other reads are rams status (freeze flag, current EIP-712 nonce, optional operator approval), rams compliance-status (principal eligibility), and rams executor-action (the AgentExecutor ActionSpec for a selector: supported, hasAmount, amountIndex).

Run brickken rams --help and brickken rams <command> --help for the complete input surface. Lifecycle signature mode is supported only by grant, revoke, extend, and set-operator; executor and admin operations are never Brickken-relayed.

Raw Transaction Flow

Use brickken tx when you want full control over the payload or need to call a specific Dapp or Agentic API transaction method directly. If BRICKKEN_API_KEY is configured, the CLI sends it for client-controlled prepare and send requests.

One-shot execution:

brickken tx prepare \
  --method agentCreateToken \
  --file token.json \
  --execute \
  --json

Supported agentic token methods include:

• agentCreateToken
• agentMintToken
• agentBurnToken
• agentTransferToken
• agentTransferFromToken
• agentApproveToken
• agentApprove as a CLI alias that normalizes to agentApproveToken

Dapp API transaction methods include:

• newTokenization
• newSto
• newInvest
• claimTokens
• closeOffer
• mintToken
• whitelist
• burnToken
• transferFrom
• transferTo
• approve
• dividendDistribution

For manual control:

brickken tx prepare --method agentRegister --file agent-register.json --json
brickken tx sign --file prepared.json --json
brickken tx send --tx-id 0xPreparedTxId --signed-tx 0xSignedRawTx --json

| Command | Purpose | Typical usage | | --- | --- | --- | | brickken tx prepare | Prepare a raw transaction payload | Agentic methods and custom API V2 methods | | brickken tx sign | Sign a transaction locally | Manual debugging and step-by-step flows | | brickken tx send | Send signed transaction payloads | Manual debugging and step-by-step flows | | brickken tx status | Look up a broadcast transaction by hash | Post-send tracking |

For brickken tx prepare --execute, the CLI:

1. prepares the transaction with /prepare-transactions
2. signs locally with the configured private key
3. sends the signed payload to /send-transactions

Example:

brickken tx prepare \
  --method agentSetMetadata \
  --file metadata.json \
  --execute \
  --json

Keep using the explicit tx sign / tx send path when you want full manual control over each step or need to inspect the unsigned payload before broadcasting.

Configuration

Global flags:

• --env <forge|sandbox|production> (forge resolves to https://d4aqanatl1.execute-api.eu-west-1.amazonaws.com/forge)
• --base-url <url>
• --api-key <key>
• --private-key <key>
• --rpc-url <url>
• --env-file <path>
• --json

Environment variables:

• BRICKKEN_API_KEY or BKN_API_KEY (Dapp API, KYC, faucet, agent getters, and RAMS reads/typed-data; also client-controlled transaction requests when configured)
• BRICKKEN_PRIVATE_KEY or BKN_PRIVATE_KEY
• BRICKKEN_BASE_URL or BKN_BASE_URL
• BRICKKEN_RPC_URL or BKN_RPC_URL
• BRICKKEN_ENV or BKN_ENV

The CLI automatically loads .env from the current working directory unless --env-file is provided.

Build Locally

pnpm install
pnpm build
node dist/index.js --help