Authentication

aibank supports three authentication methods depending on your use case.

1. API Key authentication

Most endpoints require an API key passed via the X-API-Key header:

curl http://localhost:4000/v1/wallets \
  -H "X-API-Key: ak_your_api_key"

Getting an API key

There are three ways to obtain an API key:

Method	Endpoint	Prefix	Use case
Self-registration	`POST /v1/agents/register`	`ak_`	Agent registers itself
Platform creation	`POST /v1/platform/agents`	`ak_`	Platform creates agent
Key generation	`POST /v1/keys`	`gw_`	Gateway-only access

Self-registration (no auth required)

const res = await fetch("http://localhost:4000/v1/agents/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "my-agent" }),
});

const { apiKey } = await res.json();
// apiKey = "ak_a1b2c3d4..."

Key generation (no auth required)

For gateway-only usage without wallet creation:

const res = await fetch("http://localhost:4000/v1/keys", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "user@example.com" }),
});

const { api_key } = await res.json();
// api_key = "gw_a1b2c3d4..."

New keys come with $10.00 in credits for gateway API calls.

2. Master key authentication

Platform management endpoints use a separate X-Master-Key header:

curl http://localhost:4000/v1/platform/agents \
  -H "X-Master-Key: mk_your_master_key"

Master keys have mk_ prefix and can:

Create and manage agents
Set spending limits across fleets
Rotate agent API keys
Create additional master keys
Revoke other master keys (but not the currently-active one)

3. x402 payment authentication

Gateway endpoints accept on-chain USDC payments instead of API keys:

# No API key needed -- pay with a transaction hash
curl http://localhost:4000/v1/gateway/anthropic/v1/messages \
  -H "X-Payment: 0xTransactionHash" \
  -H "X-Payment-Chain: base-sepolia" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "max_tokens": 100, "messages": []}'

See the Trading & Payments guide for the full x402 flow.

Credit system

API key users have a credit balance that is consumed by gateway calls. Check your balance:

curl http://localhost:4000/v1/balance \
  -H "X-API-Key: ak_your_key"

{
  "credits_usd": 8.50,
  "total_spent": 1.50
}

When credits reach zero, gateway calls return 402 Insufficient Credits. Wallet operations (transfers, swaps) use on-chain assets and are not limited by credits.

Endpoint auth requirements

Endpoint group	Auth method	Header
`POST /v1/agents/register`	None	--
`POST /v1/keys`	None	--
`GET /v1/health`	None	--
`GET /v1/providers`	None	--
`GET /v1/device/*`	None	--
`POST /v1/device/claim`	None	--
`/v1/wallets/*`	API key	`X-API-Key`
`/v1/balance`, `/v1/usage`	API key	`X-API-Key`
`/v1/services/`, `/v1/catalog/`	API key	`X-API-Key`
`/v1/trading/*`	API key	`X-API-Key`
`/v1/gateway/*`	API key or x402	`X-API-Key` or `X-Payment`
`/v1/platform/*`	Master key	`X-Master-Key`

Error responses

All auth failures return consistent error objects:

{
  "error": "Missing X-API-Key header",
  "code": "UNAUTHORIZED"
}

Code	Status	Meaning
`UNAUTHORIZED`	401	Missing or invalid key
`INSUFFICIENT_CREDITS`	402	No credits remaining
`PAYMENT_REQUIRED`	402	x402 payment needed
`PAYMENT_INVALID`	402	x402 payment verification failed
`PAYMENT_ALREADY_USED`	402	Transaction hash already consumed

Authentication

On this page