Bankr

Safety & Access Control

Dedicated Agent Wallet: When building autonomous agents, create a separate Bankr account rather than using your personal wallet. This isolates agent funds — if a key is compromised, only the agent wallet is exposed. Fund it with limited amounts and replenish as needed.

API Key Types: Bankr uses a single key format (bk_...) with capability flags (agentApiEnabled, llmGatewayEnabled). You can optionally configure a separate LLM Gateway key via bankr config set llmKey or BANKR_LLM_KEY — useful when you want independent revocation or different permissions for agent vs LLM access.

Read-Only API Keys: Keys with readOnly: true filter all write tools (swaps, transfers, staking, token launches, etc.) from agent sessions. The /agent/sign and /agent/submit endpoints return 403. Ideal for monitoring bots and research agents.

IP Whitelisting: Set allowedIps on your API key to restrict usage to specific IPs. Requests from non-whitelisted IPs are rejected with 403 at the auth layer.

Rate Limits: 100 messages/day (standard), 1,000/day (Bankr Club), or custom per key. Resets 24h from first message (rolling window). LLM Gateway uses a credit-based system.

Key safety rules:

• Store keys in environment variables (BANKR_API_KEY, BANKR_LLM_KEY), never in source code
• Add ~/.bankr/ and .env to .gitignore — the CLI stores credentials in ~/.bankr/config.json
• Test with small amounts on low-cost chains (Base, Polygon) before production use
• Use waitForConfirmation: true with /agent/submit — transactions execute immediately with no confirmation prompt
• Rotate keys periodically and revoke immediately if compromised at bankr.bot/api

Reference: references/safety.md

Common Patterns

Check Before Trading

# Check balance
bankr prompt "What is my ETH balance on Base?"

# Check price
bankr prompt "What's the current price of PEPE?"

# Then trade
bankr prompt "Buy $20 of PEPE on Base"

Portfolio Review

# Direct balance check (no AI agent, instant response)
bankr balances
bankr balances --chain base
bankr balances --chain base,solana
bankr balances --json

# Via AI agent (natural language, richer context)
bankr prompt "Show my complete portfolio"

# Chain-specific
bankr prompt "What tokens do I have on Base?"

# Token-specific
bankr prompt "Show my ETH across all chains"

Set Up Automation

# DCA strategy
bankr prompt "DCA $100 into ETH every week"

# Stop loss protection
bankr prompt "Set stop loss for my ETH at $2,500"

# Limit order
bankr prompt "Buy ETH if price drops to $3,000"

Market Research

# Price and analysis
bankr prompt "Do technical analysis on ETH"

# Trending tokens
bankr prompt "What tokens are trending on Base?"

# Compare tokens
bankr prompt "Compare ETH vs SOL"

API Workflow

Bankr uses an asynchronous job-based API:

1. Submit — Send prompt (with optional threadId), get job ID and thread ID
2. Poll — Check status every 2 seconds
3. Complete — Process results when done
4. Continue — Reuse threadId for multi-turn conversations

The bankr prompt command handles this automatically. When using the REST API directly, implement the poll loop yourself (see Option 2 above or the reference below). For manual job control via CLI, use bankr status <jobId> and bankr cancel <jobId>.

For details on the API structure, job states, polling strategy, and error handling, see:

Reference: references/api-workflow.md

Synchronous Endpoints

For direct signing and transaction submission, Bankr also provides synchronous endpoints:

• POST /agent/sign - Sign messages, typed data, or transactions without broadcasting
• POST /agent/submit - Submit raw transactions directly to the blockchain

These endpoints return immediately (no polling required) and are ideal for:

• Authentication flows (sign messages)
• Gasless approvals (sign EIP-712 permits)
• Pre-built transactions (submit raw calldata)

Reference: references/sign-submit-api.md

Error Handling

Common issues and fixes:

• Authentication errors → Run bankr login or check bankr whoami (CLI), or verify your X-API-Key header (REST API)
• Insufficient balance → Add funds or reduce amount
• Token not found → Verify symbol and chain
• Transaction reverted → Check parameters and balances
• Rate limiting → Wait and retry

For comprehensive error troubleshooting, setup instructions, and debugging steps, see:

Reference: references/error-handling.md

Best Practices

Security

1. Never share your API key or LLM key
2. Use a dedicated agent wallet with limited funds for autonomous agents
3. Use read-only API keys for monitoring and research-only agents
4. Set IP whitelisting for server-side agents with known IPs
5. Verify addresses before large transfers
6. Use stop losses for leverage trading
7. Store keys in environment variables, not source code — add ~/.bankr/ to .gitignore

See references/safety.md for comprehensive safety guidance.

Trading

1. Check balance before trades
2. Specify chain for lesser-known tokens
3. Consider gas costs (use Base/Polygon for small amounts)
4. Start small, scale up after testing
5. Use limit orders for better prices

Automation

1. Test automation with small amounts first
2. Review active orders regularly
3. Set realistic price targets
4. Always use stop loss for leverage
5. Monitor execution and adjust as needed

Tips for Success

For New Users

• Start with balance checks and price queries
• Test with $5-10 trades first
• Use Base for lower fees
• Enable trading confirmations initially
• Learn one feature at a time

For Experienced Users

• Leverage automation for strategies
• Use multiple chains for diversification
• Combine DCA with stop losses
• Explore advanced features (leverage, Polymarket)
• Monitor gas costs across chains

Prompt Examples by Category

Trading

• "Buy $50 of ETH on Base"
• "Swap 0.1 ETH for USDC"
• "Sell 50% of my PEPE"
• "Bridge 100 USDC from Polygon to Base"

Portfolio

• bankr balances (direct, no AI processing)
• bankr balances --chain base (single chain)
• "Show my portfolio"
• "What's my ETH balance?"
• "Total portfolio value"
• "Holdings on Base"

Market Research

• "What's the price of Bitcoin?"
• "Analyze ETH price"
• "Trending tokens on Base"
• "Compare UNI vs SUSHI"

Transfers

• "Send 0.1 ETH to vitalik.eth"
• "Transfer $20 USDC to @friend"
• "Send 50 USDC to 0x123..."

NFTs

• "Show Bored Ape floor price"
• "Buy cheapest Pudgy Penguin"
• "Show my NFTs"

Polymarket

• "What are the odds Trump wins?"
• "Bet $10 on Yes for [market]"
• "Show my Polymarket positions"

Leverage

• "Open 5x long on ETH with $100"
• "Short BTC 10x with stop loss at $45k"
• "Show my Avantis positions"

Automation

• "DCA $100 into ETH weekly"
• "Set limit order to buy ETH at $3,000"
• "Stop loss for all holdings at -20%"

Token Deployment

Solana (LaunchLab):

• "Launch a token called MOON on Solana"
• "Launch a token called FROG and give fees to @0xDeployer"
• "Deploy SpaceRocket with symbol ROCK"
• "Launch BRAIN and route fees to 7xKXtg..."
• "How much fees can I claim for MOON?"
• "Claim my fees for MOON" (works for creator or fee recipient)
• "Show my Fee Key NFTs"
• "Claim my fee NFT for ROCKET" (post-migration)
• "Transfer fees for MOON to 7xKXtg..."

EVM (Clanker):

• "Deploy a token called BankrFan with symbol BFAN on Base"
• "Claim fees for my token MTK"

Arbitrary Transactions

• "Submit this transaction: {to: 0x..., data: 0x..., value: 0, chainId: 8453}"
• "Execute this calldata on Base: {...}"
• "Send raw transaction with this JSON: {...}"

Sign API (Synchronous)

Direct message signing without AI processing:

# Sign a plain text message
curl -X POST "https://api.bankr.bot/agent/sign" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signatureType": "personal_sign", "message": "Hello, Bankr!"}'

# Sign EIP-712 typed data (permits, orders)
curl -X POST "https://api.bankr.bot/agent/sign" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signatureType": "eth_signTypedData_v4", "typedData": {...}}'

# Sign a transaction without broadcasting
curl -X POST "https://api.bankr.bot/agent/sign" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signatureType": "eth_signTransaction", "transaction": {"to": "0x...", "chainId": 8453}}'

Submit API (Synchronous)

Direct transaction submission without AI processing:

# Submit a raw transaction
curl -X POST "https://api.bankr.bot/agent/submit" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {"to": "0x...", "chainId": 8453, "value": "1000000000000000000"},
    "waitForConfirmation": true
  }'

Reference: references/sign-submit-api.md

Resources

• Documentation: https://docs.bankr.bot
• LLM Gateway Docs: https://docs.bankr.bot/llm-gateway/overview
• API Key Management: https://bankr.bot/api
• Terminal: https://bankr.bot/terminal
• CLI Package: https://www.npmjs.com/package/@bankr/cli
• Twitter: @bankr_bot

Troubleshooting

CLI Not Found

# Verify installation
which bankr

# Reinstall if needed
bun install -g @bankr/cli

Authentication Issues

CLI:

# Check current auth
bankr whoami

# Re-authenticate
bankr login

# Check LLM key specifically
bankr config get llmKey

REST API:

# Test your API key
curl -s "https://api.bankr.bot/_health" -H "X-API-Key: $BANKR_API_KEY"

API Errors

See references/error-handling.md for comprehensive troubleshooting.

Getting Help

1. Check error message in CLI output or API response
2. Run bankr whoami to verify auth (CLI) or test with a curl to /_health (REST API)
3. Consult relevant reference document
4. Test with simple queries first (bankr prompt "What is my balance?" or POST /agent/prompt)

Pro Tip: The most common issue is not specifying the chain for tokens. When in doubt, always include "on Base" or "on Ethereum" in your prompt.

Security: Keep your API key private. Never commit your config file to version control. Only trade amounts you can afford to lose.

Quick Win: Start by checking your portfolio (bankr prompt "Show my portfolio") to see what's possible, then try a small $5-10 trade on Base to get familiar with the flow.