bankr

# Bankr Bankr is an AI crypto agent that holds its own wallets. Two ways in, both using the same `bk_...` API key: - **Bankr CLI** (`@bankr/cli`, recommended). It handles login, job polling and confirmations for you. - **REST API** at `https://api.bankr.bot`. Use `/agent/*` for natural-language prompts (async jobs) and `/wallet/*` for direct, synchronous wallet operations. **Installing this skill means downloading the whole `bankr/` folder: this `SKILL.md` plus every file in [references/](references/).** A copy of `SKILL.md` alone leaves every reference link below dead. This file is the entry point. Topic detail lives in [references/](references/) (read the one for your task before acting), in the docs at [docs.bankr.bot](https://docs.bankr.bot), and in the OpenAPI spec at `https://docs.bankr.bot/openapi/api.yaml`. **Fetch the spec instead of guessing a route or payload.** It is the authoritative request/response schema and can be newer than this skill. ## Get an API key **Check whether you're already authenticated.** The host may supply the key, either as `BANKR_API_KEY` or through an egress proxy that attaches it to requests. Try `bankr whoami`, or make a request, before logging in, and never ask the user to paste a key just because the variable is empty. See [host-managed credentials](references/safety.md#host-managed-credentials-no-key-on-disk). Signing up provisions an EVM wallet (one address on every EVM chain) and a Solana wallet, so there is nothing to set up by hand. ### Headless email login (recommended for agents) Run `bankr update` first. The flow below works on @bankr/cli 0.3.38 and later. Pass `--accept-terms` and `--key-name` explicitly: from 0.3.39 a headless login accepts the Terms by itself and picks a unique key name, but on 0.3.38 a headless login without `--accept-terms` fails after the one-time code has been used, and an omitted key name defaults to `CLI-<date>`, which collides with a key created earlier that day. 1. `bankr login email <email>` sends a one-time code. 2. Ask the user for everything in **one** message: - the **code** from their email; - their go-ahead on the **[Terms of Service](https://bankr.bot/terms)**. Share the link and say plainly that step 3 accepts the Terms on their behalf. **If they decline, stop.** - any changes to the key defaults below, and a **key name** (an active key can't reuse a name). 3. Run `bankr login email <email> --code <otp> --accept-terms --key-name "<name>" [flags]`. | New-key default | Flag to change it | | --- | --- | | Wallet API on | `--no-wallet-api` | | Agent API on | `--no-agent-api` | | Token Launch API on | `--no-token-launch` | | Read-write | `--read-only` (for research or monitoring keys that must never transact) | | LLM gateway off | `--llm` | Optional hardening flags: `--allowed-ips <ips>` (IP/CIDR allowlist) and `--allowed-recipients <addresses>` (EVM/Solana send allowlist). After login, the `Features:` line shows what the key actually got. - **The code is single-use.** From 0.3.39 the CLI retries dropped connections during login by itself. If step 3 fails, restart from step 1 for a fresh code; never re-run it with the same code. - **Accounts with MFA on:** step 3 prints a `https://bankr.bot/mfa/confirm/...` link and waits up to five minutes for the user to approve with their passkey in a browser. Show the user the link, keep the command running and don't retry. If the link expires, fall back to an existing key (below). ### Other ways in - **Existing key:** `bankr login --api-key bk_...`. Add `--llm-key <key>` if the user has a separate gateway key. To mint a key in the browser, `bankr login --url` prints the [bankr.bot/api-keys](https://bankr.bot/api-keys) link. - **Sign-In with Ethereum:** `bankr login siwe --private-key 0x...`. These keys start **read-only**; pass `--read-write` to allow transactions. - Confirm the login with `bankr whoami`. ## Bankr CLI Install with `bun install -g @bankr/cli` (or `npm install -g @bankr/cli`), and update with `bankr update`. **`bankr --help` and `bankr <command> --help` are the command reference**, and [docs.bankr.bot/cli](https://docs.bankr.bot/cli) has the full guide. Command groups: `wallet` (portfolio, transfer, swap, sign, submit), `agent` (prompt, status, cancel, skills), `tokens`, `launch`, `fees`, `project` (0.3.39+), `files`, `club`, `llm`, `x402`, `webhooks`, `config`, plus `login`, `logout` and `whoami`. Behavior that `--help` doesn't spell out: - **Anything that isn't a command is a prompt.** `bankr what is the price of ETH?` is the same as `bankr agent "what is the price of ETH?"`. Named commands take precedence, so a prompt that starts with a command word (`claude`, `launch`, …) has to go through `bankr agent "..."`. - **The shell expands `$`.** In `"Buy $50 of ETH"`, `$5` expands to nothing and the agent sees `Buy 0 of ETH`. Use single quotes, pipe the prompt (`echo 'Buy $50 of ETH on Base' | bankr agent prompt`), or run `bankr agent prompt` with no argument for an interactive input. - **Threads.** Every prompt runs in a thread. `-c`/`--continue` reuses the last thread and `--thread <id>` picks one. - **Progress.** While a prompt runs, the CLI prints the agent's status lines to stderr (0.3.40+), so piped stdout carries only the response. `bankr agent status <jobId> --wait` (0.3.40+) follows an existing job. - **Max Mode.** `-m`/`--model <id>` runs the prompt on a model from the Max Mode lineup, billed from LLM credits. An ID outside the lineup is rejected with the accepted list (see [LLM gateway](#llm-gateway)). - **Non-interactive mode** (`--ni`, or `BANKR_NOT_INTERACTIVE=1`) implies `--yes` and fails fast instead of prompting. Commands that normally prompt then need their inputs as flags: - `login`: `--api-key`, `email … --code`, or `siwe --private-key`; - `launch`: `--name`; - `fees claim-wallet`: `--all`, plus `--private-key` or `BANKR_PRIVATE_KEY`; - `agent`: the prompt as an argument or on stdin. - **Config** lives in `~/.bankr/config.json`; override the path with `--config <path>` or `BANKR_CONFIG`. Environment variables win over the file: `BANKR_API_KEY`, `BANKR_API_URL`, `BANKR_LLM_KEY` (falls back to the API key) and `BANKR_LLM_URL`. Read and write values with `bankr config get|set apiKey|apiUrl|llmKey|llmUrl`. - **Deprecated aliases** still work but print a warning: `prompt`, `status`, `cancel`, `balances`, `sign`, `submit`, and `profile` / `agent profile` (now `bankr project`, 0.3.39+). On older versions `bankr project …` isn't a command, so the prompt fallthrough sends it to the agent as text; use `bankr agent profile` there. ## REST API Base URL: `https://api.bankr.bot`. Send `X-API-Key: bk_...` on every request. ### Agent API: prompts (async) 1. `POST /agent/prompt` answers `202` with `{ jobId, threadId }`. Any other status means no job was created; read the body instead of polling. 2. Poll `GET /agent/job/{jobId}` every ~2 s until `status` is `completed`, `failed` or `cancelled`. 3. `POST /agent/job/{jobId}/cancel` stops a running job. To continue a conversation, send the returned `threadId` with the next prompt. Prompts need **Bankr Club**, or **Max Mode** with LLM credits (a `maxMode` model on the request, or one saved on the wallet). Without either, the request gets `403 subscription_required` with a `remediation` list. Club allows 1,000 prompts per rolling 24 hours; Max Mode without Club allows 100. ```bash RESP=$(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 "$RESP" | jq -r '.jobId // empty') if [ -z "$JOB_ID" ]; then echo "$RESP"; exit 1; fi # no job: the body says why (403 subscription_required, 429, ...) for _ in $(seq 150); do # 150 x 2 s = 5 min, the CLI's own cap R=$(curl -s "https://api.bankr.bot/agent/job/$JOB_ID" -H "X-API-Key: $BANKR_API_KEY") case $(echo "$R" | jq -r .status) in completed|failed|cancelled) break ;; esac sleep 2 done echo "$R" | jq -r '.response // .error // .status' ``` Never poll without a `jobId`: `GET /agent/job/null` answers `404 Job not found` on every call, so an unguarded loop never ends. A job still running after five minutes keeps running; keep its `jobId` and poll again later, or cancel it. [references/agent-api.md](references/agent-api.md) covers job fields, status updates, rich data and failure handling. ### Wallet API: direct, synchronous | Endpoint | What it does | | --- | --- | | `GET /wallet/me` | Wallet addresses and account info. This is also the quickest way to check that a key works | | `GET /wallet/portfolio` | Balances, with `?include=pnl,nfts` and `?chains=base,solana` | | `POST /wallet/swap-quote` | Quotes a swap: same-chain EVM, cross-chain or Solana | | `POST /wallet/swap` | Executes a swap. The output always goes to your own wallet | | `POST /wallet/transfer` | Sends a token (by contract address) to a 0x address. Resolve an ENS name or social handle first with `GET /addresses/resolve` | | `POST /wallet/sign` | Signs a message, EIP-712 typed data or a transaction | | `POST /wallet/submit` | Broadcasts a raw transaction | - Reads (`me`, `portfolio`, `swap-quote`) work with read-only keys. `swap-quote` still needs `walletApiEnabled`. - Writes (`swap`, `transfer`, `sign`, `submit`) need `walletApiEnabled` on a read-write key. - Once a key has a recipient allowlist on either chain, `transfer` only sends to addresses on its EVM list, so a Solana-only allowlist refuses every transfer. `swap` has no recipient to check, because its output returns to you. - `submit` is also checked against the wallet's security settings: spend limits, permitted recipients and the arbitrary-contract-calls switch. Its `403` comes either with a machine-readable `errorCode` or with a plain message and no code, so handle both shapes. - These endpoints need no key: `GET /addresses/resolve`, `GET /users/search`, `GET /token-launches` and `GET /token-launches/quote-tokens?chain=<chain>`. For details, see [docs.bankr.bot/wallet-api/overview](https://docs.bankr.bot/wallet-api/overview) and [references/sign-submit-api.md](references/sign-submit-api.md). Swaps are covered in [references/token-trading.md](references/token-trading.md). ## Capabilities: where to look Most of these work by asking the agent (`bankr agent "..."` or `POST /agent/prompt`). Before anything non-trivial, read the reference for that area. | Area | Reference | Docs | | --- | --- | --- | | Swaps and bridging, including the direct swap API | [token-trading.md](references/token-trading.md) | [Swaps](https://docs.bankr.bot/features/trading/swaps), [Wallet API swap](https://docs.bankr.bot/wallet-api/swap) | | Limit, stop, DCA and TWAP orders; scheduled prompts | [automation.md](references/automation.md) | [Automations](https://docs.bankr.bot/agent/automations) | | Tokenized stocks and ETFs (Robinhood Chain, Base, Solana) | [tokenized-stocks.md](references/tokenized-stocks.md) | [Tokenized stocks](https://docs.bankr.bot/features/trading/tokenized-stocks) | | Balances, PnL, held NFTs | [portfolio.md](references/portfolio.md) | [Portfolio](https://docs.bankr.bot/features/portfolio) | | Transfers: ENS, social handles, bulk sends | [transfers.md](references/transfers.md) | [Transfers](https://docs.bankr.bot/features/transfers) | | Prices, analysis, holder lists | [market-research.md](references/market-research.md) | | | NFTs: buys, mints, offers | [nft-operations.md](references/nft-operations.md) | [NFTs](https://docs.bankr.bot/features/nfts) | | Perps on Hyperliquid and Avantis | [hyperliquid.md](references/hyperliquid.md), [leverage-trading.md](references/leverage-trading.md) | [Hyperliquid](https://docs.bankr.bot/features/hyperliquid) | | Polymarket | [polymarket.md](references/polymarket.md) | [Polymarket](https://docs.bankr.bot/features/polymarket) | | Token launches, creator fees, vesting | [token-deployment.md](references/token-deployment.md) | [Token launching](https://docs.bankr.bot/token-launching/overview) | | Project pages (`bankr project`, 0.3.39+) | [projects.md](references/projects.md) | [Projects](https://docs.bankr.bot/projects/overview) | | Wallet file storage and run outputs | [files.md](references/files.md) | [Files](https://docs.bankr.bot/agent/files) | | x402: calling and deploying paid endpoints | [x402-cloud.md](references/x402-cloud.md) | [x402 Cloud](https://docs.bankr.bot/x402-cloud/overview) | | LLM gateway, credits, Max Mode | [llm-gateway.md](references/llm-gateway.md) | [LLM gateway](https://docs.bankr.bot/llm-gateway/overview) | | Raw transactions and contract calls | [arbitrary-transaction.md](references/arbitrary-transaction.md), [sign-submit-api.md](references/sign-submit-api.md) | [Submit](https://docs.bankr.bot/wallet-api/submit) |