API Keys

API keys are account-level credentials that work across every Bankr developer surface — the Wallet API, Agent API, token launching, and the LLM Gateway. Each key carries its own permissions and access controls, so you can scope a key to exactly what it needs. Pair these per-key controls with the wallet-level controls in Bankr Console — both layers are enforced.

Keys are created and managed at bankr.bot/api-keys. All keys share the bk_... format.

Scope every key to least privilege

When you generate a key, enable only the surfaces it needs — the permission flags are independent:

• Only using the LLM Gateway? Enable gateway access and nothing else — turn wallet, agent, and token-launch access off, and turn read-only on.
• Turn read-only on unless the key must transact. New keys are read-write by default.
• Set the IP allowlist for any key deployed to servers with known egress IPs.

A scoped key caps the blast radius: if it leaks, an attacker gets only the surfaces you enabled.

Use a dedicated agent wallet

For production agents, use a separate Bankr account with its own API key and wallet:

• Blast radius isolation — a compromised key only affects the agent wallet
• Independent controls — read-only mode, IP allowlist, rate limits scoped to the agent
• Easy revocation — rotate the agent key without touching your main account

Setup: create a separate account at bankr.bot, generate a key at bankr.bot/api-keys, configure access controls, fund it with only what the agent needs. Turn on MFA for that account if the agent needs raw transactions or higher limits, since an account without MFA is capped.

Recommended configurations

Use case	Read-only	IP allowlist	Recipient allowlist
Monitoring bot	Yes	Yes	—
Trading bot	No	Yes	Yes
Public-facing demo	Yes	No	—
Dev / testing	No	No	No

API Key Permissions

Each API key has independent capability flags:

Flag	Default	Description
walletApiEnabled	Enabled	Access to wallet write operations (/wallet/swap-quote, /wallet/swap, /wallet/transfer, /wallet/sign, /wallet/submit, /wallet/x402-pay) and fee claims
agentApiEnabled	Enabled	Access to AI agent endpoints (/agent/prompt, /agent/profile, /agent/job/*)
tokenLaunchApiEnabled	Enabled	Access to token deployment (/token-launches/deploy). Also gates the deploy tool when using the Agent API.
llmGatewayEnabled	Disabled	Access to the LLM Gateway at llm.bankr.bot and to LLM credit top-ups (/llm/credits/*)
readOnly	Disabled	Restricts Wallet/Agent API to read-only operations (no transactions). Toggle it on in web settings for keys that must not transact.
allowedIps	Empty (all IPs)	IP allowlist — accepts IPs and CIDR ranges (e.g., 10.0.0.0/24)
allowedRecipients	Empty (all addresses)	Wallet allowlist — restricts which addresses the agent can send funds to

Each flag is configured independently.

With an API key, agentApiEnabled also gates managing the agent's skills, MCP servers, env vars, profile, files, apps, x402 endpoints and webhooks. A read-only key can list them but not change them.

Read-Only Mode

When readOnly is enabled on an API key, the agent can only retrieve information — it cannot execute transactions, swaps, transfers, or any state-changing operations. Use as the default for monitoring bots and public-facing surfaces.

Behavior by Endpoint

Endpoint	Behavior
POST /agent/prompt	Works, but only read tools are available (prices, balances, analytics, research)
GET /agent/job/:jobId, POST /agent/job/:jobId/cancel	Works normally
POST /wallet/swap, /wallet/transfer, /wallet/sign, /wallet/submit, /wallet/x402-pay	Blocked — returns 403
POST /token-launches/deploy and fee claims	Blocked — returns 403
Agent management writes	Blocked — returns 403 (skills, MCP servers, env vars, profile, files, apps, x402, webhooks)
GET /wallet/me, GET /wallet/portfolio, POST /wallet/swap-quote	Works normally

Read-only doesn't cover account management: a read-only key can still buy a Bankr Club subscription and top up LLM credits (with llmGatewayEnabled).

Error Responses

Sign endpoint (403):

{
  "error": "Read-only API key",
  "message": "This API key has read-only access and cannot sign messages or transactions. Update your API key permissions at https://bankr.bot/api-keys"
}

Submit endpoint (403):

{
  "error": "Read-only API key",
  "message": "This API key has read-only access and cannot submit transactions. Update your API key permissions at https://bankr.bot/api-keys"
}

How It Works

When a read-only key calls /agent/prompt, the agent session receives a system directive that removes all write tools. The following tool categories are filtered out:

• Token swaps
• Token and ETH transfers
• NFT purchases and trades
• Staking and unstaking
• Limit, stop, DCA, and TWAP orders
• Token launches and deployments
• Leveraged trading positions
• Polymarket bets
• Fee claims

The agent is aware of the restriction and will explain it to users who request write operations.

IP Allowlist

The allowedIps array restricts which IP addresses can use the key. Supports both individual IPs and CIDR ranges. Validation runs in the auth middleware before any endpoint logic.

• Empty array (default) — all IPs are accepted
• One or more entries — only requests from listed IPs or CIDR ranges are accepted (e.g., "192.168.1.1", "10.0.0.0/24")

Minimum CIDR prefix lengths are enforced to prevent overly broad ranges that would effectively disable the allowlist: /8 for IPv4 and /16 for IPv6. Ranges broader than these are rejected at key creation time.

Error response (403):

{
  "error": "IP address not allowed",
  "message": "IP address not allowed for this API key"
}

Wallet Allowlist

The allowedRecipients field restricts which wallet addresses the key can send funds or assets to. It applies to transfers, swaps that pay out to another address, a token launch's fee recipient (a deploy naming an unlisted recipient returns 403 Restricted API key), and any tool that moves value to an external address. An x402 payment is checked against the payee; for an endpoint hosted on Bankr's x402 Cloud that's the endpoint's payout wallet, not the shared fee router. Deploying an x402 Cloud endpoint, or changing its payout address, to an address outside the list also returns 403 Restricted API key. Most useful for autonomous agents where recipients are LLM-resolved.

• Both lists empty (default) — all recipient addresses are accepted
• An address on either chain — both chains are restricted to listed addresses plus the user's own wallet (/wallet/transfer accepts only addresses on the list for the transfer's chain: solana on Solana, evm otherwise)

Each chain has its own list:

{
  "allowedRecipients": {
    "evm": ["0xabc..."],
    "solana": ["7xKX..."]
  }
}

EVM addresses are stored and matched case-insensitively. You can update evm and solana independently — omit a chain key to leave it unchanged.

Error response when a blocked address is targeted:

Recipient 0xabc... is not in the trusted addresses list. Contact your API key administrator to add this address.

The agent is aware of the restriction and will surface this message if a user requests a transaction to an unlisted address.

The API-key allowlist is independent from the wallet-level Permitted Recipients. When both are configured, both must pass:

• API-key allowlist = where this key is allowed to send
• Wallet allowlist = where this wallet is allowed to send, regardless of key

Webhooks — a webhook's agent runs check the webhook's own allowedRecipients, not the key's. So a key with an allowlist can only deploy or update webhooks whose allowedRecipients stay within the key's list; anything wider returns 403.

Operations blocked outright while an allowlist is set

Some operations pay a counterparty the key can't name in advance — the address is chosen by a marketplace, an order book, or a contract at execution time, so there's nothing to check against the allowlist. Rather than let those through unchecked, they're refused entirely whenever allowedRecipients is non-empty on either chain:

• NFT buys, mints (Seadrop and Manifold), listings, and collection offers / offer accepts
• Polymarket share buys and sells
• Hyperliquid perp and spot trades, closes and deposits, and opening Avantis positions (withdrawing from Hyperliquid to your own wallet still works)
• Airdrops
• Raw /wallet/submit calls, and eth_signTransaction / eth_signTypedData_v4 / 32-byte personal_sign (order digest) requests on /wallet/sign
• The agent signing typed data or a 32-byte message (plain-text messages such as logins still sign)

Buying Polymarket shares is not supported when trusted-recipient restrictions are
configured on this API key — the counterparty address cannot be validated against
the allowlist. Contact your API key administrator.

An allowlist on either chain locks these down on both — a key hardened for EVM is treated as hardened for uncontrolled-counterparty operations everywhere. If a key needs these operations, leave allowedRecipients empty and bound the key with the IP allowlist and the wallet-level USD limits instead.

Rate Limits

Daily Message Limits

The /agent/prompt endpoint requires a Bankr Club subscription or Max Mode with LLM credits. There is no free tier.

Tier	Daily Limit	Requirement
Max Mode	100 messages	LLM credit balance > $0
Bankr Club	1,000 messages	Active subscription ($20/mo)
Custom (per key)	Set by Bankr for specific keys — not editable at bankr.bot/api-keys	—

Custom limits override both the Max Mode and Bankr Club defaults.

The limit uses a rolling 24-hour window from the time of first usage — it does not reset at midnight.

Error response (429):

{
  "error": "Daily limit exceeded",
  "message": "You have reached your daily API limit of 100 messages. Upgrade to Bankr Club for 1000 messages/day. Resets at 2025-01-15T12:00:00.000Z",
  "resetAt": 1736942400000,
  "limit": 100,
  "used": 100
}

The resetAt field is a Unix timestamp (milliseconds) indicating when the counter resets. The limit and used fields show the current quota and consumption.

note

The "Upgrade to Bankr Club" portion of the message only appears for Max Mode accounts. Bankr Club members and accounts with a custom daily limit see a shorter message without the upgrade prompt.

Other Rate Limits

Endpoints carry their own limits and answer 429 when one is hit. The ones an integration is most likely to meet:

Scope	Limit
Wallet writes (/wallet/transfer, /wallet/swap, /wallet/sign, /wallet/submit)	10 requests per minute per IP, shared
API key creation (bankr.bot and bankr login)	20 per hour per IP — 429 "Too many API key creations. Please try again later."
External orders (/trading/order)	10 requests per second per API key

API Key vs LLM Gateway Key

A single API key can serve both the Agent API and the LLM Gateway when both flags are enabled. You can also use separate keys:

Config	Agent API	LLM Gateway
Single key	BANKR_API_KEY	Same key
Separate keys	BANKR_API_KEY	BANKR_LLM_KEY

In the CLI:

• bankr login --api-key KEY sets the Agent API key
• bankr login --llm-key KEY sets the LLM Gateway key
• bankr config set llmKey KEY updates the LLM key independently

When to use separate keys:

• Different permission requirements (e.g., agent key is read-only, LLM key only needs gateway access)
• Independent revocation — rotate one without affecting the other
• Different rate limit tracking

Layer wallet-level controls on top

Even with a hardened API key, the wallet's security controls still apply. We recommend setting a daily USD limit and a per-transaction limit appropriate for the agent's purpose — they cap total damage if the key is misconfigured or compromised.

Incident response

If you suspect a key is compromised:

1. Pause the wallet at bankr.bot → Security. Halts every outbound transaction immediately, including in-flight broadcasts. Revoking the key alone does not stop transactions already past auth.
2. Rotate the key with Rotate Key in its settings at bankr.bot/api-keys — the replacement keeps every permission flag, allowlist and custom limit, and the old key stops working at once. Update your deployments with the new secret, or revoke the key outright if nothing needs it.
3. Audit — review recent transactions and agent job history before unpausing.