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 Terminal — 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.

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/transfer, /wallet/sign, /wallet/submit)
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
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.

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	Works normally
POST /agent/cancel/:jobId	Works normally
POST /wallet/sign	Blocked — returns 403
POST /wallet/submit	Blocked — returns 403
POST /wallet/transfer	Blocked — returns 403
GET /wallet/me	Works normally
GET /wallet/portfolio	Works normally

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 agent can send funds or assets to. It applies to transfers, swaps, and any tool that moves value to an external address. Most useful for autonomous agents where recipients are LLM-resolved.

• Empty arrays (default) — all recipient addresses are accepted
• One or more addresses — only listed addresses (plus the user's own wallet) are accepted

Supports both EVM and Solana independently:

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

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
• Airdrops

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 in BNKR)
Custom (per key)	Set 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.

General API Rate Limits

These apply to all API consumers by IP or API key:

Scope	Window	Limit
Public endpoints (/public/*)	15 minutes	100 requests per IP
General endpoints	1 minute	120 requests per IP
External orders (/trading/order)	1 second	10 requests 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 Bankr Terminal 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. Revoke the key at bankr.bot/api-keys.
3. Rotate — generate a new key with the same access profile and update deployments.
4. Audit — review recent transactions and agent job history before unpausing.