Bankr

Bankr

Execute crypto trading and DeFi operations using natural language. Two integration options:

1. Bankr CLI (recommended) — Install @bankr/cli for a batteries-included terminal experience 2. REST API — Call https://api.bankr.bot directly from any language or tool

Both use the same API key. The API has two layers:

• Wallet API (/wallet/*) — Direct, synchronous endpoints for portfolio, transfers, signing, and transaction submission
• Agent API (/agent/*) — AI-powered async prompt endpoint for natural language operations

Getting an API Key

Before using either option, you need a Bankr API key. Two ways to get one:

Option A: Headless email login (recommended for agents)

Two-step flow — send OTP, then verify and complete setup. See "First-Time Setup" below for the full guided flow with user preference prompts.

# Step 1 — send OTP to email
bankr login email user@example.com

# Step 2 — verify OTP and generate API key (options based on user preferences)
bankr login email user@example.com --code 123456 --accept-terms --key-name "My Agent" --read-write

This creates a wallet, accepts terms, and generates an API key — no browser needed. Before running step 2, ask the user which APIs they need (wallet, agent, both via --read-write, LLM gateway) and their preferred key name.

Option B: Bankr Terminal

1. Visit bankr.bot/api 2. Sign up / Sign in — Enter your email and the one-time passcode (OTP) sent to it 3. Generate an API key — Create a key with Wallet & Agent API access enabled (the key starts with bk_...)

Both options automatically provision EVM wallets (Base, Ethereum, Polygon, Unichain) and a Solana wallet — no manual wallet setup needed.

Option 1: Bankr CLI (Recommended)

Install

bun install -g @bankr/cli

Or with npm:

npm install -g @bankr/cli

First-Time Setup

Headless email login (recommended for agents)

When the user asks to log in with an email, walk them through this flow:

Step 1 — Send verification code

bankr login email <user-email>

Step 2 — Ask the user for the OTP code and all preferences in a single message. This avoids unnecessary back-and-forth. Ask for:

1. OTP code — the code they received via email 2. Accept Terms of Service (REQUIRED) — Present the Terms of Service link and confirm the user agrees. The login command will fail for new users without `--accept-terms`. You MUST ask for ToS acceptance and do not pass --accept-terms unless the user has explicitly confirmed. 3. Which APIs do they need?

• Wallet API — enabled by default, use --no-wallet-api to disable
• Agent API (--agent-api) — AI-powered prompts and natural language operations
• Token Launch — enabled by default, use --no-token-launch to disable
• Add --read-write to allow transactions (without it, enabled APIs are read-only)

4. Enable LLM gateway access? (--llm) — multi-model API at llm.bankr.bot (currently limited to beta testers). Skip if user doesn't need it. 5. Key name? (--key-name) — a display name for the API key (e.g. "My Agent", "Trading Bot")

Step 3 — Construct and run the step 2 command with the user's choices. Do NOT execute if the user has not explicitly accepted the Terms of Service — ask again if needed:

# Full access: wallet + agent with write + LLM
bankr login email <user-email> --code <otp> --accept-terms --key-name "My Agent" --agent-api --read-write --llm

# Agent with write access (AI can execute transactions)
bankr login email <user-email> --code <otp> --accept-terms --key-name "Trading Agent" --agent-api --read-write

# Default key (wallet + token launch, read-only)
bankr login email <user-email> --code <otp> --accept-terms --key-name "My Key"

# Agent read-only (research, prices, balances — no transactions)
bankr login email <user-email> --code <otp> --accept-terms --key-name "Research Agent" --agent-api

# LLM-only (no wallet, no token launch)
bankr login email <user-email> --code <otp> --accept-terms --key-name "LLM Client" --no-wallet-api --no-token-launch --llm

Login options reference

New key defaults (when no flags are passed):

Any option not provided on the command line will be prompted interactively by the CLI, so you can mix headless and interactive as needed.

Login with existing API key

If the user already has an API key:

bankr login --api-key bk_YOUR_KEY_HERE

If they need to create one at the Bankr Terminal: 1. Run bankr login --url — prints the terminal URL 2. Present the URL to the user, ask them to generate a bk_... key 3. Run bankr login --api-key bk_THE_KEY

Separate LLM Gateway Key (Optional)

If your LLM gateway key differs from your API key, pass --llm-key during login or run bankr config set llmKey YOUR_LLM_KEY afterward. When not set, the API key is used for both. See references/llm-gateway.md for full details.

Verify Setup

bankr whoami
bankr wallet portfolio
bankr agent prompt "What is my balance?"

Option 2: REST API (Direct)

No CLI installation required — call the API directly with curl, fetch, or any HTTP client.

Authentication

All requests require an X-API-Key header:

curl -X POST "https://api.bankr.bot/agent/prompt" \
  -H "X-API-Key: bk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is my ETH balance?"}'

Quick Example: Submit → Poll → Complete

# 1. Submit a prompt — returns a job ID
JOB=$(curl -s -X POST "https://api.bankr.bot/agent/prompt" \
  -H "X-API-Key: $BANKR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is my ETH balance?"}')
JOB_ID=$(echo "$JOB" | jq -r '.jobId')

# 2. Poll until terminal status
while true; do
  RESULT=$(curl -s "https://api.bankr.bot/agent/job/$JOB_ID" \
    -H "X-API-Key: $BANKR_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ] && break
  sleep 2
done

# 3. Read the response
echo "$RESULT" | jq -r '.response'

Conversation Threads

Every prompt response includes a threadId. Pass it back to continue the conversation:

# Start — the response includes a threadId
curl -X POST "https://api.bankr.bot/agent/prompt" \
  -H "X-API-Key: $BANKR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is the price of ETH?"}'
# → {"jobId": "job_abc", "threadId": "thr_XYZ", ...}

# Continue — pass threadId to maintain context
curl -X POST "https://api.bankr.bot/agent/prompt" \
  -H "X-API-Key: $BANKR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "And what about SOL?", "threadId": "thr_XYZ"}'

Omit threadId to start a new conversation. CLI equivalent: bankr agent prompt --continue (reuses last thread) or bankr agent prompt --thread <id>.

API Endpoints Summary

Wallet API (/wallet/*) — Direct endpoints (synchronous)

• Read endpoints (/wallet/me, /wallet/portfolio) — any valid API key with a wallet
• Write endpoints (/wallet/transfer, /wallet/sign, /wallet/submit) — require walletApiEnabled, readOnly check, and allowedRecipients enforcement
• IP allowlist enforced on all endpoints

Agent API (/agent/*) — AI-powered endpoints (async)

Deprecated endpoints

The following /agent/* endpoints still work but are deprecated in favor of /wallet/*:

For full API details (request/response schemas, job states, rich data, polling strategy), see:

Reference: references/api-workflow.md | references/sign-submit-api.md

CLI Command Reference (v0.2.0)

CLI 0.2.0 organizes commands into three namespaces: wallet, agent, and tokens. Old flat commands (balances, prompt, status, etc.) still work as deprecated aliases.

bankr wallet — Wallet Operations

bankr agent — AI Agent Operations

bankr tokens — Token Discovery

Auth & Config Commands

Valid config keys: apiKey, apiUrl, llmKey, llmUrl

Default config location: ~/.bankr/config.json. Override with --config or BANKR_CONFIG env var.

Deprecated Aliases

Old flat commands still work but prefer the namespaced versions:

Environment Variables

Environment variables override config file values. Config file values override defaults.

LLM Gateway Commands

Core Usage

Simple Query

For straightforward requests that complete quickly:

bankr agent prompt "What is my ETH balance?"
bankr agent prompt "What's the price of Bitcoin?"

The CLI handles the full submit-poll-complete workflow automatically. You can also use the shorthand — any unrecognized command is treated as a prompt:

bankr What is the price of ETH?

Interactive Prompt

For prompts containing $ or special characters that the shell would expand:

# Interactive mode — no shell expansion issues
bankr agent prompt
# Then type: Buy $50 of ETH on Base

# Or pipe input
echo 'Buy $50 of ETH on Base' | bankr agent prompt

Conversation Threads

Continue a multi-turn conversation with the agent:

# First prompt — starts a new thread automatically
bankr agent prompt "What is the price of ETH?"
# → Thread: thr_ABC123

# Continue the conversation (agent remembers the ETH context)
bankr agent prompt --continue "And what about BTC?"
bankr agent prompt -c "Compare them"

# Resume any thread by ID
bankr agent prompt --thread thr_ABC123 "Show me ETH chart"

Thread IDs are automatically saved to config after each prompt. The --continue / -c flag reuses the last thread.

Manual Job Control

For advanced use or long-running operations:

# Submit and get job ID
bankr agent prompt "Buy $100 of ETH"
# → Job submitted: job_abc123

# Check status of a specific job
bankr agent status job_abc123

# Cancel if needed
bankr agent cancel job_abc123

LLM Gateway

The Bankr LLM Gateway is a unified API for Claude, Gemini, GPT, and other models — multi-provider access, cost tracking, automatic failover, and SDK compatibility through a single endpoint.

Base URL: https://llm.bankr.bot | Dashboard: bankr.bot/llm | API Keys: bankr.bot/api

Key Concepts

• Uses your llmKey if configured, otherwise falls back to your API key
• LLM credits (USD) and trading wallet (crypto) are completely separate balances — having crypto does NOT give you LLM credits
• New accounts start with $0 LLM credits — top up via bankr llm credits add 25 or at bankr.bot/llm?tab=credits before making any LLM calls, or you will get a 402 error
• Check credits: bankr llm credits | Top up: bankr llm credits add <amount> | Auto top-up: bankr llm credits auto --enable --amount 25 --tokens USDC
• In OpenClaw config, prefix model IDs with bankr/ (e.g. bankr/claude-sonnet-4.6). In direct API calls, use bare IDs (e.g. claude-sonnet-4.6)

Quick Commands

bankr llm models                           # List available models
bankr llm credits                          # Check credit balance
bankr llm credits add 25                   # Top up $25 credits (USDC)
bankr llm credits auto --enable --amount 25 --tokens USDC  # Auto top-up
bankr llm setup openclaw --install         # Install Bankr provider into OpenClaw
bankr llm setup claude                     # Print Claude Code env vars
bankr llm claude                           # Launch Claude Code through gateway

Model Deprecation

The gateway supports model deprecation with auto-redirect to replacement models. Deprecated models return X-Model-Deprecated and X-Model-Replacement response headers. Hard-deprecated models return HTTP 410 — update your model ID to the replacement indicated in the header.

For full details — setup paths, model list, provider config, SDK examples, key management, and troubleshooting — see:

Reference: references/llm-gateway.md

Capabilities Overview

Trading Operations

• Token Swaps: Buy/sell/swap tokens across chains
• Cross-Chain: Bridge tokens between chains
• Limit Orders: Execute at target prices
• Stop Loss: Automatic sell protection
• DCA: Dollar-cost averaging strategies
• TWAP: Time-weighted average pricing

Reference: references/token-trading.md

Portfolio Management

• Check balances across all chains (bankr wallet portfolio or GET /wallet/portfolio)
• View USD valuations with optional PnL tracking (--pnl or ?include=pnl)
• View NFT holdings (--nfts or ?include=nfts)
• Track holdings by token or chain
• Real-time price updates
• Multi-chain aggregation
• Filter by chain: bankr wallet portfolio --chain base,solana or GET /wallet/portfolio?chains=base,solana

Reference: references/portfolio.md

Market Research

• Token prices and market data
• Technical analysis (RSI, MACD, etc.)
• Social sentiment analysis
• Price charts
• Trending tokens
• Token comparisons

Reference: references/market-research.md

Transfers

• Send to addresses, ENS, or social handles
• Multi-chain support
• Flexible amount formats
• Social handle resolution (Twitter, Farcaster, Telegram)

Reference: references/transfers.md

NFT Operations

• Browse and search collections
• View floor prices and listings
• Purchase NFTs via OpenSea
• View your NFT portfolio
• Transfer NFTs
• Mint from supported platforms

Reference: references/nft-operations.md

Polymarket Betting

• Search prediction markets
• Check odds
• Place bets on outcomes
• View positions
• Redeem winnings

Reference: references/polymarket.md

Leverage Trading

• Long/short positions (up to 50x crypto, 100x forex/commodities)
• Crypto, forex, and commodities
• Stop loss and take profit
• Position management via Avantis on Base

Reference: references/leverage-trading.md

Token Deployment

• EVM (Base): Deploy ERC20 tokens via Clanker with customizable metadata and social links
• Solana: Launch SPL tokens via Raydium LaunchLab with bonding curve and auto-migration to CPMM
• Creator fee claiming on both chains
• Fee Key NFTs for Solana (50% LP trading fees post-migration)
• Optional fee recipient designation with 99.9%/0.1% split (Solana)
• Both creator AND fee recipient can claim bonding curve fees (gas sponsored)
• Optional vesting parameters (Solana)
• Rate limits: 1/day standard, 10/day Bankr Club (gas sponsored within limits)

Reference: references/token-deployment.md

Automation

• Limit orders
• Stop loss orders
• DCA (dollar-cost averaging)
• TWAP (time-weighted average price)
• Scheduled commands

Reference: references/automation.md

Arbitrary Transactions

• Submit raw EVM transactions with explicit calldata
• Custom contract calls to any address
• Execute pre-built calldata from other tools
• Value transfers with data

Reference: references/arbitrary-transaction.md

Supported Chains

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 (walletApiEnabled, agentApiEnabled, tokenLaunchApiEnabled, 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: New keys default to readOnly: true. This filters all write tools (swaps, transfers, staking, token launches, etc.) from agent sessions. The /wallet/sign, /wallet/submit, and /wallet/transfer write endpoints return 403. Use --read-write during login or toggle in the web settings to disable. 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 /wallet/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 wallet portfolio --chain base

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

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

Portfolio Review

# Direct portfolio check (no AI agent, instant response)
bankr wallet portfolio
bankr wallet portfolio --pnl        # Include profit/loss data
bankr wallet portfolio --nfts       # Include NFT holdings
bankr wallet portfolio --all        # PnL + NFTs
bankr wallet portfolio --chain base
bankr wallet portfolio --chain base,solana
bankr wallet portfolio --json

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

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

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

Set Up Automation

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

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

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

Market Research

# Token discovery
bankr tokens search PEPE
bankr tokens info USDC

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

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

# Compare tokens
bankr agent 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 agent 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 agent status <jobId> and bankr agent cancel <jobId>.

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

Reference: references/api-workflow.md

Synchronous Endpoints (Wallet API)

For direct signing and transaction submission, use the Wallet API synchronous endpoints:

• POST /wallet/sign - Sign messages, typed data, or transactions without broadcasting
• POST /wallet/submit - Submit raw transactions directly to the blockchain
• POST /wallet/transfer - Transfer tokens with symbol resolution and multi-chain support

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)
• Programmatic token transfers

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 wallet portfolio (direct, no AI processing — hides low-value tokens by default)
• bankr wallet portfolio --pnl (include profit/loss)
• bankr wallet portfolio --nfts (include NFT holdings)
• bankr wallet portfolio --all (PnL + NFTs)
• bankr wallet portfolio --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: {...}"

Transfers (Direct)

Transfer tokens via CLI or Wallet API without AI processing:

# CLI — token symbol resolution built in
bankr wallet transfer --to vitalik.eth --token USDC --amount 50 --chain base
bankr wallet transfer --to 0x1234... --token ETH --amount 0.1

# REST API
curl -X POST "https://api.bankr.bot/wallet/transfer" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "vitalik.eth", "token": "USDC", "amount": "50", "chain": "base"}'

Sign API (Synchronous)

Direct message signing without AI processing:

# Sign a plain text message
curl -X POST "https://api.bankr.bot/wallet/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/wallet/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/wallet/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/wallet/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 agent 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 wallet portfolio) to see what's possible, then try a small $5-10 trade on Base to get familiar with the flow.

---

Profile Management

Agents can create and manage public profile pages at bankr.bot/agents. Profiles showcase project metadata, team info, token data (chart + market cap), weekly fee revenue, shipped products, and a Twitter activity feed.

Eligibility: You must have deployed a token through Bankr (Doppler or Clanker) or be a fee beneficiary on the token to create a profile. The token address is verified against your deployment history and beneficiary records.

Profile Lifecycle

1. Deploy a token through Bankr (required prerequisite) 2. Create a profile via CLI or REST API with the token address 3. Populate metadata (team, products, revenue sources) 4. Admin approval — profiles start with approved: false and become publicly visible after admin approval 5. Maintain — post project updates, keep products and revenue sources current

CLI Commands

bankr agent profile                     # View own profile
bankr agent profile create              # Interactive creation wizard
bankr agent profile create --name "My Agent" --token 0x... --twitter myagent
bankr agent profile update --description "Updated description"
bankr agent profile delete              # Delete own profile (with confirmation)
bankr agent profile add-update          # Add a project update
bankr agent profile add-update --title "v2 Launch" --content "Shipped new features"

All commands support --json for structured output (enables programmatic use).

REST API Endpoints

All endpoints require API key authentication via X-API-Key header.

Create profile:

curl -X POST "https://api.bankr.bot/agent/profile" \
  -H "X-API-Key: $BANKR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectName": "My Agent", "tokenAddress": "0x...", "description": "An AI trading agent"}'

Add a project update:

curl -X POST "https://api.bankr.bot/agent/profile/update" \
  -H "X-API-Key: $BANKR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "v2 Launch", "content": "Shipped swap optimization and new UI"}'

See references/agent-profiles.md for the full integration guide.

Agent Profiles Reference

Create and manage public profile pages at bankr.bot/agents. Profiles showcase project info, team, token data with live charts, weekly fee revenue, products, and activity.

Eligibility: You must have deployed a token through Bankr (Doppler or Clanker) or be a fee beneficiary on the token to create an agent profile. The token address is verified against your deployment and beneficiary history.

Profile Fields

CLI Usage

View Profile

bankr profile              # Pretty-printed view
bankr profile --json       # JSON output

Create Profile

# Interactive wizard
bankr profile create

# Non-interactive with flags
bankr profile create \
  --name "My Agent" \
  --description "AI-powered trading agent on Base" \
  --token 0x1234...abcd \
  --image "https://example.com/logo.png"

Update Profile

bankr profile update --description "Updated description"
bankr profile update --token 0xNEW...ADDR

Add Project Updates

Project updates appear in a timeline on the profile detail page. Capped at 50 entries (oldest are pruned).

# Interactive
bankr profile add-update

# Non-interactive
bankr profile add-update --title "v2 Launch" --content "Shipped new swap engine and portfolio dashboard"

Delete Profile

bankr profile delete   # Requires confirmation

REST API Endpoints

All endpoints under /agent/profile require API key authentication (X-API-Key header).

GET /agent/profile

Returns the authenticated user's profile.

curl "https://api.bankr.bot/agent/profile" \
  -H "X-API-Key: $BANKR_API_KEY"

POST /agent/profile

Create a new profile. Returns 409 if one already exists.

{
  "projectName": "My Agent",
  "description": "AI trading agent",
  "tokenAddress": "0x1234...abcd",
  "tokenChainId": "base",
  "tokenSymbol": "AGENT",
  "twitterUsername": "myagent",
  "teamMembers": [
    { "name": "Alice", "role": "Lead Dev", "links": [{ "type": "twitter", "url": "https://x.com/alice" }] }
  ],
  "products": [
    { "name": "Swap Engine", "description": "Optimized DEX routing", "url": "https://myagent.com/swap" }
  ],
  "revenueSources": [
    { "name": "Trading fees", "description": "0.3% on each swap" }
  ]
}

PUT /agent/profile

Update specific fields. Only include fields you want to change. Set a field to null to clear it.

{
  "description": "Updated description",
  "tokenAddress": null
}

DELETE /agent/profile

Delete the authenticated user's profile. Returns { "success": true }.

POST /agent/profile/update

Add a project update entry.

{
  "title": "v2 Launch",
  "content": "Shipped swap optimization, portfolio dashboard, and new onboarding flow."
}

Public Endpoints (No Auth Required)

Query Parameters for Listing

Approval Workflow

Profiles start with approved: false and are not publicly visible. After admin approval, the profile appears in the public listing at /agents and receives automatic market cap and revenue updates from background workers.

Auto-Populated Fields

• profileImageUrl: Auto-populated from linked Twitter profile image if no manual URL is provided
• twitterUsername: Auto-populated from linked Twitter social account
• marketCapUsd: Updated every 5 minutes by background worker (via CoinGecko)
• weeklyRevenueWeth: Updated every 30 minutes by background worker (from Doppler fee data)

LLM Usage Stats

GET /agent-profiles/:identifier/llm-usage returns public LLM usage statistics for an approved profile. Cached for 5 minutes.

Query parameters:

• days (default: 30, range: 1-90) — lookback period

Response includes:

• totals — totalRequests, totalTokens, totalInputTokens, totalOutputTokens, successRate (0-100), avgLatencyMs
• byModel — per-model breakdown with requests, totalTokens, successRate, avgLatencyMs
• daily — array of { date, requests, totalTokens } entries for charting (gaps filled with zeros)

No cost data is included (public-safe).

Tweets

GET /agent-profiles/:identifier/tweets returns up to 10 recent original tweets (excludes replies/retweets) from the profile's linked Twitter account. Cached for 10 minutes.

Response: { tweets: [{ id, text, createdAt, metrics: { likes, retweets, replies }, url }] }

Returns empty array if no Twitter account is linked or if fetch fails.

Real-Time Updates

The /agent-profiles WebSocket namespace provides live updates:

• AGENT_PROFILE_UPDATE — profile listing changes (market cap, revenue updates)
• AGENT_PROFILE_DETAIL_UPDATE — detail page changes (subscribe to a specific profile via socket.emit("subscribe", slug))

Bankr API Workflow Reference

Understanding the asynchronous job pattern for Bankr Agent API operations.

Source: Agent API Reference | Wallet API Docs

Note: This reference covers the Agent API async prompt workflow (/agent/prompt). For direct synchronous wallet operations (portfolio, transfer, sign, submit), see the Wallet API endpoints at /wallet/* documented in sign-submit-api.md, portfolio.md, and transfers.md.

Using the Bankr CLI

The CLI handles submit-poll-complete automatically. For installation and login, see the main SKILL.md.

bankr agent prompt "What is my ETH balance?"   # submit + poll + display
bankr agent status <jobId>                      # check a specific job
bankr agent cancel <jobId>                      # cancel a running job

Using the REST API Directly

Call the endpoints below with curl, fetch, or any HTTP client. All requests require an X-API-Key header.

Core Pattern: Submit-Poll-Complete

All operations follow this pattern:

1. SUBMIT  → Send prompt, get job ID
2. POLL    → Check status every 2s
3. COMPLETE → Process results

API Endpoints

POST /agent/prompt

Submit a natural language prompt to start a job.

CLI equivalent: bankr agent prompt "What is my ETH balance?"

Request:

curl -X POST "https://api.bankr.bot/agent/prompt" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is my ETH balance?"}'

Continue a conversation:

curl -X POST "https://api.bankr.bot/agent/prompt" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "And what about SOL?", "threadId": "thr_ABC123"}'

Request Body:

• prompt (string, required): The prompt to send to the AI agent (max 10,000 characters)
• threadId (string, optional): Continue an existing conversation thread. If omitted, a new thread is created.

Response (202 Accepted):

{
  "success": true,
  "jobId": "job_abc123",
  "threadId": "thr_XYZ789",
  "status": "pending",
  "message": "Job submitted successfully"
}

Error Responses:

GET /agent/job/{jobId}

Check job status and results.

CLI equivalent: bankr agent status job_abc123

Request:

curl -X GET "https://api.bankr.bot/agent/job/job_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK):

{
  "success": true,
  "jobId": "job_abc123",
  "threadId": "thr_XYZ789",
  "status": "completed",
  "prompt": "What is my ETH balance?",
  "response": "You have 0.5 ETH worth approximately $1,825.",
  "richData": [],
  "statusUpdates": [
    {"message": "Checking balances...", "timestamp": "2025-01-26T10:00:00Z"},
    {"message": "Calculating USD values...", "timestamp": "2025-01-26T10:00:02Z"}
  ],
  "createdAt": "2025-01-26T10:00:00Z",
  "completedAt": "2025-01-26T10:00:03Z",
  "processingTime": 3000
}

Error Responses:

POST /agent/job/{jobId}/cancel

Cancel a pending or processing job. Cancel requests are idempotent — cancelling an already-cancelled job returns success.

CLI equivalent: bankr agent cancel job_abc123

Request:

curl -X POST "https://api.bankr.bot/agent/job/job_abc123/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response (200 OK):

{
  "success": true,
  "jobId": "job_abc123",
  "status": "cancelled",
  "prompt": "Swap 0.1 ETH for USDC",
  "createdAt": "2025-01-26T10:00:00Z",
  "cancelledAt": "2025-01-26T10:00:05Z"
}

Error Responses:

Job Status States

Response Fields

Standard Fields

• success: Boolean, true if request succeeded
• jobId: Unique job identifier
• threadId: Conversation thread ID (reuse to continue the conversation)
• status: Current job status (pending, processing, completed, failed, cancelled)
• prompt: Original user prompt
• createdAt: ISO 8601 timestamp

Success Fields (status=completed)

• response: Natural language response text
• richData: Array of structured data objects (see Rich Data below)
• completedAt: When job finished (ISO 8601)
• processingTime: Duration in milliseconds

Progress Fields (status=processing)

• statusUpdates: Array of progress messages ({message, timestamp})
• startedAt: When processing began (ISO 8601)
• cancellable: Boolean, whether the job can still be cancelled

Error Fields (status=failed)

• error: Error message
• completedAt: When failure occurred (ISO 8601)

Cancelled Fields (status=cancelled)

• cancelledAt: When the job was cancelled (ISO 8601)

Rich Data Objects

Completed jobs may include a richData array containing structured data (e.g., token info, price quotes, charts). Each entry has:

type RichData = {
  type?: string;          // e.g., "token_info", "price_quote"
  [key: string]: unknown; // Additional structured data
};

The exact shape depends on the operation performed. The response field always contains a human-readable text summary regardless of what richData contains.

Polling Strategy

Timing

• Interval: 2 seconds between requests
• Typical duration: 30 seconds to 2 minutes
• Maximum: 5 minutes (then suggest cancellation)

Example Polling Loop

#!/bin/bash
JOB_ID="job_abc123"
MAX_ATTEMPTS=150  # 5 minutes

for i in $(seq 1 $MAX_ATTEMPTS); do
    sleep 2
    STATUS=$(curl -s "https://api.bankr.bot/agent/job/$JOB_ID" \
        -H "X-API-Key: $API_KEY" | jq -r '.status')

    case "$STATUS" in
        completed|failed|cancelled)
            break
            ;;
        *)
            echo "Polling... ($i/$MAX_ATTEMPTS)"
            ;;
    esac
done

Status Update Handling

Track what you've shown:

LAST_UPDATE_COUNT=0

while true; do
    RESULT=$(get_job_status "$JOB_ID")
    CURRENT_COUNT=$(echo "$RESULT" | jq '.statusUpdates | length')

    if [ "$CURRENT_COUNT" -gt "$LAST_UPDATE_COUNT" ]; then
        # Show new updates only
        echo "$RESULT" | jq -r ".statusUpdates[$LAST_UPDATE_COUNT:] | .[].message"
        LAST_UPDATE_COUNT=$CURRENT_COUNT
    fi

    STATUS=$(echo "$RESULT" | jq -r '.status')
    [ "$STATUS" != "pending" ] && [ "$STATUS" != "processing" ] && break

    sleep 2
done

Output Guidelines

Response Formatting

Price queries:

• Clear, direct answer
• Include symbol and price
• Example: "ETH is currently $3,245.67"

Trading confirmations:

• Confirm amounts
• Show transaction hash
• Mention gas costs if significant

Portfolio display:

• List token amounts and USD values
• Group by chain if multi-chain
• Show total portfolio value

Market analysis:

• Summarize key insights
• Highlight important data points
• Keep concise

Errors:

• Explain what went wrong clearly
• Suggest next steps
• Avoid technical jargon

Error Handling

Authentication Errors (401)

{
  "error": "Authentication required",
  "message": "API key is missing or invalid"
}

Resolution: Check API key, ensure "Wallet & Agent API" access is enabled at https://bankr.bot/api

Forbidden (403)

{
  "error": "Agent API access not enabled",
  "message": "Enable agent access for your API key"
}

Resolution: Visit https://bankr.bot/api and enable Wallet & Agent API access on your key

Rate Limiting (429)

{
  "error": "Rate limit exceeded",
  "message": "Retry after 60 seconds"
}

Resolution: Wait and retry, implement exponential backoff

Job Failures

{
  "success": true,
  "status": "failed",
  "error": "Insufficient balance for trade"
}

Resolution: Check specific error, guide user to fix

Best Practices

Submission

1. Validate input before submitting 2. Handle errors gracefully 3. Store job ID for tracking 4. Show confirmation to user

Polling

1. Use 2-second interval - Don't poll too fast 2. Show progress - Display status updates 3. Set timeout - Don't poll forever 4. Handle network errors - Retry with backoff

Completion

1. Parse response carefully 2. Check richData for structured results 3. Format output nicely 4. Save to history for reference

Error Recovery

1. Identify error type quickly 2. Provide clear explanation to user 3. Suggest fixes when possible 4. Retry intelligently

Example Workflows

Simple Balance Check

1. Submit: "What is my ETH balance?"
2. Poll every 2s (completes in ~5s)
3. Show: "You have 0.5 ETH ($1,825)"

Token Swap

1. Submit: "Swap 0.1 ETH for USDC"
2. Poll every 2s
   - Update: "Checking balance..."
   - Update: "Finding best route..."
   - Update: "Executing swap..."
3. Complete after ~45s
4. Show: "Swapped 0.1 ETH for 365 USDC"
5. Display transaction hash

Market Research

1. Submit: "Analyze ETH price"
2. Poll every 2s
   - Update: "Fetching price data..."
   - Update: "Running technical analysis..."
   - Update: "Analyzing sentiment..."
3. Complete after ~30s
4. Show formatted analysis with key metrics

Security Notes

API Key

• Never expose in client code
• Use environment variables or config.json
• Rotate periodically
• Monitor usage
• Revoke immediately if leaked at https://bankr.bot/api

Validation

• Validate user input
• Sanitize prompts
• Check amounts/addresses
• Confirm before critical operations

Error Messages

• Don't leak sensitive info
• Be helpful but not revealing
• Log internally, show safely
• Guide users constructively

---

Remember: The asynchronous pattern allows Bankr to handle complex operations that may take time, while keeping you informed of progress.

Arbitrary Transaction Reference

Submit raw EVM transactions with explicit calldata to any supported chain.

Supported Chains

JSON Format

{
  "to": "0x...",
  "data": "0x...",
  "value": "0",
  "chainId": 8453
}

Validation Rules

Prompt Examples

Submit a raw transaction:

Submit this transaction:
{
  "to": "0x1234567890abcdef1234567890abcdef12345678",
  "data": "0xa9059cbb000000000000000000000000recipient00000000000000000000000000000000000000000000000000000000000f4240",
  "value": "0",
  "chainId": 8453
}

Execute calldata on a contract:

Execute this calldata on Base:
{
  "to": "0xContractAddress...",
  "data": "0xFunctionSelector...",
  "value": "0",
  "chainId": 8453
}

Send ETH with calldata:

Submit transaction with value:
{
  "to": "0xRecipientAddress...",
  "data": "0x",
  "value": "1000000000000000000",
  "chainId": 1
}

ERC-20 transfer via calldata:

Submit this ERC-20 transfer:
{
  "to": "0xTokenContractAddress...",
  "data": "0xa9059cbb000000000000000000000000...",
  "value": "0",
  "chainId": 8453
}

Common Issues

Use Cases

• Custom contract interactions - Call any function on any contract
• Pre-built calldata execution - Execute calldata generated by other tools
• Advanced DeFi operations - Complex multi-step transactions
• Protocol integrations - Interact with protocols not yet natively supported

Best Practices

1. Verify calldata - Double-check encoding before submission 2. Test on testnet first - If possible, test transactions on testnets 3. Start with zero value - Test contract calls without sending ETH first 4. Check gas estimates - Ensure sufficient balance for gas costs 5. Verify contract addresses - Confirm target address is correct

Security Notes

• Irreversible - Blockchain transactions cannot be undone
• Verify everything - Calldata determines exactly what happens
• Trust the source - Only execute calldata from trusted sources
• Check value field - Ensure you're not sending unintended ETH
• Contract verification - Confirm the target contract is legitimate

Automation Reference

Set up automated orders and scheduled trading strategies.

Order Types

Limit Orders

Execute trade when price reaches target.

Examples:

• "Set a limit order to buy ETH at $3,000"
• "Limit order: sell BNKR when it hits $0.02"
• "Buy 1 SOL if price drops to $100"
• "Sell my PEPE at $0.000015"

Use cases:

• Buy the dip
• Take profit at target
• Enter at better price
• Exit at predetermined level

Stop Loss Orders

Automatically sell to limit losses.

Examples:

• "Set stop loss for my ETH at $2,500"
• "Stop loss: sell 50% of BNKR if it drops 20%"
• "Protect my SOL position with stop at $150"

Use cases:

• Protect gains
• Limit downside
• Risk management
• Sleep peacefully

DCA (Dollar Cost Averaging)

Invest fixed amounts at regular intervals.

Examples:

• "DCA $100 into ETH every week"
• "Set up daily $50 Bitcoin purchases"
• "Buy $25 of SOL every Monday"
• "Monthly $500 DCA into ETH"

Use cases:

• Reduce timing risk
• Build position over time
• Smooth out volatility
• Disciplined investing

Intervals:

• Hourly
• Daily
• Weekly
• Monthly

TWAP (Time-Weighted Average Price)

Spread large orders over time to reduce market impact.

Examples:

• "TWAP: buy $1000 of ETH over 24 hours"
• "Spread my sell order over 4 hours"
• "Buy 10 ETH using TWAP over next 6 hours"
• "TWAP sell 50% of position over 12 hours"

Use cases:

• Large order execution
• Reduce slippage
• Minimize market impact
• Better average price

Scheduled Commands

Run any Bankr command on a schedule.

Examples:

• "Every morning at 8am, check my portfolio"
• "Daily at 9am, check ETH price"
• "Every Monday, show me trending tokens"
• "Hourly, check my open positions"

Use cases:

• Regular monitoring
• Automated reporting
• Price alerts
• Balance checks

Managing Automations

View Active Automations

Examples:

• "Show my automations"
• "What limit orders do I have?"
• "List my active DCAs"
• "Show all scheduled commands"

Information shown:

• Order type
• Asset/pair
• Trigger condition
• Amount
• Status
• Created date

Cancel Automations

Examples:

• "Cancel my ETH limit order"
• "Stop my DCA into Bitcoin"
• "Cancel all my stop losses"
• "Remove my SOL automation"

Cancellation:

• Immediate effect
• No fees for canceling
• Can recreate anytime
• To modify an automation, cancel and recreate with new parameters

Chain Support

EVM Chains (Base, Polygon, Ethereum)

• ✅ Limit orders
• ✅ Stop loss
• ✅ DCA
• ✅ TWAP
• ✅ Scheduled commands

Solana

• ✅ Limit orders (via Jupiter Trigger)
• ✅ Stop loss (via Jupiter)
• ✅ DCA (via Jupiter)
• ⚠️ TWAP (limited support)
• ✅ Scheduled commands

Common Issues

Best Practices

Setting Up

1. Start small - Test with small amounts 2. Clear conditions - Be specific about triggers 3. Check balance - Ensure funds available 4. Set alerts - Get notified on execution 5. Review regularly - Update as market changes

Risk Management

1. Always use stop loss - Especially for leverage 2. Don't set and forget - Monitor periodically 3. Adjust targets - Update as conditions change 4. Consider gas - Factor in execution costs 5. Test first - Try one small automation first

DCA Strategy

1. Consistent amounts - Stick to the plan 2. Long timeframe - At least 3-6 months 3. Don't pause - Keep going through volatility 4. Review quarterly - Adjust if needed 5. Compound - Consider increasing over time

Limit Order Strategy

1. Realistic prices - Check historical support/resistance 2. Layered orders - Multiple orders at different prices 3. Time limits - Set expiration if needed 4. Review daily - Cancel stale orders 5. Be patient - Good prices take time

Tips for Success

Automation is Not Set-and-Forget

• Check on orders regularly
• Market conditions change
• Update targets as needed
• Cancel outdated orders

Combine Strategies

• DCA + stop loss = Protected accumulation
• Limit buy + limit sell = Range trading
• TWAP + stop loss = Large position exit

Use Alerts

• Get notified on execution
• Track automation performance
• Stay informed without constant checking
• Review execution prices

Keep It Simple

• Start with basic automations
• Add complexity gradually
• Don't over-automate
• Clear naming for tracking

Cost Considerations

Execution Costs

• Gas fees on each trigger
• Higher on Ethereum mainnet
• Very low on Base/Polygon
• Factor into profit calculations

DCA Costs

• Per-transaction gas
• Can add up with frequent DCA
• Daily DCA = 365 transactions/year
• Weekly might be more efficient

TWAP Costs

• Multiple transactions
• Total gas = intervals × gas per tx
• Balance cost vs slippage savings

Examples by Use Case

Build Long-Term Position

"DCA $200 into ETH every week for 6 months"
"Set stop loss at -30% to protect"
"Monthly review of strategy"

Take Profit Strategy

"Limit order: sell 25% at $4,000"
"Limit order: sell 25% at $4,500"
"Limit order: sell 50% at $5,000"

Downside Protection

"Stop loss at -20% for all holdings"
"Set stop loss for my ETH at $2,500"
"Stop loss: sell 50% of BNKR if it drops 20%"

Opportunistic Buying

"Buy $100 ETH if drops to $2,500"
"Buy $200 ETH if drops to $2,000"
"Buy $500 ETH if drops to $1,500"

Monitoring & Adjusting

Weekly Reviews

• Check execution history
• Adjust price targets
• Cancel outdated orders
• Review performance

Monthly Analysis

• Calculate ROI
• Compare to manual trading
• Adjust DCA amounts
• Refine strategy

Quarterly Rebalance

• Reassess allocations
• Update long-term targets
• Modify automation strategy
• Consider market changes

---

Remember: Automation is a tool to execute your strategy, not a replacement for strategy. Regular review and adjustment is key to success.

Error Handling Reference

Resolve Bankr API errors and common issues.

Authentication Errors

Symptoms

• HTTP 401 status code
• "Invalid API key" or "Unauthorized" message
• "X-API-Key header is required"

Resolution Steps

1. Install the Bankr CLI

bun install -g @bankr/cli

2. Authenticate

bankr login

Or if you already have an API key from https://bankr.bot/api:

bankr config set apiKey bk_your_actual_key_here

3. Verify Setup

bankr whoami
bankr prompt "What is my balance?"

Common API Key Issues

Job Failures

Transaction Failures

Insufficient Balance

• Error: "Insufficient balance for trade"
• Cause: Not enough tokens or gas
• Fix: Add funds or reduce amount

Token Not Found

• Error: "Token not found on [chain]"
• Cause: Wrong symbol, chain, or address
• Fix: Verify token exists, specify chain, use contract address

Slippage Exceeded

• Error: "Slippage tolerance exceeded"
• Cause: Price moved too much during execution
• Fix: Retry, increase slippage, or use smaller amount

Transaction Reverted

• Error: "Transaction reverted"
• Cause: On-chain failure (various reasons)
• Fix: Check transaction details, verify parameters

Network Congestion

• Error: "Network congestion, transaction failed"
• Cause: High network activity
• Fix: Increase gas, wait, or try L2

Market/Query Failures

Market Not Found

• Error: "Polymarket market not found"
• Cause: Market closed, wrong search terms
• Fix: Try different search, check if market exists

NFT Not Available

• Error: "NFT listing no longer available"
• Cause: NFT was sold to someone else
• Fix: Try another listing, check floor price

Rate Limit

• Error: "Rate limit exceeded"
• Cause: Too many requests in short time
• Fix: Wait 60 seconds, implement backoff

Timeout

• Error: "Job timed out"
• Cause: Operation took too long
• Fix: Simplify query, retry, or check service status

HTTP Status Codes

Network/Connection Errors

Symptoms

• "Failed to connect"
• "Network error"
• "Timeout"
• "Connection refused"

Troubleshooting

Check Internet Connection

ping -c 3 api.bankr.bot

Verify API Endpoint

curl -I https://api.bankr.bot

Check DNS Resolution

nslookup api.bankr.bot

Test with curl

curl -sf https://api.bankr.bot || echo "Connection failed"

Balance/Funding Issues

Insufficient Native Token

Symptoms:

• "Insufficient ETH for gas"
• "Not enough MATIC for transaction"
• "Insufficient SOL for fees"

Fix:

• Add native token to wallet
• Amounts needed:
• Ethereum: 0.01-0.05 ETH
• Base: 0.001-0.01 ETH
• Polygon: 1-5 MATIC
• Solana: 0.01-0.1 SOL

Insufficient Token Balance

Symptoms:

• "Insufficient [TOKEN] balance"
• "Balance too low for trade"

Fix:

• Check balance first
• Reduce trade amount
• Add more tokens

Configuration Issues

CLI Not Installed

# Install the Bankr CLI
bun install -g @bankr/cli

# Or with npm
npm install -g @bankr/cli

# Verify installation
which bankr

Not Authenticated

# Authenticate (opens browser for email/OTP flow)
bankr login

# Or set API key directly
bankr config set apiKey bk_your_key_here

# Set separate LLM key (optional, falls back to API key)
bankr config set llmKey your_llm_key_here

# Verify
bankr whoami

Config is stored at ~/.bankr/config.json. View current values with bankr config get.

REST API Authentication

If using the API directly without the CLI, test your key with:

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

Set BANKR_API_KEY (and optionally BANKR_LLM_KEY for the LLM gateway) as environment variables.

User-Friendly Error Messages

Template

[What went wrong]

This usually means: [Explanation]

To fix this:
1. [Step 1]
2. [Step 2]
3. [Step 3]

Need help? Visit https://bankr.bot/api

Examples

Balance Error:

You don't have enough ETH to complete this trade.

This usually means: Your wallet balance is too low for the trade amount plus gas fees.

To fix this:
1. Check your balance: "What is my ETH balance?"
2. Either reduce the trade amount
3. Or add more ETH to your wallet

You currently need at least $XX.XX worth of ETH.

Token Not Found:

Couldn't find the token "XYZ" on Base.

This usually means: The token symbol is wrong, the token doesn't exist on this chain, or it hasn't been indexed yet.

To fix this:
1. Double-check the token symbol spelling
2. Try specifying the chain: "Buy XYZ on Ethereum"
3. Or use the contract address instead

Try: "Search for XYZ token" to find it

Debugging Checklist

Before reporting an issue, check:

• [ ] API key is set and correct
• [ ] Config file exists and has valid JSON
• [ ] Internet connection is working
• [ ] api.bankr.bot is reachable
• [ ] Wallet has sufficient balance (tokens + gas)
• [ ] Token/market exists on specified chain
• [ ] Command syntax is correct
• [ ] No typos in token symbols or addresses
• [ ] Recent similar operations worked

Getting Help

Check Status

# Verify authentication
bankr whoami

# Test with a simple query
bankr prompt "What is my balance?"

Gather Information

When reporting issues, include:

• Error message (exact text)
• Command that failed
• Job ID (if available)
• Timestamp
• Chain and tokens involved
• Your config (without API key)

Resources

• Agent API Reference: https://www.notion.so/Agent-API-2e18e0f9661f80cb83ccfc046f8872e3
• API Key Management: https://bankr.bot/api
• Twitter: @bankr_bot
• Telegram: @bankr_ai_bot

Prevention

Before Operating

1. Test with small amounts first 2. Verify balance before trades 3. Check token exists on chain 4. Confirm parameters are correct 5. Have enough gas for transactions

Best Practices

1. Start small and test 2. Keep some native token for gas 3. Verify addresses/symbols 4. Use limit orders for better prices 5. Monitor your automations 6. Review transactions before confirming 7. Keep API key secure

Regular Maintenance

1. Check balance weekly 2. Review open orders monthly 3. Update automation rules 4. Monitor gas costs 5. Keep config backed up

Common Mistake Patterns

Wrong Chain

• Mistake: "Buy TOKEN" (doesn't specify chain)
• Result: Token not found or wrong chain selected
• Fix: "Buy TOKEN on Base"

Insufficient Gas Buffer

• Mistake: Using all ETH in trade
• Result: No gas for future transactions
• Fix: Keep 0.01 ETH buffer

Typos in Symbols

• Mistake: "ETHE" instead of "ETH"
• Result: Token not found
• Fix: Double-check spelling

Forgetting Decimals

• Mistake: "Buy 100 ETH" (wants $100 worth)
• Result: Tries to buy 100 ETH ($300,000+)
• Fix: "Buy $100 of ETH"

No Stop Loss

• Mistake: Opening leverage without stop loss
• Result: Risk of liquidation
• Fix: Always set stop loss for leverage

Error Recovery Workflow

1. Error occurs
   ↓
2. Read error message carefully
   ↓
3. Check this guide for known issue
   ↓
4. Apply suggested fix
   ↓
5. Test with small amount
   ↓
6. If still failing:
   - Verify config
   - Test API connectivity
   - Report issue with details

---

Remember: Most errors have simple fixes. Read the error message carefully, check the basics (API key, balance, connection), and consult this guide.

Hyperliquid Reference

Trade perpetual futures, spot tokens, and equities on Hyperliquid's on-chain order book.

Overview

Hyperliquid is a high-performance L1 DEX with an on-chain order book. It supports perpetual futures (crypto, stocks, commodities), spot trading, and advanced order management.

Chain: Hyperliquid L1 (bridged via Arbitrum) Collateral: USDC Protocol: Hyperliquid

Account Structure

Perps trading requires USDC in the perps account. Bankr auto-transfers from spot to perps when needed.

Supported Assets

Prompt Examples

Open perps positions:

• "Long $100 of BTC on hyperliquid"
• "Short $50 of ETH on hyperliquid with 10x leverage"
• "Long TSLA with 5x leverage"
• "Short SOL with 20x"

Limit orders:

• "Long $100 of BTC at $60000 on hyperliquid"
• "Short ETH with a limit price of $4000"

Spot trading:

• "Buy $50 of HYPE on hyperliquid"
• "Sell 100 PURR on hyperliquid"
• "Buy $200 of HYPE at $25"

TP/SL on new positions:

• "Long BTC with 10x and take profit at $70000 and stop loss at $55000"
• "Long ETH with 200% ROE take profit"
• "Short SOL with stop loss if price increases by $2000"

TP/SL on existing positions:

• "Set take profit at $70000 on my BTC position"
• "Set SL at $55000 on my ETH position"
• "Set TP at $4000 and SL at $3000 on my ETH position"

View positions:

• "Show my hyperliquid positions"
• "What positions do I have on HL?"

Close positions:

• "Close my BTC position on hyperliquid"
• "Close 50% of my ETH position"
• "Close all my hyperliquid positions"

Manage leverage and margin:

• "Set my BTC leverage to 20x"
• "Change ETH leverage to 5x isolated"
• "Add $500 margin to my BTC position"
• "Remove $200 margin from my ETH position"

Order management:

• "Show my open orders on hyperliquid"
• "Change my BTC limit order price to $62000"
• "Cancel my BTC order on hyperliquid"
• "Cancel all my hyperliquid orders"

Balances and transfers:

• "Show my hyperliquid balances"
• "Transfer $500 from spot to perps on hyperliquid"
• "Move $200 from perps to spot"

Bridge funds:

• "Deposit $500 USDC to hyperliquid"
• "Bridge $1000 to hyperliquid from arbitrum"
• "Withdraw $500 from hyperliquid"

Market data:

• "BTC price on hyperliquid"
• "What's the funding rate for SOL?"
• "What can I trade on hyperliquid?"
• "Search for TSLA on hyperliquid"

Position Parameters

TP/SL Formats

On New Positions (all formats supported)

On Existing Positions (absolute prices only)

Bridge Operations

Deposit source chains: Arbitrum, Base, Polygon, Ethereum (auto-detected based on balances)

Margin Modes

Funding Rates

• Charged every 8 hours
• Longs pay shorts (or vice versa) depending on rate
• Check with: "What's the funding rate for BTC on hyperliquid?"
• Can erode profits on long-held positions

Common Issues

HIP-3 Assets (Stocks, RWAs)

Hyperliquid supports equities and real-world assets via HIP-3 builder-deployed dexes:

• Trade stocks like TSLA, AAPL, NVDA as perpetual futures
• Same tools and workflow as crypto perps
• Dex abstraction is enabled automatically on first trade
• Search with: "Search for TSLA on hyperliquid" or "What stocks can I trade on hyperliquid?"

Trading Flow

1. Check balances — "Show my hyperliquid balances" 2. Bridge if needed — "Deposit $500 USDC to hyperliquid" 3. Open position — "Long $100 of BTC on hyperliquid with 10x" 4. Set risk management — "Set TP at $70000 and SL at $55000 on my BTC position" 5. Monitor — "Show my hyperliquid positions" 6. Close — "Close my BTC position on hyperliquid" 7. Withdraw — "Withdraw $500 from hyperliquid"

Risk Warnings

• Leverage amplifies both gains and losses
• Positions can be liquidated if margin is insufficient
• 50x leverage means 2% price move = 100% gain/loss
• Funding rates can erode profits on long-held positions
• Bridge deposits/withdrawals take a few minutes to process

Leverage Trading Reference

Trade with leverage using Avantis perpetuals on Base.

Overview

Avantis offers long/short positions on crypto, forex, and commodities via perpetuals on Base.

Chain: Base Protocol: Avantis

Leverage Limits

Supported Markets

Cryptocurrency

BTC, ETH, SOL, ARB, AVAX, BNB, DOGE, LINK, OP, MATIC

Forex

• EUR/USD - Euro vs US Dollar
• GBP/USD - British Pound vs US Dollar
• USD/JPY - US Dollar vs Japanese Yen
• AUD/USD - Australian Dollar vs US Dollar
• USD/CAD - US Dollar vs Canadian Dollar

Commodities

• XAU (Gold)
• XAG (Silver)
• WTI (Crude Oil)
• NATGAS (Natural Gas)

Prompt Examples

Open positions:

• "Open a 5x long on ETH with $100"
• "Short Bitcoin with 10x leverage using $50"
• "Long Gold with 2x leverage"
• "Open 3x long SOL position"

With risk management:

• "Long ETH 5x with stop loss at $3000"
• "Short BTC 10x with take profit at 20%"
• "Long SOL 3x with SL at $150 and TP at $200"
• "5x long EUR/USD with stop loss at 1.08"

View positions:

• "Show my Avantis positions"
• "What leverage trades do I have open?"
• "My open positions"
• "PnL on my ETH long"

Close positions:

• "Close my ETH long"
• "Exit all my Avantis positions"
• "Close 50% of my BTC short"
• "Take profit on my SOL position"

Position Parameters

How Leverage Works

Long Position Example

• Open 5x long ETH with $100 at $3,000
• Effective position: $500 worth of ETH
• If ETH → $3,300 (+10%): Gain $50 (50% profit)
• If ETH → $2,700 (-10%): Lose $50 (50% loss)
• If ETH → $2,400 (-20%): Position liquidated

Short Position Example

• Open 5x short BTC with $100 at $50,000
• If BTC → $45,000 (-10%): Gain $50 (50% profit)
• If BTC → $55,000 (+10%): Lose $50 (50% loss)
• If BTC → $60,000 (+20%): Position liquidated

Leverage Guidelines

Liquidation

What is liquidation?

• Position is automatically closed
• Happens when losses approach collateral amount
• You lose all collateral for that position

Liquidation Price Calculation:

• Long position: Entry price × (1 - 1/leverage)
• Short position: Entry price × (1 + 1/leverage)

Examples:

• 5x long ETH at $3,000: Liquidated ~$2,400 (-20%)
• 10x short BTC at $50,000: Liquidated ~$55,000 (+10%)
• 2x long SOL at $100: Liquidated ~$50 (-50%)

Risk Management

Stop Loss (SL)

• Set maximum acceptable loss
• Closes position automatically
• Protects from larger losses
• Recommended for all positions

Take Profit (TP)

• Set profit target
• Closes position when reached
• Locks in gains
• Good for planned exits

Position Sizing

• Start with small amounts
• Risk only 1-5% of capital per trade
• Don't use full balance as collateral
• Keep reserve for other opportunities

Funding Rates

What are funding rates?

• Periodic fee between longs and shorts
• Usually every 8 hours
• Can be positive or negative
• Affects profitability on long holds

How they work:

• If rate is positive: Longs pay shorts
• If rate is negative: Shorts pay longs
• Typically 0.01% - 0.1% per period

Impact:

• Short-term trades: Minimal
• Long holds: Can add up
• Check before opening position

Common Issues

Advanced Strategies

Hedging

• Open opposite position on same asset
• Protects against adverse moves
• Locks in current value

Scaling In/Out

• Build position gradually
• Take partial profits
• Average entry price
• Manage risk dynamically

Cross-Asset Arbitrage

• Long one asset, short related asset
• Example: Long ETH, short BTC
• Profit from spread changes
• Requires market knowledge

Best Practices

Before Opening Position

1. Check price - Confirm entry is good 2. Set stop loss - Decide max loss upfront 3. Calculate liquidation - Know your risk 4. Check funding - Consider costs 5. Have a plan - Know exit strategy

While Position Open

1. Monitor regularly - Markets move fast 2. Adjust stops - Trail profits upward 3. Watch funding - Rates can change 4. Stay informed - Follow news 5. Don't overtrade - Be patient

Closing Position

1. Take profits - Don't be greedy 2. Cut losses - Accept when wrong 3. Learn - Analyze what worked/didn't 4. Record - Keep trade journal 5. Rest - Don't immediately jump into next trade

Risk Warnings

⚠️ High Risk Activity

• Can lose entire collateral quickly
• Leverage amplifies both gains and losses
• Liquidation is permanent
• Not suitable for beginners
• Only use money you can afford to lose

⚠️ Market Volatility

• Crypto is highly volatile
• Flash crashes can liquidate positions
• Weekend markets can be thin
• News can cause rapid moves

⚠️ Technical Risks

• Smart contract risk
• Oracle failures (rare)
• Network congestion
• Gas spikes on busy days

Tips for Beginners

1. Start small - Test with $10-20 2. Low leverage - Use 2-3x maximum 3. Always use stop loss - Non-negotiable 4. Close daily - Don't hold overnight initially 5. Paper trade first - Practice without real money 6. Learn from losses - They will happen 7. Don't revenge trade - Take breaks after losses

Tips for Experienced Traders

1. Manage multiple positions - Diversify leverage exposure 2. Use TP/SL ratios - 2:1 or 3:1 reward:risk minimum 3. Consider funding - Factor into long-term holds 4. Scale positions - Don't go all-in at once 5. Hedge strategically - Use shorts to protect longs 6. Monitor correlation - Related assets move together 7. Take regular profits - Lock in winners

Resources

• Avantis Documentation: https://docs.avantisfi.com/
• Funding Rate History: Plan long-term holds
• Market Statistics: Analyze trading data
• Liquidation Calculator: Estimate risk

---

Remember: Leverage trading is a tool, not a get-rich-quick scheme. Most traders lose money. Start small, learn continuously, and never risk more than you can afford to lose.

LLM Gateway Reference

The Bankr LLM Gateway is a unified API for Claude, Gemini, GPT, and other models. It provides multi-provider access, cost tracking, automatic failover, and SDK compatibility through a single endpoint.

Base URL: https://llm.bankr.bot

The gateway accepts both https://llm.bankr.bot and https://llm.bankr.bot/v1 — it normalizes paths automatically. Works with both OpenAI and Anthropic API formats.

Authentication

The gateway uses your LLM key for authentication. The key resolution order:

1. BANKR_LLM_KEY environment variable 2. llmKey in ~/.bankr/config.json 3. Falls back to your Bankr API key (BANKR_API_KEY / apiKey)

Most users only need a single key for both the agent API and the LLM gateway. Set a separate LLM key only if your keys have different permissions or rate limits.

Dashboard: Manage usage, credits, and auto top-up at bankr.bot/llm. Top up credits at bankr.bot/llm?tab=credits. Generate and configure API keys at bankr.bot/api.

Setting the LLM Key

Via CLI:

bankr login --llm-key YOUR_LLM_KEY            # during login
bankr config set llmKey YOUR_LLM_KEY           # after login

Via environment variable:

export BANKR_LLM_KEY=your_llm_key_here

Verify:

bankr config get llmKey

Available Models

# Fetch live model list from the gateway
bankr llm models

Credits

New wallets start with $0 LLM credits. Top up via CLI (bankr llm credits add 25) or at bankr.bot/llm?tab=credits before your first LLM call. Without credits, all gateway requests return HTTP 402.

Check your LLM gateway credit balance:

bankr llm credits

Top up credits from your wallet:

bankr llm credits add 25                   # Add $25 credits (USDC default)
bankr llm credits add 50 --token 0x...     # Add $50 from a specific token
bankr llm credits add 25 -y                # Skip confirmation prompt

Configure automatic top-up so credits never run out:

bankr llm credits auto                     # View current auto top-up config
bankr llm credits auto --enable --amount 25 --threshold 5 --tokens USDC
bankr llm credits auto --disable

When credits are exhausted, gateway requests will fail with HTTP 402.

LLM credits vs trading wallet: These are completely separate balances on the same account and API key. Your trading wallet (ETH, SOL, USDC) is for on-chain transactions. LLM credits (USD) are for gateway API calls. Having crypto does NOT give you LLM credits.

LLM Gateway Setup

If the user already has a Bankr account, they just need to configure the gateway. If not, they need to create one first.

Have Bankr Account

1. Get an API key with LLM Gateway enabled:

• Have a key? Enable LLM Gateway at bankr.bot/api
• Need a key? Generate via CLI: bankr login email user@example.com → bankr login email user@example.com --code OTP --accept-terms --key-name "My Agent" --llm

2. Run: bankr llm setup openclaw --install 3. Set default model in ~/.openclaw/openclaw.json:

   { "agents": { "defaults": { "model": { "primary": "bankr/claude-sonnet-4.6" } } } }

4. Verify credits: bankr llm credits (must show > $0 — top up via bankr llm credits add 25 or at bankr.bot/llm?tab=credits) 5. Restart OpenClaw or run: openclaw gateway restart

Need Bankr Account

1. Send OTP: bankr login email user@example.com 2. Complete setup: bankr login email user@example.com --code OTP --accept-terms --key-name "My Agent" --llm

• Can also create/configure keys at bankr.bot/api

3. Top up credits: bankr llm credits add 25 or at bankr.bot/llm?tab=credits — new wallets start with $0 4. Verify: bankr llm credits (must show > $0) 5. Run: bankr llm setup openclaw --install 6. Set default model in ~/.openclaw/openclaw.json (see above) 7. Restart OpenClaw or run: openclaw gateway restart

Model names: In OpenClaw, prefix with bankr/ (e.g. bankr/claude-sonnet-4.6). In direct API calls, use bare IDs (e.g. claude-sonnet-4.6).

For the full 4-path setup guide (including users who don't have OpenClaw yet), see https://docs.bankr.bot/llm-gateway/openclaw

Separate LLM and Agent API Keys

By default, one key is used for both. To use separate keys:

bankr config set llmKey YOUR_LLM_KEY           # after login
bankr login email user@example.com --llm-key YOUR_LLM_KEY  # during login

Key resolution: BANKR_LLM_KEY env var → llmKey in config → falls back to API key.

Key Permissions

Manage at bankr.bot/api:

Tool Integrations

OpenClaw

Auto-install the Bankr provider into your OpenClaw config:

# Write config to ~/.openclaw/openclaw.json
bankr llm setup openclaw --install

# Preview the config without writing
bankr llm setup openclaw

This writes the following provider config (with your key and all available models):

{
  "models": {
    "providers": {
      "bankr": {
        "baseUrl": "https://llm.bankr.bot",
        "apiKey": "your_key_here",
        "api": "openai-completions",
        "models": [
          { "id": "claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "api": "anthropic-messages" },
          { "id": "claude-haiku-4.5", "name": "Claude Haiku 4.5", "api": "anthropic-messages" },
          { "id": "gemini-3-flash", "name": "Gemini 3 Flash" },
          { "id": "gpt-5.2", "name": "GPT 5.2" }
        ]
      }
    }
  }
}

Claude models are automatically configured with "api": "anthropic-messages" per-model overrides while all other models use the default "api": "openai-completions".

To use a Bankr model as your default in OpenClaw, add to openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "bankr/claude-sonnet-4.6"
      }
    }
  }
}

Claude Code

Two ways to use Claude Code with the gateway:

Option A: Launch directly (recommended)

# Launch Claude Code through the gateway
bankr llm claude

# Pass any Claude Code flags through
bankr llm claude --model claude-sonnet-4.6
bankr llm claude --allowedTools Edit,Write,Bash
bankr llm claude --resume

All arguments after claude are forwarded to the claude binary. The CLI sets ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN automatically from your config (using llmKey if set, otherwise apiKey).

Option B: Set environment variables

# Print the env vars to add to your shell profile
bankr llm setup claude

This outputs:

export ANTHROPIC_BASE_URL="https://llm.bankr.bot"
export ANTHROPIC_AUTH_TOKEN="your_key_here"

Add these to ~/.zshrc or ~/.bashrc so all Claude Code sessions use the gateway.

OpenCode

# Auto-install Bankr provider into ~/.config/opencode/opencode.json
bankr llm setup opencode --install

# Preview without writing
bankr llm setup opencode

Cursor

# Get step-by-step setup instructions with your API key
bankr llm setup cursor

The setup adds your key as the OpenAI API Key, sets https://llm.bankr.bot/v1 as the base URL override, and registers the available model IDs. When the base URL override is enabled, all model requests go through the gateway.

Direct SDK Usage

The gateway is compatible with standard OpenAI and Anthropic SDKs — just override the base URL.

curl (OpenAI format)

curl -X POST "https://llm.bankr.bot/v1/chat/completions" \
  -H "Authorization: Bearer $BANKR_LLM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

curl (Anthropic format)

curl -X POST "https://llm.bankr.bot/v1/messages" \
  -H "x-api-key: $BANKR_LLM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

OpenAI SDK (Python)

from openai import OpenAI

client = OpenAI(
    base_url="https://llm.bankr.bot/v1",
    api_key="your_bankr_key",
)

response = client.chat.completions.create(
    model="claude-sonnet-4.6",
    messages=[{"role": "user", "content": "Hello"}],
)

OpenAI SDK (TypeScript)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://llm.bankr.bot/v1",
  apiKey: "your_bankr_key",
});

const response = await client.chat.completions.create({
  model: "gemini-3-flash",
  messages: [{ role: "user", content: "Hello" }],
});

Anthropic SDK (Python)

from anthropic import Anthropic

client = Anthropic(
    base_url="https://llm.bankr.bot",
    api_key="your_bankr_key",
)

message = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

Model Deprecation

The gateway supports model deprecation with automatic redirect to replacement models:

• Soft-deprecated models still work but return X-Model-Deprecated: true and X-Model-Replacement: <new-model-id> response headers. Migrate to the replacement model at your earliest convenience.
• Hard-deprecated models return HTTP 410 (Gone) with the replacement model in the X-Model-Replacement header. Update your model ID to continue.

Check bankr llm models for current model status and replacement mappings.

Troubleshooting

401 Unauthorized

• Verify key is set: bankr config get llmKey or echo $BANKR_LLM_KEY
• Check for leading/trailing spaces
• Ensure the key hasn't expired

402 Payment Required

• Credits exhausted: bankr llm credits shows $0.00
• Top up via CLI: bankr llm credits add 25 or at bankr.bot/llm?tab=credits — this is the most common error for new users
• Set up auto top-up to prevent this: bankr llm credits auto --enable --amount 25 --threshold 5 --tokens USDC
• New wallets start with $0 — you must add credits before first use
• LLM credits are separate from your trading wallet balance

Model not found

• Use exact model IDs (e.g., claude-sonnet-4.6, not claude-3-sonnet)
• Check available models: bankr llm models

Claude Code not found

• bankr llm claude requires Claude Code to be installed separately
• Install: https://docs.anthropic.com/en/docs/claude-code

Slow responses

• Try claude-haiku-4.5 or gemini-3-flash for faster responses
• The gateway has automatic failover — temporary slowness usually resolves itself

---

Documentation: https://docs.bankr.bot/llm-gateway/overview

Market Research Reference

Research tokens and analyze market data using Bankr's AI-powered analysis.

Capabilities

• Token search across chains
• Price and market data
• Technical analysis
• Social sentiment analysis
• Price charts
• Trending tokens
• Token comparisons

Prompt Examples

Price queries:

• "What's the price of ETH?"
• "How much is Bitcoin worth?"
• "Current price of BNKR"
• "Price of SOL in USD"

Market data:

• "Show me ETH market data"
• "What's the market cap of BNKR?"
• "Trading volume for Bitcoin"
• "SOL fully diluted valuation"

Technical analysis:

• "Do technical analysis on ETH"
• "Show RSI for Bitcoin"
• "Is ETH overbought?"
• "Support and resistance levels for BTC"
• "Moving averages for SOL"

Sentiment analysis:

• "What's the sentiment on ETH?"
• "Is the community bullish on SOL?"
• "Twitter sentiment for PEPE"
• "Social metrics for DOGE"

Charts:

• "Show me ETH price chart"
• "Generate BTC chart for last week"
• "30-day price chart for BNKR"

Discovery:

• "What tokens are trending?"
• "Show top gainers today"
• "Top losers in the last 24 hours"
• "New tokens on Base"

Comparisons:

• "Compare ETH vs SOL"
• "Which is better: MATIC or ARB?"
• "Show differences between UNI and AAVE"

Data Available

Price Data

• Current USD price
• 24h / 7d / 30d change
• All-time high/low
• Historical prices

Market Metrics

• Market cap
• Fully diluted valuation (FDV)
• 24h trading volume
• Circulating supply
• Total supply
• Max supply
• Number of holders

Technical Indicators

• RSI (Relative Strength Index)
• MACD (Moving Average Convergence Divergence)
• Moving averages (50-day, 200-day)
• Support/resistance levels
• Bollinger Bands
• Volume analysis

Social Metrics

• Twitter mentions
• Community sentiment
• Social volume
• Influencer activity

Supported Chains

Token research works across:

• Base
• Polygon
• Ethereum
• Solana
• Unichain

Token Search

Find tokens by name, symbol, or address:

• "Search for BNKR token"
• "Find tokens called Bankr"
• "What is the contract for PEPE on Base?"
• "Token address for USDC on Polygon"

Use Cases

Before trading:

• Check current price and trends
• Analyze technical indicators
• Review sentiment

Investment research:

• Compare similar tokens
• Check market cap and volume
• Review holder distribution

Market monitoring:

• Track trending tokens
• Find top gainers/losers
• Monitor sentiment shifts

Limitations

• Historical data limited to available timeframes
• Sentiment based on public social data
• New tokens may have limited data
• Analysis is informational, not investment advice
• Some metrics may not be available for all tokens

Best Practices

1. Cross-reference - Check multiple metrics 2. Context matters - Consider overall market conditions 3. Volume - Low volume tokens have less reliable data 4. New tokens - Be cautious with recently launched tokens 5. DYOR - Use as one of many research tools

NFT Operations Reference

Browse, purchase, and manage NFTs across chains via OpenSea integration.

Supported Chains: Base, Ethereum, Polygon

Operations

• Browse - Search NFT collections
• View Listings - Find best deals and floor prices
• Buy - Purchase NFTs from marketplace listings
• View Holdings - Check your NFT portfolio
• Transfer - Send NFTs to another wallet
• Mint - Mint from supported platforms (Manifold, SeaDrop)

Prompt Examples

Browse NFTs:

• "Find NFTs from the Bored Ape collection"
• "Show me trending NFT collections"
• "Search for Pudgy Penguins NFTs"
• "What are the top NFT collections on Base?"

View listings:

• "What's the floor price for Pudgy Penguins?"
• "Show cheapest NFTs in Azuki collection"
• "List all available Bored Apes under 50 ETH"
• "Show me the rarest items in [collection]"

Buy NFTs:

• "Buy the cheapest Bored Ape"
• "Purchase this NFT: [OpenSea URL]"
• "Buy Pudgy Penguin #1234"
• "Get the floor Azuki"

View holdings:

• "Show my NFTs"
• "What NFTs do I own on Ethereum?"
• "My NFT collection on Base"
• "Show all my Pudgy Penguins"

Transfer NFTs:

• "Send my Bored Ape #123 to 0x..."
• "Transfer Pudgy Penguin to vitalik.eth"
• "Send NFT to @friend"

Minting:

• "Mint from [Manifold link]"
• "Mint 5 NFTs from this collection"

Collection Resolution

Bankr resolves common names and abbreviations:

Chain Considerations

Ethereum

• Most valuable blue-chip collections
• Highest liquidity
• Expensive gas fees
• Established marketplace

Base

• Growing NFT ecosystem
• Very low gas fees
• Newer collections
• Good for emerging artists

Polygon

• Gaming and metaverse NFTs
• Low gas fees
• Good for frequent trading
• Strong gaming communities

OpenSea Integration

Bankr uses OpenSea's marketplace:

• Real-time floor prices
• Verified collections
• Direct purchase links
• Rarity data
• Collection stats

Common Issues

Safety Tips

1. Verify collection - Check official links and social media 2. Check floor price - Avoid overpaying, compare to floor 3. Verified badge - Look for OpenSea verified collections 4. Gas costs - Factor in gas, especially on Ethereum 5. Research - DYOR on collection before buying 6. Scams - Be wary of too-good-to-be-true deals 7. Contract address - Verify it matches official contract

NFT Portfolio

View your holdings:

• Total NFT count by chain
• Estimated floor value
• Collection breakdown
• Recently acquired
• Rarest pieces

Minting

For supported mint platforms:

• Manifold mints
• SeaDrop protocol
• Direct contract mints (if supported)

Provide the mint page URL and Bankr handles the transaction.

Best Practices

1. Start small - Learn with cheaper NFTs first 2. Research collections - Check roadmap and community 3. Compare prices - Look at recent sales and floor 4. Gas timing - Mint/buy during low gas periods 5. Hold long-term - Most value comes from holding 6. Diversify - Don't put everything in one collection

Polymarket Reference

Interact with Polymarket prediction markets.

Overview

Polymarket is a decentralized prediction market where users can search markets, view odds, place bets, and manage positions.

Chain: Polygon (uses USDC.e for betting)

Prompt Examples

Search markets:

• "Search Polymarket for election markets"
• "What prediction markets are trending?"
• "Find markets about crypto"
• "Show Polymarket sports markets"

Check odds:

• "What are the odds Trump wins the election?"
• "Check the odds on the Eagles game"
• "Polymarket odds for ETF approval"
• "What's the probability of [event]?"

Place bets:

• "Bet $10 on Yes for Trump winning"
• "Place $5 on the Eagles to win"
• "Buy $20 of Yes shares on [market]"
• "Bet on No for [event]"

View positions:

• "Show my Polymarket positions"
• "What bets do I have active?"
• "My Polymarket portfolio"

Redeem winnings:

• "Redeem my Polymarket positions"
• "Cash out my resolved bets"
• "Claim my winnings"

How Betting Works

Share-Based System

• You buy shares of "Yes" or "No" outcomes
• Share price reflects market probability
• $0.60 = 60% chance according to market
• $0.20 = 20% chance
• If your outcome wins, shares pay $1.00 each
• Profit = $1.00 - purchase price (per share)

Example

Bet $10 on "Yes" at $0.60 price:

• Receive: ~16.67 shares
• If Yes wins: Get $16.67 (profit: $6.67)
• If No wins: Lose $10

Return on Investment

• Better odds (lower price) = higher potential return
• Price $0.10 → 10x return if wins
• Price $0.90 → 1.11x return if wins

Auto-Bridging

If you don't have USDC on Polygon:

• Bankr automatically bridges from another chain
• Uses your available stablecoins (USDC/USDT)
• Optimizes for lowest fees
• Typically completes in minutes

Market Types

Market Phases

Active Markets

• Open for betting
• Prices fluctuate with news
• Can buy or sell shares

Closed Markets

• No new bets accepted
• Outcome determined
• Awaiting resolution

Resolved Markets

• Outcome confirmed
• Winners can redeem
• Losers get nothing

Common Issues

Tips for Success

Research

1. Read market details carefully 2. Check resolution criteria 3. Review similar past markets 4. Follow news about the event

Strategy

1. Start small - Test with small amounts 2. Diversify - Spread risk across markets 3. Think probability - If you think real odds > market odds, bet Yes 4. Sell early - Can sell shares before resolution 5. Compound - Reinvest winnings

Timing

1. Early bets - Better odds before news breaks 2. React fast - Odds change quickly with news 3. Redeem promptly - Claim winnings soon after resolution

Risk Management

1. Never bet more than you can afford to lose 2. Understand the outcome criteria 3. Consider worst-case scenarios 4. Don't let emotions drive decisions 5. Set a budget and stick to it

Market Liquidity

• High liquidity - Easy to buy/sell, stable prices
• Low liquidity - Harder to exit, price slippage
• Check volume before large bets
• Popular markets have better liquidity

Resolution Process

1. Event occurs - Real-world outcome determined 2. Market closes - No more betting 3. Resolution - Polymarket resolves via UMA oracle based on outcome criteria 4. Winners paid - Shares worth $1 each 5. Losers - Shares become worthless

Advanced Features

Selling Shares

• Can sell before resolution
• Lock in profits or cut losses
• Price depends on current odds

Partial Positions

• Don't have to go all-in
• Can build position over time
• Average your entry price

Market Making

• Provide liquidity to earn fees
• Advanced strategy
• Requires understanding of odds

Responsible Betting

• Set limits before you start
• Don't chase losses
• Take breaks
• Betting is not guaranteed profit
• Only use money you can afford to lose

Best Practices

1. Read carefully - Understand resolution criteria 2. Check sources - Official resolution sources 3. Start small - Learn with small bets 4. Track record - Keep notes on your bets 5. Stay informed - Follow news about your markets 6. Redeem quickly - Don't leave money on table

Portfolio Reference

Query token balances and portfolio across all supported chains.

CLI Commands

bankr wallet portfolio                    # Full portfolio (hides tokens under $1)
bankr wallet portfolio --pnl              # Include profit/loss data
bankr wallet portfolio --nfts             # Include NFT holdings
bankr wallet portfolio --all              # PnL + NFTs
bankr wallet portfolio --chain base       # Filter by chain
bankr wallet portfolio --chain base,solana  # Multiple chains
bankr wallet portfolio --json             # Raw JSON output

REST API

# Basic portfolio
curl -s "https://api.bankr.bot/wallet/portfolio" \
  -H "X-API-Key: $API_KEY"

# With PnL and NFTs (progressive loading)
curl -s "https://api.bankr.bot/wallet/portfolio?include=pnl,nfts" \
  -H "X-API-Key: $API_KEY"

# Filter by chain
curl -s "https://api.bankr.bot/wallet/portfolio?chains=base,solana" \
  -H "X-API-Key: $API_KEY"

Deprecation notice: GET /agent/balances still works but is deprecated. Use GET /wallet/portfolio instead.

The /wallet/portfolio endpoint is a read endpoint — any valid API key with a wallet can access it (no feature flags required).

Supported Chains

All chains: Base, Polygon, Ethereum, Unichain, Solana, World Chain, Arbitrum, BNB Chain

Prompt Examples

Full portfolio:

• "Show my portfolio"
• "What's my total balance?"
• "How much crypto do I have?"
• "Portfolio value"
• "What's my net worth?"

Chain-specific:

• "Show my Base balance"
• "What tokens do I have on Polygon?"
• "Ethereum portfolio"
• "Solana holdings"

Token-specific:

• "How much ETH do I have?"
• "What's my USDC balance?"
• "Show my ETH across all chains"
• "BNKR balance"

Features

• USD Valuation: All balances include current USD value
• PnL Tracking: Profit/loss data via --pnl or ?include=pnl
• NFT Holdings: View NFTs via --nfts or ?include=nfts
• Progressive Loading: Request only the data you need with ?include= parameters
• Multi-Chain Aggregation: See the same token across all chains
• Real-Time Prices: Values reflect current market prices
• Comprehensive View: Shows all tokens with meaningful balances

Common Tokens Tracked

• Stablecoins: USDC, USDT, DAI
• Blue Chips: ETH, WETH, WBTC
• DeFi: UNI, AAVE, LINK, COMP, CRV
• Memecoins: DOGE, SHIB, PEPE, BONK
• Project tokens: BNKR, ARB, OP, MATIC

Use Cases

Before trading:

• "Do I have enough ETH to swap for 100 USDC?"
• "Check if I have MATIC for gas on Polygon"

Portfolio review:

• "What's my largest holding?"
• "Show portfolio breakdown by chain"
• "What percentage of my portfolio is stablecoins?"

After transactions:

• "Did my ETH arrive?"
• "Show my new BNKR balance"
• "Verify the swap completed"

Output Format

Portfolio responses typically include:

• Token name and symbol
• Amount held
• Current USD value
• Chain location
• Price per token
• 24h price change

Notes

• Portfolio queries are read-only (no transactions) — any valid API key works
• Shows balance of connected wallet address
• Tokens valued under $1 are hidden by default in CLI output
• Includes native tokens (ETH, MATIC, SOL) and ERC20/SPL tokens
• PnL and NFT data use progressive loading — only fetched when requested, keeping base queries fast

Safety & Access Control Reference

Comprehensive safety guidance for building agents and integrations with the Bankr API and CLI. Covers API key types, access controls, wallet separation, rate limits, and operational best practices.

API Key Types & Separation

Bankr uses a single key format (bk_...) with capability flags that control what each key can access. You can optionally configure a separate key for the LLM Gateway.

Capability Flags

Each API key has independent toggles managed at bankr.bot/api:

A single key can have multiple capabilities enabled (e.g., both Agent API and LLM Gateway).

Agent API Key vs LLM Gateway Key

For most users, one key works for both the Agent API and LLM Gateway. However, you can configure a separate LLM key when you want different permissions or rate limits for each:

When to use separate keys:

• Your agent API key is read-only but your LLM key needs no such restriction (LLM calls are inherently read-only)
• You want to revoke LLM access without affecting agent operations (or vice versa)
• Different keys for different team members or environments

Setting a separate LLM key:

bankr login --api-key bk_AGENT_KEY --llm-key bk_LLM_KEY   # during login
bankr config set llmKey bk_LLM_KEY                         # after login

For full LLM Gateway setup details, see llm-gateway.md.

API Key Access Control

Bankr API keys support granular access control configured at bankr.bot/api. Two key security features: read-only mode and IP whitelisting.

Read-Only API Keys

When an API key has readOnly: true, all write tools are filtered from the agent session. The agent receives a system directive explaining the restriction and will inform users accordingly.

Behavior by endpoint:

403 error responses:

For /agent/sign:

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

For /agent/submit:

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

Write tool categories filtered in read-only mode:

The agent receives a system directive and will explain the restriction if a user requests a write operation:

"This session has READ-ONLY API access. You can retrieve information (balances, prices, analytics, portfolio data, market research) but CANNOT execute any transactions."

IP Whitelisting

API keys support an allowedIps whitelist. When configured, requests from non-whitelisted IPs are rejected at the authentication layer before reaching any endpoint.

• Empty array ([]) = all IPs allowed (default)
• Non-empty array = only listed IPs can use the key

403 error response:

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

Configuring Access Control

Manage API key settings at bankr.bot/api:

CLI Security

The Bankr CLI (@bankr/cli) stores credentials locally and provides its own safety considerations alongside the REST API.

Credential Storage

The CLI stores keys in ~/.bankr/config.json:

{
  "apiKey": "bk_...",
  "llmKey": "bk_...",
  "apiUrl": "https://api.bankr.bot",
  "llmUrl": "https://llm.bankr.bot"
}

Safety rules for CLI credentials:

• Add ~/.bankr/ to your global .gitignore — never commit this directory
• On shared machines, restrict file permissions: chmod 600 ~/.bankr/config.json
• Use bankr logout to clear stored credentials when done on a shared machine
• For CI/CD, prefer environment variables (BANKR_API_KEY, BANKR_LLM_KEY) over config files

Non-Interactive Login

When running the CLI in automated scripts or AI agent environments where interactive prompts aren't possible:

# Direct key login — no prompts
bankr login --api-key bk_YOUR_KEY

# With separate LLM key
bankr login --api-key bk_AGENT_KEY --llm-key bk_LLM_KEY

# Verify it worked
bankr whoami

CLI vs REST API Access Controls

Access controls (read-only, IP whitelist) apply identically whether you use the CLI or REST API — they are enforced server-side on the API key itself. The CLI is a convenience wrapper; it submits the same requests as direct API calls.

# These two are equivalent — same access controls apply
bankr prompt "What is my balance?"
curl -X POST "https://api.bankr.bot/agent/prompt" \
  -H "X-API-Key: bk_YOUR_KEY" \
  -d '{"prompt": "What is my balance?"}'

Dedicated Agent Wallet

When building autonomous agents that execute transactions, use a separate Bankr account as the agent's wallet rather than your personal account. This limits blast radius — if an agent key is compromised or the agent misbehaves, only the dedicated wallet's funds are at risk.

Why Separate Wallets

• Limited exposure: A compromised agent key only exposes the agent wallet's funds, not your main holdings
• Clear accounting: Agent transactions are isolated from personal activity
• Independent controls: Apply stricter access controls (read-only, IP whitelist) without affecting personal use
• Easy revocation: Disable the agent account without disrupting your primary wallet

Setup Steps

1. Create a new Bankr account — Sign up at bankr.bot/api with a different email. This provisions fresh EVM and Solana wallets automatically. 2. Generate an API key — Enable Agent API access for the key 3. Configure access controls — Set readOnly, allowedIps, or both as appropriate for your use case 4. Fund with limited amounts — Transfer only what the agent needs for its operations

Recommended Funding

Fund the agent wallet with enough for gas and intended operations, not more:

Replenish periodically rather than pre-loading large amounts.

Access Control Combinations

Choose the right combination based on your agent's purpose:

Rate Limits

Daily Message Limits

The /agent/prompt endpoint enforces daily message limits per account:

429 response when limit exceeded:

{
  "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 reset window is 24 hours from the first message (rolling window), not a fixed midnight reset. The resetAt field in the response tells you exactly when the counter resets.

General API Rate Limits

For error response handling, retry strategies, and exponential backoff guidance, see error-handling.md.

Transaction Safety

Blockchain transactions are irreversible once confirmed. Key safety rules:

• Test first — Always test with small amounts before scaling up. Use Base or Polygon for low-cost testing.
• Verify recipients — Double-check addresses before transfers. See transfers.md for address resolution details.
• Gas buffer — Keep enough native tokens for gas on each chain you operate on. See the funding table above for recommended minimums.
• Wait for confirmation — Use waitForConfirmation: true with /agent/submit to ensure transactions are confirmed before proceeding. See sign-submit-api.md.
• Immediate execution — /agent/submit executes transactions immediately with no confirmation prompt. For safety with the prompt API, the AI agent may ask for confirmation on large or unusual operations.
• Understand calldata — When using arbitrary transactions, verify the calldata source is trusted. See arbitrary-transaction.md.

Key Management

Storage

• Environment variables — Store API keys in BANKR_API_KEY and LLM keys in BANKR_LLM_KEY, never in source code
• CLI config — The CLI stores keys in ~/.bankr/config.json. Ensure this directory is in .gitignore and has restricted permissions
• Never commit secrets — Add ~/.bankr/, .env, and credential files to .gitignore. Use bankr logout to clear CLI credentials on shared machines

Rotation & Revocation

• Rotate periodically — Generate new keys and deactivate old ones at bankr.bot/api. After rotating, update both env vars and CLI config (bankr login --api-key NEW_KEY)
• Revoke immediately — If any key (API or LLM) is leaked, deactivate it immediately at the dashboard
• One key per purpose — Use separate keys for different agents, environments, and services (Agent API vs LLM Gateway) so you can revoke individually without disrupting unrelated systems

Best Practices

• Prefer environment variables for server-side agents and CI/CD; use CLI config for local development
• If you use separate API and LLM keys, rotate them independently
• When revoking a compromised key, check both BANKR_API_KEY and BANKR_LLM_KEY — if the same key was used for both, both need updating

For the full API key setup and authentication workflow, see api-workflow.md.

Safety by Feature

Each feature has specific safety considerations documented in its reference file:

Checklist

Before deploying an agent or integration:

• [ ] Use a dedicated agent wallet — not your personal account
• [ ] Fund the agent wallet with limited amounts appropriate to its purpose
• [ ] Set API key to read-only if the agent only needs to query data
• [ ] Configure IP whitelisting for server-side agents with known IPs
• [ ] Store keys in environment variables (BANKR_API_KEY, BANKR_LLM_KEY), never in source code or version control
• [ ] If using the CLI, ensure ~/.bankr/ is in .gitignore and has restricted file permissions
• [ ] Use separate keys for Agent API vs LLM Gateway if they need independent access controls or revocation
• [ ] Test with small amounts on low-cost chains (Base, Polygon) before production use
• [ ] Verify recipient addresses in any transfer logic before execution
• [ ] Implement error handling for rate limits (429) and access control errors (403)
• [ ] Monitor the agent's daily message usage against your tier limit
• [ ] Review and rotate all keys (API and LLM) periodically; revoke immediately if compromised