> ## 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.

# Authentication & Configuration

> Dapp API, KYC, faucet, API-key-or-x402 reads, private-key signing, environments, and CLI configuration.

## What the CLI can authenticate

The CLI uses endpoint-specific authentication. Dapp API transaction methods and JSON endpoints require an API key. Client-controlled Agentic API and RAMS writes use an API key when configured and otherwise fall back to x402; relayed writes use x402. KYC link creation requires an API key, while the BKN faucet, agent getters, and RAMS reads use an API key when configured and otherwise fall back to x402.

| Request | Credential the CLI sends |
| - | - |
| Dapp transaction methods (`newTokenization`, `newSto`, `mintToken`, and other Dapp methods) | `x-api-key` (required) |
| Client-controlled Agentic/RAMS writes | `x-api-key` if configured, otherwise x402 |
| Relayed Agentic/RAMS writes | x402 only |
| `kyc create-link` | `x-api-key` (required) |
| `faucet bkn` (Sandbox/Forge) | Exactly one: `x-api-key`, or 0.01 USDC x402 with a private key |
| `agent list`, `info`, `transactions` | `x-api-key` if configured, otherwise x402 |
| `tx status` | `x-api-key` if configured, otherwise existing access or x402 |
| `rams inspect`, `status`, `can-execute`, `compliance-status`, `executor-action`, `sign` | `x-api-key` if configured, otherwise x402 |
| `dapp get`, `dapp request` | `x-api-key` (required) |

<Note>
  The CLI supports Dapp API transaction methods through `brickken tx prepare --method <method>` and Dapp API JSON endpoints through `brickken dapp get` or `brickken dapp request`. Multipart file uploads such as `/patch-token-docs` remain REST-only.

  Use the [MCP server](/mcp/introduction) or [REST API](/api-reference/introduction) when you need multipart uploads or the full typed Dapp API surface.
</Note>

## Write authentication

Transaction authentication depends on the method and execution mode:

1. In `brickken-relayed` mode, the CLI prepares for free and the send carries the full operation charge.
2. Dapp API transaction methods use the configured API key at prepare and send; the operation is charged against the key's credits.
3. Client-controlled Agentic API and RAMS writes use the configured API key when present. Without a key, the CLI handles the x402 challenge at each priced step.
4. When an x402 request responds `402 Payment Required`, the CLI signs the payment locally and retries with an `X-PAYMENT` header.

In the recommended `brickken-relayed` mode the private key signs **only the x402 payment** — Brickken's relayer signs and broadcasts the operation. In the default `client-signed` mode the same key also **signs the blockchain transaction** locally.

## KYC and read authentication

KYC and Dapp API JSON endpoints always need an API key. Agent getters and RAMS read/typed-data endpoints send the key when configured and otherwise use the configured private key for x402.

```bash theme={null}
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 "$AGENT" --principal "$PRINCIPAL"
```

`BKN_API_KEY` is accepted as an alias, or pass global `--api-key`. Offline `rams sign --typed-data-file` does not require a key.

<Warning>
  Your private key never leaves your machine. Treat it as a secret: prefer an `.env` file or environment variable over passing `--private-key` inline.
</Warning>

## Provide a private key

```bash theme={null}
export BRICKKEN_PRIVATE_KEY=0x...
```

`BKN_PRIVATE_KEY` is accepted as an alias.

## Environments and base URLs

Select the environment with `--env` or `BRICKKEN_ENV` (default: `sandbox`):

| Environment | Base URL |
| - | - |
| `sandbox` (default) | `https://api.sandbox.brickken.com` |
| `production` | `https://api.brickken.com` |

Override the base URL directly with `--base-url` or `BRICKKEN_BASE_URL` when needed. An internal `forge` environment exists for Brickken pre-release QA — contact `tech@brickken.com` for its base URL.

## Networks and chain IDs

Pass the target chain with `--chain`. Both decimal and hex forms are accepted, and common decimal IDs are normalized automatically — for example Base Sepolia can be passed as `84532` or `14a34`.

| Network | Decimal | Hex |
| - | - | - |
| Base mainnet | `8453` | `0x2105` |
| Base Sepolia | `84532` | `0x14a34` |
| Ethereum Sepolia (legacy) | `11155111` | `0xaa36a7` |

## RPC URL

Some commands (notably [`create-token`](/cli/commands/token-economics)) wait for the deployment receipt to read back the deployed `tokenAddress`. Set an RPC for the target chain:

```bash theme={null}
export BRICKKEN_RPC_URL="https://sepolia.base.org"   # Base Sepolia
```

`BKN_RPC_URL` is accepted as an alias, or use `--rpc-url`.

## Configuration precedence

Configuration is resolved in this order (highest priority first):

1. **Command-line flags** — `--env`, `--base-url`, `--api-key`, `--private-key`, `--rpc-url`, `--env-file`, `--json`
2. **Environment variables** — `BRICKKEN_*` or `BKN_*`
3. **`.env` file** in the current working directory (or the path given by `--env-file`)
4. **Defaults** — `sandbox` environment, `client-signed` execution mode (pass `--execution-mode brickken-relayed` to opt into relayed)

### Global flags

| Flag | Description |
| - | - |
| `--env <forge\|sandbox\|production>` | Target Brickken environment |
| `--base-url <url>` | Override the Brickken API base URL |
| `--api-key <key>` | API key for Dapp API, KYC, faucet, agent getters, and client-controlled reads/writes |
| `--private-key <key>` | Private key for local signing and x402 payments |
| `--rpc-url <url>` | RPC URL used to wait for token deployment receipts |
| `--env-file <path>` | Env file to load before resolving config |
| `--json` | Print machine-readable JSON output |

### Environment variables

| Variable | Alias | Purpose |
| - | - | - |
| `BRICKKEN_API_KEY` | `BKN_API_KEY` | Dapp API, KYC, faucet, agent getters, and client-controlled reads/writes |
| `BRICKKEN_PRIVATE_KEY` | `BKN_PRIVATE_KEY` | Signing and x402 payment key |
| `BRICKKEN_BASE_URL` | `BKN_BASE_URL` | API base URL |
| `BRICKKEN_RPC_URL` | `BKN_RPC_URL` | RPC for receipt polling |
| `BRICKKEN_ENV` | `BKN_ENV` | `forge`, `sandbox`, or `production` |

## Budget note

Relayed preparation is free, while client-controlled modes split the write charge between prepare and send. Agent getters cost `0.000001 USDC` per x402 call. On Base Sepolia and other non-production environments the write reference price is commonly `0.01 USDC` per operation. Fund the wallet behind `BRICKKEN_PRIVATE_KEY` with the exact asset returned by the live challenge. See [Pricing](/api-reference/endpoint/agentic-pricing) for the execution-mode matrix and mainnet write table.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.