# Bankr Documentation > Documentation for Bankr - financial rails for self-sustaining AI agents. Launch tokens, earn fees, and pay for compute automatically. This file contains all documentation content in a single document following the llmstxt.org standard. ## Platform Overview Bankr is the financial rails for self-sustaining AI agents. Every agent gets a wallet. Launch a token. Trading fees land in the wallet. Pay LLM costs automatically from those fees. No ongoing funding required. ## The Self-Funding Flywheel ``` ┌──────────────────────────────────────┐ │ │ ▼ │ ┌─────────────┐ ┌─────────────┐ ┌───────┴───────┐ │ Agent Wallet │───▶│ Launch Token │───▶│ Trading Fees │ └──────┬──────┘ └─────────────┘ └───────┬───────┘ │ │ │ ┌─────────────┐ │ │◀────────│ Pay for │◀─────────────┘ │ │ Compute │ │ └─────────────┘ │ ▼ ┌─────────────┐ │ DeFi Tools │ │ Swaps, DCA │ │ Limit Orders│ └─────────────┘ ``` 1. **Agent gets a wallet** — Cross-chain, gas-sponsored, ready to go 2. **Launch a token** — Fair launch on Robinhood Chain, Base or Arbitrum 3. **Earn trading fees** — 95% of your token's 0.7% pool swap fee (0.665% of trading volume) flows to your agent's wallet 4. **Pay for compute** — Fees fund LLM costs via the [LLM Gateway](/llm-gateway/overview) 5. **Repeat** — The agent keeps running as long as the token has trading activity ## Agent Wallet Every agent gets a cross-chain wallet across eleven networks: Base, Ethereum, Polygon, Unichain, World Chain, Arbitrum, BNB Chain, Robinhood Chain, Arc, Solana and Hyperliquid. Bankr sponsors gas on most of the EVM chains, within a daily allowance per wallet — see [Supported Chains](/getting-started/supported-chains) for the full capability matrix. Prompting the agent through the Agent API, the CLI or the Bankr skill needs a [Bankr Club subscription](/faq/bankr-club) or [LLM credits](/llm-gateway/overview) for Max Mode. ## Token Launching Deploy a token for your agent and earn trading fees automatically. On a Doppler launch, every trade pays a **0.7% swap fee on the pool — 95% of it goes to you** — plus the hook-added **Bankr protocol fee + BNKR buyback and LP fee** (1.75% all-in): | Recipient | Share of volume | | ------------------------------------------------------------- | --------------- | | Creator (you) — 95% of the 0.7% pool swap fee | 0.665% | | LP fee (via hook) — locked liquidity in your token's own pool | 0.285% | | Bankr protocol fee (via hook) | 0.475% | | BNKR buyback (via hook) | 0.2375% | | Protocol (Doppler) | ~0.0875% | Fee schedules are fixed at launch — tokens launched earlier keep the schedule they launched with. Launch via [natural language](/token-launching/overview), the [CLI](/cli#bankr-launch), or the [Deploy API](/token-launching/api-reference/deploy-token-launch). ## Automatic LLM Payments The [LLM Gateway](/llm-gateway/overview) is an OpenAI-compatible proxy that routes to multiple providers (OpenAI, Anthropic, Google, and more). Fees earned from token trading accumulate in your agent's wallet and can be used to pay for LLM inference automatically. This closes the loop — your agent funds its own compute. ## DeFi & Trading Tools Beyond the flywheel, your agent can interact with DeFi protocols through natural language: ``` "swap $50 of ETH to USDC on base" "set a limit order to buy BNKR if it drops 10%" "start a DCA: buy $10 of ETH every day for a week" ``` Supported actions include [swaps](/features/trading/swaps), [limit orders](/features/trading/limit-orders), [stop orders](/features/trading/stop-orders), [DCA](/features/trading/dca-orders), [TWAP orders](/features/trading/twap-orders), [leveraged trading](/features/leveraged-trading), [Polymarket](/features/polymarket), [NFTs](/features/nfts), and [transfers](/features/transfers). ## Security Every transaction passes through Bankr's security layer, which checks for malicious contracts, phishing attempts, unusual transaction patterns, and prompt injection attacks. ## Integration Options | Method | Best For | Complexity | | ---------------------------------------------------- | -------------------------------------------------------------- | ---------- | | [Bankr Skill](/skills/for-other-agents/installation) | Skills-compatible agents (Claude Code, OpenClaw, Cursor, etc.) | Low | | [Bankr CLI](/cli) | Terminal-first workflows | Low | | [Claude Plugins](/claude-plugins/overview) | Claude Code users | Low | | [Agent API](/agent-api/overview) | Custom integrations | Medium | ## Next Steps - [Quick Start Guide](/getting-started/quick-start) — Get running in 5 minutes - [Token Launching](/token-launching/overview) — Deploy your agent's token - [Features Overview](/features/features-table) — See everything Bankr can do - [LLM Gateway](/llm-gateway/overview) — Route LLM traffic through Bankr --- ## Quick Start Get your AI agent trading in under 5 minutes. :::info Subscription Required Agent prompts from the skill, the Agent API, the plugins and the CLI need a [Bankr Club subscription](/faq/bankr-club) ($20/mo) or [Max Mode](/llm-gateway/max-mode) with LLM credits. The [bankr.bot](https://bankr.bot) terminal also gives you 5 free messages a day. ::: ## Option 1: Bankr Skill (Fastest) :::tip Install in your agent Tell your agent (Claude Code, OpenClaw, Cursor, or any other skills-compatible framework): > install the bankr skill from https://github.com/BankrBot/skills/tree/main/bankr ::: That's it. Your agent can now execute trades, check balances, and launch tokens. **Try it:** ``` "what's the price of ETH?" "buy $5 of BNKR on base" "what are my balances?" ``` ## Option 2: Agent API For custom integrations, use the REST API directly. ### 1. Get an API Key Sign up at [bankr.bot/api-keys](https://bankr.bot/api-keys) and generate an API key. New keys have Agent API and Wallet API access on by default. ### 2. Send a Prompt ```bash curl -X POST https://api.bankr.bot/agent/prompt \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{"prompt": "what is the price of ETH?"}' ``` ### 3. Poll for Results ```bash curl https://api.bankr.bot/agent/job/JOB_ID \ -H "X-API-Key: YOUR_API_KEY" ``` See the [Agent API documentation](/agent-api/overview) for full details. ## Option 3: Claude Plugins For Claude Code users, install the Bankr plugin: ```bash claude plugin marketplace add BankrBot/claude-plugins ``` Then install the plugin you need — see [Claude Plugins](/claude-plugins/overview) for the list. ## Option 4: Bankr CLI Install the CLI globally and start prompting from your terminal: ```bash npm install -g @bankr/cli # Log in (generates a wallet + API key) bankr login # Send a prompt bankr agent "what is the price of ETH?" ``` See the [CLI documentation](/cli) for the full command reference. ## What's Next? Now that you're connected, explore what you can do: - [Features Table](/features/features-table) — Complete list of capabilities with example prompts - [Token Launching](/token-launching/overview) — Deploy a token and earn trading fees - [Automations](/agent/automations) — Set up DCA, limit orders, and stop-losses --- ## Supported Chains Bankr supports eleven blockchain networks, each with different capabilities and trade-offs. ## Chain Overview | Chain | Type | Native Token | Gas Sponsorship | NFTs | | --------------- | ---- | ------------ | --------------- | ---- | | Base | EVM | ETH | Yes | Yes | | Ethereum | EVM | ETH | No | Yes | | Polygon | EVM | POL | Yes | Yes | | Unichain | EVM | ETH | Yes | Yes | | World Chain | EVM | ETH | Yes | No | | Arbitrum | EVM | ETH | Yes | Yes | | BNB Chain | EVM | BNB | Yes | No | | Hyperliquid | L1 | USDC | N/A | No | | Robinhood Chain | EVM | ETH | Yes | Yes | | Arc | EVM | USDC | No | No | | Solana | SVM | SOL | Limited | No | Sponsored gas covers up to 10 transactions and $3 of gas per wallet per 24 hours; past either cap, transactions pay their own gas until the window resets. Bankr doesn't sponsor raw transactions or arbitrary contract calls. ## Base Base is the primary chain for Bankr with the most features enabled. **Capabilities:** - Token swaps, routed through the 0x and Relay aggregators across Base DEXs (Uniswap, Aerodrome and more) - Token launching with fee sharing - Tokenized equities as B20 tokens (AAPL, NVDA, TSLA, and more). Requires [location verification](../features/trading/tokenized-stocks.md#location-verification); not available in the US, UK, or sanctioned regions - Limit orders, stop orders, DCA, TWAP - NFT buying, selling, and minting - Leveraged trading via Avantis (equities, commodities, forex, crypto) - Gas sponsorship for transactions **Block Explorer:** [Basescan](https://basescan.org) ## Ethereum Ethereum mainnet for high-value operations. **Capabilities:** - Token swaps, routed through the 0x and Relay aggregators - Limit orders, stop orders, DCA, TWAP - NFT buying, selling, and minting **Note:** Gas is not sponsored on Ethereum mainnet due to high costs. **Block Explorer:** [Etherscan](https://etherscan.io) ## Polygon Low-cost EVM chain with Polymarket support. **Capabilities:** - Token swaps, routed through the 0x and Relay aggregators - Limit orders, stop orders, DCA, TWAP - Polymarket betting - NFT buying, selling, and minting - Gas sponsorship for transactions **Block Explorer:** [Polygonscan](https://polygonscan.com) ## Unichain Uniswap's native L2 chain. **Capabilities:** - Token swaps, routed through the 0x and Relay aggregators - Limit orders, stop orders, DCA, TWAP - NFT buying, selling, and minting - Gas sponsorship for transactions **Block Explorer:** [Uniscan](https://uniscan.xyz) ## World Chain World Chain (Worldcoin's L2) with gas sponsorship. **Capabilities:** - Token swaps, routed through the 0x and Relay aggregators - Cross-chain swaps - Limit orders, stop orders, DCA, TWAP - Gas sponsorship for transactions **Block Explorer:** [Worldscan](https://worldscan.org) ## Arbitrum Leading Ethereum L2 with deep DeFi liquidity. **Capabilities:** - Token swaps, routed through the 0x and Relay aggregators - Cross-chain swaps - Limit orders, stop orders, DCA, TWAP - Token launching with fee sharing (WETH-paired; the launch wallet pays network gas) - Gas sponsorship for transactions other than retail token launches **Block Explorer:** [Arbiscan](https://arbiscan.io) ## BNB Chain BNB Chain (formerly Binance Smart Chain) with deep DeFi liquidity. **Capabilities:** - Token swaps, routed through the 0x and Relay aggregators - Cross-chain swaps - Limit orders, stop orders, DCA, TWAP - Gas sponsorship for transactions **Block Explorer:** [BscScan](https://bscscan.com) ## Hyperliquid High-performance on-chain order book for perpetual futures and spot trading. **Capabilities:** - Perpetual futures (crypto, stocks, commodities) - Spot trading (HYPE, PURR, and more) - Position management (leverage, margin, TP/SL) - Order management (limit, modify, cancel) - Bridge deposits from Arbitrum, Base, Polygon, Ethereum - Bridge withdrawals to Arbitrum **Note:** Hyperliquid is its own L1. Funds are bridged via Arbitrum. Deposits auto-detect the best source chain. **Explorer:** [Hyperliquid](https://app.hyperliquid.xyz) ## Robinhood Chain Robinhood's Arbitrum Orbit L2, home to tokenized stocks, ETFs, and memecoins. **Capabilities:** - Tokenized stocks and ETFs — 190+ Robinhood-issued equities (NVDA, AAPL, SPY, and more). Requires [location verification](../features/trading/tokenized-stocks.md#location-verification); not available in the US, UK, or sanctioned regions - Memecoin swaps (no verification required), routed through the 0x and Relay aggregators or directly against a fresh Bankr launch's Uniswap v4 pool - Limit orders, stop orders, DCA and TWAP on memecoins and tokenized stocks. Stock limit and stop orders need an on-chain pool for that stock to watch, and a stock order that triggers outside US market hours can't fill until the market reopens - Token launching with fee sharing - USDG (Global Dollar) as the chain's native stablecoin - Cross-chain bridging via Relay - Gas sponsorship for transactions other than retail token launches (the launch wallet pays network gas) **Block Explorer:** [Etherscan](https://robin.etherscan.io) ## Arc Circle's L1 where USDC is the native gas token (one balance, exposed both as the 18-decimal native view and the 6-decimal ERC-20 at `0x3600000000000000000000000000000000000000`). No wrapped native token exists. **Capabilities:** - Balances and USDC/ERC-20 transfers - Raw transactions, contract deploys - Token launches on Bankr Launch v3, quoted in native USDC (the chain's only launch quote) **Note:** No aggregator swaps yet (0x/Relay do not route Arc). Gas is paid in native USDC and is not sponsored. **Block Explorer:** [Arcscan](https://arc-scan.org) (third-party until Circle publishes the official explorer) ## Solana High-speed SVM chain for fast trading. **Capabilities:** - Token swaps via Jupiter aggregator - Cross-chain swaps - Limit and stop orders as Jupiter trigger orders (0.5% fee when they fill); no DCA or TWAP **Note:** Gas sponsorship is limited on Solana. **Block Explorer:** [Orb Markets](https://www.orbmarkets.io) ## Specifying Chains When sending prompts, you can specify the chain: ``` "swap $10 of USDC to ETH on base" "buy $5 of BONK on solana" "buy $20 of POL on polygon" ``` If no chain is specified, Bankr will: 1. Use the chain where your balance is highest 2. Default to Base for EVM operations 3. Default to Solana for SOL-related operations ## Cross-Chain Operations Bankr supports cross-chain swaps between EVM chains and Solana using bridge aggregators: ``` "swap $50 USDC from polygon to ETH on base" "swap $20 USDC from base to SOL on solana" ``` --- ## Bankr Agent Overview **Bankr is a web-native agent runtime with first-class crypto support.** It's more than a chatbot — it's a full execution environment you can talk to in plain English, running anywhere you message it from. You get an AI agent with a real wallet, a persistent filesystem you can browse in the UI, scheduled automations that keep running while you sleep, durable memory across conversations, programmable payments via x402, and a code sandbox for arbitrary scripts. Every surface (web, Twitter, Telegram, CLI) talks to the same agent with the same state. ## What Makes It a Runtime Bankr isn't just "an LLM wrapped around crypto APIs." It's a workspace with: - **A wallet per user** — cross-chain across Base, Ethereum, Polygon, Unichain, World Chain, Arbitrum, BNB Chain, Robinhood Chain, Arc, Solana, and Hyperliquid; gas-sponsored on supported chains. Sign, swap, bridge, deploy, transfer. - **A web-based filesystem** — every user has persistent storage (`/…` with folders, the `/.memory` folder for agent memory, a `/cli` folder for installed skills). Drag-and-drop uploads, in-browser file editing, markdown preview with internal deep links. - **Scheduled automations** — set a limit order, DCA schedule, TWAP, stop order, or any agent prompt on an interval. Runs whether or not you're online. - **Durable memory** — tell the agent once ("call me deployer", "talk like Rick Sanchez", "never confirm trades under $50") and it applies on every future turn, across every surface. Stored in `/.memory/` and editable directly. See [Memory](/agent/memory). - **x402 support (full)** — pay-per-request APIs over HTTP 402. The agent can call, host, and settle x402 endpoints. You can even create and deploy x402 endpoints entirely through chat — describe your handler and Bankr writes, builds, and ships it. See [x402 Cloud](/x402-cloud/overview). - **A code sandbox** — the `execute_cli` tool gives the agent a sandboxed terminal to run scripts, generate images, compile code, or install CLI tools on the fly. Outputs get saved back to your file storage. - **Extensibility via skills and MCPs** — install [skills](/skills/in-bankr/from-github) from GitHub, or wire up user-level MCP servers so the agent can use your tools. ## First-Class Crypto Support Not an afterthought bolted on. Every tool is crypto-native: - **Trading**: swap, bridge, limit orders, stop-loss, DCA, TWAP, leveraged positions (Hyperliquid, Avantis) - **Tokens**: fair-launch on Robinhood Chain (default), Base or Arbitrum, claim & transfer trading fees, manage clanker/doppler tokens - **Portfolio**: balances, PnL, positions across every supported chain, NFTs - **Prediction markets**: bet and manage positions on Polymarket from chat - **Arbitrary contracts**: interact with any DeFi protocol (Aave, Morpho, Uniswap, ENS, etc.) even without a dedicated tool — the agent finds the ABI, verifies the address, and calls it. It can also **deploy** a contract from compiled bytecode and **verify** its source on block explorers - **Transfers**: to ENS or Twitter handles — the agent resolves them A security layer screens every transaction for malicious contracts, phishing, unusual patterns, and prompt injection before anything signs. ## Multi-Surface, One Agent | Surface | How to reach it | | ------------- | ----------------------------------------------------------------------------------------- | | Web terminal | [bankr.bot](https://bankr.bot) | | Twitter/X | `@bankrbot` | | Telegram | `@bankr_ai_bot` | | CLI | `bankr "…"` (see [Bankr CLI](/cli)) | Whatever you set on one surface — Max Mode model, preferences, memory, files, automations — syncs to all of them because state lives on your wallet, not the client. ## Getting Started 1. Go to [bankr.bot](https://bankr.bot), sign in, and ask `what's the price of ETH?` 2. Read the [Access](/agent/access) page to pick between Bankr Club (standard model, unlimited terminal chat) or Max Mode (premium models, pay-per-token). 3. Check [Memory](/agent/memory) — the agent remembers your preferences across chats, and you can edit what it knows directly from the file explorer. :::tip Just ask Bankr understands natural language. You don't need to memorize commands — say what you want (`buy $50 of BNKR on Base`, `set up a weekly $25 DCA into ETH`, `launch a token called FROG`, `who is following me on farcaster?`) and the agent picks the right tool. ::: ## Where to Go Next - **[Memory](/agent/memory)** — how durable context works - **[Access: Bankr Club & Max Mode](/agent/access)** — pricing and model selection - **[Token Launching](/token-launching/overview)** — the self-funding flywheel for agents - **[x402 Cloud](/x402-cloud/overview)** — pay-per-request API support - **[Skills](/skills/overview)** — install Bankr in another agent, or extend your Bankr agent with new skills - **[Features Table](/features/features-table)** — the full list of built-in capabilities --- ## Memory **Bankr remembers what you tell it about yourself.** Preferences, persona, trading rules, ongoing goals — saved once, applied in every future chat. Memory lives in a hidden folder in your file storage: `/.memory/`. The agent writes to it automatically, but you can read and edit it yourself through the file explorer. ## How It Works When you tell Bankr a durable fact about yourself — how you want to be addressed, your preferred chain, "never confirm trades under $50" — it saves that fact to `/.memory/` in the same turn. On every future message (even in a brand new conversation), the saved preferences are injected back into the agent's context. You'll never have to repeat yourself. Change your mind? Tell Bankr the new preference and the old one gets replaced. ## File Layout Everything lives under `/.memory/` with a strict filename convention. **The prefix controls load behavior.** | File pattern | Load behavior | Use for | |---|---|---| | `MEMORY.md` | Always loaded (index) | Auto-generated table of contents | | `user_*.md` | **Always preloaded (content)** | Preferences, persona, addressing, trading rules | | `feedback_*.md` | Lazy (read when relevant) | Past corrections with the WHY | | `project_*.md` | Lazy | Ongoing goals, positions, strategies | | `reference_*.md` | Lazy | Pointers to external systems (dashboards, docs) | Only `user_*.md` files have their full content baked into every turn. Anything else is shown to the agent as a one-line hook in `MEMORY.md`, and it reads the full file on demand if the current conversation touches that topic. ## Editing Memory Manually You can open `/.memory/` in the file explorer and edit any file directly: 1. Open [bankr.bot](https://bankr.bot) and click the **Files** panel 2. Navigate to the `.memory` folder 3. Click a file (like `user_preferences.md`) to open it 4. Click the **Edit** button, make your changes, and save **Typical use**: you usually don't need to. The agent maintains these files as you chat. But if it got something wrong, or you want to scrub a preference, editing directly is faster than explaining the correction in chat. :::tip Filename matters If you create a new preference file yourself, make sure the name starts with `user_` (e.g. `user_risk_profile.md`, `user_wallet_nicknames.md`). Otherwise it won't be preloaded and the agent won't see it on future turns. ::: ## What Bankr Saves Good things to save: - How to address you (`call me deployer`) - Communication style (`talk like Rick Sanchez`) - Default chain / slippage / gas preferences - Trading rules (`never confirm trades under $50`) - Nicknames for your wallets - Corrections to past mistakes, with the reason Things Bankr **won't** save: - Ephemeral data (current prices, balances, transaction hashes) - Anything it can re-query via a tool (portfolio, positions) - Low-confidence guesses about you ## Persona Limits Bankr adopts most personas you ask for, but it refuses any persona that would require producing sexual content involving minors, graphic violence/gore/torture, or content planning real-world harm. If `user_*.md` contains such a rule, it's ignored and Bankr falls back to its default voice. ## Seeing What Bankr Knows Ask directly: `what do you remember about me?` — or open `/.memory/MEMORY.md` in the file explorer for the index, then drill into individual topic files. --- ## File Storage **Every Bankr wallet gets a persistent filesystem.** Docs the agent generates for you, files you upload, installed CLI skills, and your [memory](/agent/memory) all live there — browsable, editable, and shared across every surface the agent runs on. ## Tiers | | Free | Bankr Club | | --------------------- | ------------- | -------------- | | **Total storage** | 1 GB | 10 GB | | **Max per-file size** | 10 MB | 50 MB | | **Monthly downloads** | 10 GB / month | 100 GB / month | You don't need a Club subscription to use file storage — the agent can read, write, edit, and organize files on your free tier. Upgrading to Club buys more headroom, bigger single files, and ~10× the monthly download budget. Quota usage shows live in the file explorer; the agent also sees what's remaining and will warn you when you're close before attempting a large write. ## What Lives There A fresh wallet's filesystem looks like this: ``` / ← your root ├─ .memory/ ← auto-managed memory (see Memory doc) ├─ cli/ ← installed CLI skills and manifests └─ (your folders) ``` One name at the root is reserved: **`/runs`** belongs to the agent's own run store — where large tool outputs and files a sandbox script writes to its `output/` directory get parked so they don't flood the conversation. Creating a file or folder called `runs` at the root fails; the CLI and API return only a generic error for it. Everything else is yours. Anything you upload, or anything the agent generates in response to you, goes into the root (or a folder of your choosing). Examples: - A market-research report the agent wrote (`/research/eth-merge-2026.md`) - A CSV of your transactions (`/exports/portfolio-2026-04.csv`) - A PDF contract you uploaded for review - A token-launch checklist (`/launches/FROG/plan.md`) ## Using Files From Chat Just ask. The agent has dedicated tools for creating, reading, updating, searching, moving, renaming, and deleting files. ``` save this analysis as /research/unichain-vs-base.md open my DCA plan rename /portfolio-report to /reports/2026-q1 delete the draft from yesterday search my files for "hyperliquid" ``` When the agent generates a document, you'll get a clickable file link right in the chat. Click it to open the file in the built-in preview / editor. Refer to a file however is natural — a path (`/research/notes.md`) works anywhere a file ID does, on every file tool. ## Asking Questions About a File Some questions are about a file rather than about its bytes: _how many rows match_, _what's the total_, _which entries are over a threshold_. Loading a 4 MB CSV into the conversation just to count lines is slow and burns context, so the agent can instead run a small read-only pipeline against the file in a sandbox and get back only the answer — the file itself never enters the conversation. ``` how many rows in /exports/portfolio-2026-04.csv have a negative pnl? count the ERROR lines in /logs/run.log what's the highest score in /data/candidates.json? ``` This is available on **every wallet** — no Club subscription needed — and you don't have to ask for it by name; the agent reaches for it when a question is an aggregation rather than a read. What it can run: - `jq` for JSON and JSONL, plus `grep`, `egrep`, `fgrep`, `awk`, `cut`, `sort`, `uniq`, `wc`, `head`, `tail`, `cat`, `tr`, `nl`, `rev`, `paste`, `column`, `comm` - Pipes between them — but no redirection, command chaining, or command substitution, and no network access - Or a short Python 3 script (standard library only, up to 20 KB) for multi-step calculations — not available to read-only API keys - Read-only: it can never modify the file Limits: - Text files only — not PDFs, images, or archives — up to roughly **5 MB** per query. Above the limit the agent falls back to reading the file in ranges. - Answers are capped at ~8,000 characters, and the pipeline or script is cut off after 10 seconds. If you hit either, narrow the question (a count or a top-N instead of a dump). ## Uploading From the Web Open [bankr.bot](https://bankr.bot), click the **Files** panel, then drag and drop — or use the upload button. Supported types include text (`.md`, `.txt`, `.csv`, `.json`, code files), images, and PDFs. Executable formats (`.exe`, `.sh`, `.bat`, `.com`) are blocked for safety; every other common document type is allowed. ## Downloading Click any file in the explorer → **Download**. Each download counts against your monthly download budget (see Tiers above); you'll see the remaining budget in the storage panel. The monthly counter resets on the 1st of each month (UTC). ## Deleting Delete from chat (`delete /old-stuff/draft.md`) or from the file explorer's trash icon. Deletion is soft — the file is removed from listings immediately, then permanently deleted **24 hours later**. If you nuke something by accident, open a ticket at the [Bankr Help Center](https://help.bankr.bot) within that window. Once the 24-hour grace period passes, the file is gone and unrecoverable. ## Storage Quotas in Practice Quotas are checked at the moment of write. If a create or edit would push you over, the call fails fast with a message like: ``` Storage full (950MB of 1.0GB used, attempted 200MB). Join Bankr Club for 10.0GB. ``` The agent receives the same error and will relay it to you clearly so you can either delete some files, pick a smaller write, or subscribe to Club. Quotas are resolved from your current Club status at every write — subscribing to Club instantly raises your cap to 10 GB with no migration or wait. :::tip Per-file cap The 10 MB / 50 MB per-file cap is separate from the total storage budget. A single file bigger than the cap is rejected even if you have plenty of free space. Upgrading to Club raises both caps together. ::: ## From the CLI and API The [Bankr CLI](/cli) exposes the same filesystem via `bankr files` commands (list, upload, download, delete, etc.), and there's a REST API under `/user/files/*` for programmatic access from your own scripts. Because state lives on your wallet, CLI and web see exactly the same files. ## FAQ **Does the agent have automatic access to my files?** Yes. Every tool call that needs a file (reading a doc you told it to summarize, appending to a plan, attaching a CSV to a report) resolves paths against your filesystem. The agent only writes what you ask it to — it won't silently create junk files. **Can I share a file with someone else?** Not yet — file ownership is per-wallet. You can always download a file and send it yourself. **What happens to my files if I let my Club subscription lapse?** Nothing destructive. Your tier reverts to Free (1 GB / 10 MB per file / 10 GB monthly downloads), existing files are preserved, and you can still read, download, and delete any of them. Uploads that would push you back over the 1 GB cap are blocked until you delete files or re-subscribe. **Why is there a monthly download cap?** The cap (10 GB free / 100 GB Club) is set well above normal use — it's there to prevent someone from turning their Bankr storage into a free CDN. Most users never come close. --- ## Access: Free, Bankr Club & Max Mode **Three tiers — start free on the terminal, upgrade to Bankr Club for unlimited chat and full features on the standard Gemini 3.8 Flash model, or use Max Mode for premium models pay-as-you-go.** | | Free | Bankr Club | Max Mode | | ------------------------- | ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------ | | **Cost** | $0 | $20/mo or $198/yr in USDC (default) or BNKR / ETH / any Base ERC-20 | Pay-per-token from LLM credits | | **Messages/day** | 5 (terminal only) | Unlimited on the terminal | Unlimited (pay-per-token) | | **Model** | Gemini 3.8 Flash | Gemini 3.8 Flash | Premium gateway models (Claude Opus 5, Gemini 3.1 Pro, etc.) | | **Token launches / Apps** | No | Yes | Yes | | **Browser tools** | No | Yes | Only with Bankr Club | | **@bankrbot on X** | No | Yes | Yes | | **Resets** | 24h after your first message | — | — | You can mix tiers — Club for everyday chat, Max Mode when you need more horsepower. ## Free Tier — Terminal Only The free tier lets you try Bankr without subscribing. **5 messages per day on the [bankr.bot](https://bankr.bot) terminal**, over a 24-hour window that starts with your first message. You're on the fast standard model — no model picker until you upgrade. **What free tier includes**: - Chat, trading, swaps, transfers, market data, portfolio, NFTs, Polymarket, Avantis, Hyperliquid **What free tier doesn't include** (Bankr Club or Max Mode required): - Token launches - Browser tools (Bankr Club only) - Apps - Replies from @bankrbot on X — these are silently ignored for non-Club users (no free quota applies on X at all) **Other surfaces**: the 5-message/day quota applies **only** to the bankr.bot terminal. Twitter, Telegram, Farcaster, the API, and webhooks each have their own access gates — most require Bankr Club. See the relevant integration doc for details. **Max Mode bypasses the daily limit** — Max Mode requests don't count against your free messages; they draw from your LLM credit balance instead. ## Bankr Club — the Base Model Plan Bankr Club is the simple flat-rate plan. Pay once per month (or year), get the standard model (Gemini 3.8 Flash) with unlimited messages on the terminal, and access to every feature — trading, token launches, automations, prediction markets, the works. **To subscribe**: ask Bankr in chat: ``` Subscribe to Bankr Club ``` It'll walk you through payment. **Default is USDC** — BNKR is paid directly, and any other token (ETH or any Base ERC-20) is swapped to USDC at checkout (≤5% slippage). Yearly ($198/yr) is the better deal if you use Bankr every day. :::info Want to pay in BNKR? You need BNKR in your wallet first. Just ask Bankr: ``` swap $25 of ETH to BNKR on base ``` Then: `subscribe to Bankr Club with BNKR` ::: :::warning Embedded wallets only Club subscriptions require a Bankr embedded wallet (auto-created when you sign in with email, X, Farcaster, or Telegram). **External/connected wallets** (MetaMask, Coinbase Wallet, Sign-In with Ethereum) **cannot subscribe** — payments are signed by Privy on your behalf, and Bankr doesn't hold keys for external wallets. Options: sign in with email/social to get an embedded wallet, or use [Max Mode](/llm-gateway/max-mode) which works with any wallet. ::: **Check your status**: ``` what is my Club status? ``` :::note Bankr Club NFTs If you hold an original Bankr Club NFT from the initial drop, that's a commemorative collectible — **it does not grant membership**. To get Club access, subscribe through the chat flow above. ::: ## Max Mode — Premium Models, Pay As You Go Max Mode swaps out the default model for a more capable one — any frontier, flagship or balanced gateway model (Claude Opus 5, Gemini 3.1 Pro, etc.). You pay per token from an LLM credit balance, so cost scales with usage. Your Max Mode choice syncs across every surface (web, Twitter, Telegram, CLI, automations). ### Enabling Max Mode **Web terminal**: at [bankr.bot](https://bankr.bot), open the mode menu in the chat composer and choose **Max**, then pick a model from the model picker. **CLI**: pass `--model` to any prompt: ```bash bankr "analyze my portfolio" --model claude-opus-5.5 ``` See the full [Max Mode docs](/llm-gateway/max-mode) for every model and flag. ### Adding Credits LLM credits are denominated in USDC and drawn down as you send Max Mode messages. Top up from chat, the web, or CLI: **Ask Bankr directly**: ``` what's my LLM credit balance? add $25 in LLM credits ``` Bankr reports your spendable balance, your active Max Mode model, and the soonest-expiring credit grant if you hold any. **Web**: [bankr.bot/terminal/llm?tab=credits](https://bankr.bot/terminal/llm?tab=credits) **CLI**: ```bash bankr llm credits # check balance bankr llm credits add 25 # add $25 bankr llm credits auto --enable # auto top-up (never run dry) ``` ### What Happens If Credits Run Out The agent replies asking you to top up rather than answering on the default model — on X it quietly falls back to the standard model instead, so a public thread never turns into a top-up nag. If credits run out partway through a turn, it stops there and saves its progress in the thread so you can top up and ask it to continue. Enable auto top-up above to avoid the interruption. Full detail: [Max Mode](/llm-gateway/max-mode). ## FAQ **Do I need both?** No. Either one unlocks Bankr. Most users start with Bankr Club. **Can Club members use Max Mode too?** Yes. Club + Max Mode stack — Club covers unlimited standard-model chat, and Max Mode lets you run premium models on top whenever you need them. **Are there any model discounts?** Yes. The LLM Gateway supports time-bounded per-model discounts. See [LLM Gateway → Model Discounts](/llm-gateway/overview#model-discounts) and check [bankr.bot/llm](https://bankr.bot/llm) for active promos. **What happens on the free tier?** 5 free terminal messages/day on the fast standard model. Past that, subscribe to Bankr Club or use Max Mode (unlimited on the terminal, pay-per-token from LLM credits). The [Agent API](/security/developer-api#rate-limits) caps non-Club users at 100 messages/day; that limit doesn't apply on the terminal. **Where do I ask for help?** Ask Bankr in chat, or open a ticket at the [Bankr Help Center](https://help.bankr.bot). --- ## Advanced Features Bankr is extensible. Beyond the built-in tools, you can install **skills** from GitHub (or write your own), connect **MCP servers** so the agent can call your private APIs, and store **secure environment variables** for secrets like API keys. All of these are per-wallet — your skills, MCP servers, and env vars are private to you and sync across every surface the agent runs on. ## Skills Skills are pre-packaged workflows the agent can load on demand. Think "a specialized prompt + optional reference docs" bundled together. A single skill might teach the agent how to add liquidity on a specific AMM, interpret a Zerion portfolio export, or format reports for a specific workflow you use. ### Install from GitHub Just ask Bankr in chat: ``` install the ens skill from https://github.com/austintgriffith/ethskills/tree/master/skills/ens ``` The URL must point to a directory containing a `SKILL.md` file. Bankr fetches the skill, parses the frontmatter, pulls down any companion reference files, and registers it to your wallet. A repo URL works when the repo holds one skill; if it holds several (like [BankrBot/skills](https://github.com/BankrBot/skills)), Bankr lists them and asks you to re-run the install with the directory of the one you want. See the [Bankr skill installation guide](/skills/for-other-agents/installation) for the full repo structure, [other available skills](/skills/for-other-agents/available-skills), and how to [contribute your own via PR](/skills/for-other-agents/contributing-skills). ### Manual Installation If you don't want to push the skill to a public repo, paste the SKILL.md content directly in chat: ``` create a skill with this content: --- name: my_workflow description: Runs my custom portfolio report tags: [portfolio, reporting] --- # My Workflow ... skill instructions ... ``` Bankr validates the frontmatter, saves the skill to your private library, and makes it available via `use_skill` on any future turn. ### Using Installed Skills Once installed, the agent picks the right skill automatically based on your question. You can also force it: ``` use the ens skill to register deployer.eth ``` Ask `what skills do I have?` to see your library. :::tip Skill limits Up to **50 skills per wallet**. Each `SKILL.md` is capped at 1MB, and each reference file is capped at 100KB. Plenty for prose instructions; not for stuffing a whole repo. ::: ## MCP Servers [Model Context Protocol](https://modelcontextprotocol.io) servers expose tools to the agent over HTTP. Add an MCP server once and every tool it provides becomes callable through Bankr — Linear tickets, GitHub PRs, Notion pages, internal APIs, whatever the server exposes. ### Adding a Server **Web terminal**: open the settings gear in the terminal → **MCP Servers** → **+ Add**. Fill in the URL, transport (HTTP or SSE), and choose how the server authenticates: - **None** — public servers that need no credentials. - **Header** — send a static header (e.g. an API key) on every request. This is the mode shown below. - **OAuth** — sign in to the provider through a popup, no key to paste. See [OAuth-gated servers](#oauth-gated-servers). **Chat**: describe the server in plain English: ``` add an MCP server named "Linear" at https://mcp.linear.app/mcp with Authorization header "Bearer {{LINEAR_API_KEY}}" ``` The `{{LINEAR_API_KEY}}` placeholder is a reference to a secure environment variable — see the next section. The agent stores the server config, hits the `tools/list` endpoint immediately to discover what tools the server provides, and caches the list. ### OAuth-Gated Servers Some remote MCP servers require you to sign in with the provider instead of pasting a key. Pick **OAuth** as the auth mode when adding the server, then click **Connect** on the server card — a popup opens the provider's consent screen. Approve it, and Bankr exchanges the grant, discovers the server's tools, and marks the card **connected**. OAuth sign-in is rolling out provider by provider; the first is Coinbase at `https://agents.coinbase.com/mcp`. Where it isn't enabled yet, **Connect** fails and the card records an OAuth error; servers that authenticate with a key or header are unaffected. Bankr keeps your access and refresh tokens in encrypted storage and refreshes them automatically — they're never shown in chat and never stored alongside the server config. OAuth servers don't take custom headers; the sign-in replaces them. If a grant expires or is revoked, the card flips to **NOT CONNECTED** and tool calls stop until you click **Reconnect** and sign in again. ### Using MCP Tools Once a server is added, the agent can call any tool it exposes. Ask naturally: ``` show my open Linear issues assigned to me ``` Bankr looks up the right Linear MCP tool and calls it. You can also: - `list my MCP servers` - `list tools from the Linear server` - `remove the Linear server` - `sync the Linear server` — re-fetches the tool list if the upstream server changed :::tip MCP limits Up to **20 MCP servers per wallet**. ::: ## Secure Environment Variables For secrets (API keys, tokens, private credentials) you never want echoed in chat or tool logs. Bankr stores them encrypted under a per-wallet namespace — the agent can pass the values to tools that need them, but the values are never surfaced back to the chat transcript. Common uses: - `LINEAR_API_KEY` referenced by an MCP server header - `OPENAI_API_KEY` used by a skill that calls an external API - Any secret an `execute_cli` script needs at runtime ### Setting Env Vars **Web terminal**: settings gear → **Env Vars** → add key/value pairs. This is the recommended path — you type the value once, into a form, and it's written straight to the secret store. **API**: `POST /agent/env`, `GET /agent/env`, `DELETE /agent/env/:key`. See the [Agent API reference](/agent-api/overview). ### Using Env Vars The agent reads env vars automatically when a tool needs them. You refer to a var by name with the `{{VAR_NAME}}` placeholder, e.g. in an MCP server header: ``` Authorization: Bearer {{LINEAR_API_KEY}} ``` Or have a skill / `execute_cli` script read them from the environment. ### What the Agent Can See - `GET /agent/env` returns **key names only** — the agent (and anyone asking it) can see _what_ secrets exist, never the values. - Values are decrypted on-demand inside the tool runtime and never echoed back into the conversation. - Reserved prefixes used internally by the platform (including `BANKR_*` and standard cloud-provider prefixes) are blocked to prevent shadowing platform config. Ask `what env vars do I have?` to see the key list. ## Putting It Together A typical advanced setup: 1. Install a handful of skills you use daily (`install skill from github ...`) 2. Add an MCP server or two for your work tools (Linear, Notion, GitHub) 3. Store the API keys each server needs as secure env vars 4. Reference them via `{{ENV_VAR}}` templates in the server configs Now every time you chat with Bankr — from the web, Telegram, or the CLI — your full toolkit is available and the secrets stay locked away. --- ## Automations Automations let you set up conditional and scheduled trading actions that execute automatically. Create limit orders, stop-losses, DCA strategies, and more — the Bankr agent monitors conditions and executes when triggered. ## Automation Types | Type | Description | Docs | |------|-------------|------| | **Limit Order** | Buy or sell when a token reaches a target price | [Limit Orders](../features/trading/limit-orders) | | **Stop Order** | Stop-loss sells, stop buys on breakouts, and trailing stops | [Stop Orders](../features/trading/stop-orders) | | **DCA** | Recurring buys at fixed intervals | [DCA Orders](../features/trading/dca-orders) | | **TWAP** | Spread a large order over time | [TWAP Orders](../features/trading/twap-orders) | | **Vesting Sell** | Scheduled token release and sell (Base and Robinhood Chain) | | **Agent Command** | Schedule any agent command to run on a recurring basis | | **Solana Triggered Order** | On-chain price oracle triggers on Solana | ## Limits | Automation | Active at once (paused ones count) | Runs per automation | |------------|----------------|---------------------| | Agent commands | 20 with Bankr Club, counted per wallet, or per conversation in Telegram, X and Farcaster DMs. Without Club, 1 per DM conversation; the terminal, the Agent API and public posts need Club | Up to 1,000 in total and 100 a day, at least 10 minutes apart | | Stop and limit orders | 50 | — | | DCA and TWAP orders | 20 combined | DCA: up to 100 in total and 24 a day, at least 1 hour apart. TWAP: up to 1,000 in total and 480 a day, at least 3 minutes apart | Limit, stop, DCA and TWAP fills count toward your wallet's [spending limits](/security/bankr-terminal#spend-tracking). A fill the limits refuse retries hourly and the order stays active. ## Managing Automations ``` "show my automations" "cancel my limit order" "cancel all my automations" ``` Pausing, resuming and editing an automation happen in the Automations view in the terminal sidebar. ## Agent Command Automations Schedule any agent command to run on a recurring basis: ``` "every day at 9am, check the price of ETH and send me a summary" "every 6 hours, check my portfolio PnL" ``` With Bankr Club you can create them from any surface, including the [Agent API](/agent-api/overview) and the CLI — each run executes against the wallet behind your API key. Each execution counts as one run against the automation's daily limit. --- ## Browser Automation Bankr can browse the web for you. When a task can't be done through an API — searching a store, filtering a list, signing in to your account, walking a checkout — describe what you want and Bankr opens a browser, navigates, fills out forms, and reports back. Browser automation is a [Bankr Club](/faq/bankr-club) feature, and it only runs in private chats — the [bankr.bot](https://bankr.bot) terminal, a Farcaster direct cast or a Telegram DM — never from a Telegram group, a public post or the Agent API. ## When This Helps Ask Bankr to: - Search a website that needs filters, sorting, or clicks to surface what you want. - Sign in to your account on a site and continue a workflow there. - Add items to a cart and prepare a checkout for your final approval. - Download a statement, receipt, export, or report. - Upload a file you already have into a web form. - Show you what a page looks like with a screenshot. For data that has a public API or a Bankr-supported integration, Bankr will prefer those — they're faster and more reliable. ## Staying Signed In For sites where you'd normally stay logged in, Bankr can remember the signed-in state between conversations. The first time you ask Bankr to do something on a site that requires login, it'll handle the sign-in (using stored credentials, see below). After that, returning to the same site picks up where you left off — no need to repeat the login on every task. ## When Bankr Asks for Help Some steps need you in the loop: - Solving a CAPTCHA. - Entering a one-time code sent to your email or phone. - Confirming a final purchase or anything that costs money. - Anything sensitive where Bankr can't safely act on its own. When that happens, Bankr will pause and ask you directly. You don't need to paste passwords into chat — that's what stored credentials are for. ## Stored Credentials If you want Bankr to sign you in automatically, you can store login credentials for specific sites ahead of time. Bankr fills them in only when it lands on the matching site, and it never echoes the values back to you in chat. See [Stored Browser Credentials](/browser/stored-credentials) for setup. ## Final Approvals Bankr won't submit a purchase, send a payment, or take an irreversible action on your behalf without explicit confirmation. For checkout flows, expect Bankr to bring you to the review screen with the merchant, item, and total clearly stated, then wait for your go-ahead. --- ## Stored Browser Credentials Stored credentials let Bankr sign you in to websites without you pasting passwords into chat. You set them up once for the sites you use, and Bankr fills them in automatically when it lands on the right login page. This is for ordinary login forms — email/password style. It's not a way to feed arbitrary data to Bankr or to the page. ## How It Works Each set of credentials is tied to a specific site (or set of sites). When Bankr opens a login page, it checks that the page is on the allowed site for that credential, and only then fills in the field. The values stay safely stored and never appear in chat or in anything Bankr returns to you. ## Setting It Up Stored credentials live in your **Settings → Env Vars** in Bankr. For each site you want Bankr to sign in to, you add three entries: a username/email, a password, and the website(s) where the credential is allowed to be used. Each entry uses a name in the format: ```text BROWSER_CREDENTIAL__ ``` `` is a label you choose for the site (letters, numbers, underscores, or hyphens). `` is one of `EMAIL`, `USERNAME`, or `PASSWORD`. You also add an `ALLOWED_ORIGINS` entry that locks the credential to a specific website address. ### Example: Amazon In Settings → Env Vars, add: | Name | Value | | ------------------------------------------- | ------------------------ | | `BROWSER_CREDENTIAL_AMAZON_EMAIL` | `alice@example.com` | | `BROWSER_CREDENTIAL_AMAZON_PASSWORD` | your password | | `BROWSER_CREDENTIAL_AMAZON_ALLOWED_ORIGINS` | `https://www.amazon.com` | Once saved, ask Bankr to do something on Amazon that requires sign-in. Bankr will fill the form on its own. ### Multiple Allowed Sites If a site uses several login domains, list them comma-separated: ```text BROWSER_CREDENTIAL_SHOP_ALLOWED_ORIGINS=https://shop.example.com,https://checkout.example.com ``` The website address has to match exactly — same scheme (`https`) and same subdomain (`www.amazon.com` is not the same as `amazon.com`). Anything after the address, like a path, is ignored. ## Safety Stored credentials are designed to fail closed: - A credential set for one site will not fill on a different site, even one with a similar name. - Bankr never returns the password value back to you, prints it in chat, or includes it in screenshots. - Bankr can only read credentials that follow the `BROWSER_CREDENTIAL_*` naming convention — other entries in your env vars are off-limits to the browser. ## When You'll Still Be Asked Even with stored credentials, you'll still be pulled in for: - One-time codes sent to your email, phone, or authenticator app. - CAPTCHA challenges. - Any final purchase or money-moving step. These exist on purpose so an automated sign-in can't be turned into an automated checkout without your explicit OK. ## If Sign-In Fails If Bankr says it couldn't sign in, the most common causes are: - **The credential isn't saved yet.** Add it in Settings → Env Vars before asking Bankr to use the site. - **The allowed website is wrong.** Make sure the `ALLOWED_ORIGINS` entry is the exact site Bankr is on, with `https://` and the same subdomain. For example, `https://www.amazon.com` doesn't cover `https://amazon.com`. - **The site asked for a one-time code or CAPTCHA.** Bankr will ask you for it directly rather than guessing. --- ## Apps Overview **Apps are mini-dashboards and tools you describe in plain English — Bankr writes the manifest, the scripts, and the UI for you, then drops it into your terminal.** No project scaffolding, no build pipeline, no hosting to set up. You talk, Bankr ships. ## Build an app by asking Open the chat and tell Bankr what you want. The more specific you are about the data, layout, and refresh cadence, the closer the first build lands to what you imagined. ``` build me a polymarket alpha terminal — show curated picks bankr's reasoning, trending markets, ending-soon markets, and my open positions. refresh every 15 minutes. share it as a public link i can post on twitter. ``` Bankr designs the data model, writes the backend scripts, drafts the HTML with charts and tables, picks a refresh schedule, and installs the app under your wallet. When it's done, the app shows up in your **Apps** sidebar — click it and the dashboard renders inside the terminal panel. You can also ask for tools that aren't dashboards: a calculator, a step-by-step trade builder, a watchlist with a paste-in field, a portfolio snapshot. If the agent has the right permissions and the data is reachable, it can probably build it. ### App Building Terms The first time you ask the agent to build, edit, fork or run an app — or to deploy or manage an [x402 endpoint](/x402-cloud/overview) through chat — it shows the **App Building Terms** and pauses until you reply exactly `I agree`. The key point: you're responsible for any wallets, keys or funds your apps create or use, so never send funds to an address an app or the agent generates while building. You accept once per version of the terms; automations and webhooks can't accept on your behalf. ## Refine by chatting Every installed app keeps the chat open right next to it. To change something, just say what you want changed. ``` add a column for entry price between symbol and size change the schedule to every 5 minutes split the curated section into two panels — long and short show 24h volume next to each market stop showing my solana positions, only base ``` Bankr edits the app in place. It only touches the parts you asked about — your existing layout, naming, and color choices stay. If something breaks, say so ("the trending panel is empty after the last edit") and Bankr will read its own scripts, find the issue, and patch it. You don't need to think about which file to edit. The agent owns the manifest, the scripts, the HTML, and the schedule, and figures out the smallest change that satisfies your request. ## Running scripts on demand Each app's backend logic lives in **scripts** — small functions that run on a server-side runtime when invoked. Most are wired up to a **schedule** that fires automatically (every 15 minutes, every hour, daily, whatever you ask for); some are triggered from buttons in the app's UI; some are run on demand. Without [Bankr Club](/faq/bankr-club), scheduled runs are capped at 1,000 a day (UTC) across all of a wallet's apps, failed runs included; past the cap, scheduled runs are skipped until the next day. If you own the app, the panel header has a **Scripts** button that opens a drawer listing every script. Each row has: - The script name and its schedule (or `on-demand` for unscheduled scripts). - An **Open** button that jumps you into the file editor with the script's source loaded. - A **Run** button that fires the script immediately, as if its schedule had just ticked. The result (or error) renders inline. Useful for testing edits, refreshing data immediately instead of waiting for the next scheduled run, or seeing exactly what a script returns. ## Paid endpoints with x402 Apps can call paid HTTP endpoints from the iframe using the [x402 payment protocol](https://x402.org). When a button needs to spend money — an AI image generator, a premium per-query data lookup, a gated upstream feed — the app calls `bankr.x402.fetch(url, options)`. The host pops a confirmation dialog showing the URL and the endpoint's price, the visitor's wallet pays, and the upstream response renders. Each call goes through its own confirm; nothing settles silently. ``` build me an image generator app where each render charges the visitor $0.10 to call x402.bankr.bot/0xowner/image-gen ``` The agent adds the `pay:x402` permission, pins the endpoint hostname in an `allowedHosts` allowlist, and writes the iframe code. A per-(visitor, app) rate limit of 10 calls/minute caps abuse. If you want to _publish_ a paid endpoint that other apps and agents can consume — not just consume one — see [x402 Cloud](/x402-cloud/overview). For the wire-level details on consuming x402 from inside an app see [Permissions](/apps/permissions#network-and-ai-permissions) and the [SDK reference](/apps/sdk#visitor-paid-x402-buttons). ## Sharing & forking :::note We're re-evaluating how app sharing and forking work. Sharing an owner-mode app works today; forking someone else's app and opening viewer-mode apps to visitors are paused for now. ::: Apps default to private. To share one: ``` make this app public make this app unlisted, give me the share link ``` - **Unlisted** apps are accessible to anyone with the URL. - **Public** apps are listed in Bankr's app directory and discoverable by anyone. Anyone visiting your shared dashboard sees the same data you see — scripts run as the **owner** so visitors get a consistent view. Forking someone else's app is turned off for now, so a visitor who wants the same view of their own data asks Bankr to build them their own app. Apps can also run in "viewer mode", where each visitor's own wallet drives the scripts (per-user calculators, viewer-specific trade builders). Viewer mode is closed to visitors for now: a viewer-mode app opens only for its owner and can't be made public or unlisted. See [Permissions](/apps/permissions#wallet-identity) for the details. Before flipping an app to public or sharing the unlisted link, walk the [public-app checklist](/apps/permissions#before-publishing-public-or-unlisted) — it covers the small set of rules that catch the most common breakage (most often: an iframe reads a key the manifest never declared, and anonymous viewers get a 403). ## Fullscreen The app panel has a fullscreen icon next to **Refresh**. Click it and the app fills the viewport, hiding the terminal sidebar. Press **Esc** or click the icon again to return. Great for dense terminals — heat-maps, depth charts, long position tables. ## Where to next - [Permissions](/apps/permissions) — what an app can read, write, and execute on your behalf. - [SDK Reference](/apps/sdk) — the methods available to your app's frontend HTML and backend scripts, plus the manifest format and where app files live in your filesystem. --- ## Permissions **Every app declares what it needs access to in its manifest.** Permissions are checked at runtime — a script that calls a wallet read without `read:wallet` declared in the manifest fails immediately, with an error you'll see in the script output. This makes the surface area of any app explicit: glance at the permissions list and you know exactly what it can touch. When you ask Bankr to build an app, the agent picks the minimum set of permissions the scripts actually use. If you want fewer, ask — Bankr will rewrite the scripts to drop the dependency, or tell you the feature can't work without it. ## Permission catalog ### Read permissions These let the app see things. None of them can change state. | Permission | What it grants | |---|---| | `read:wallet` | Your wallet identity — the EVM address, Solana address, and a stable account ID. Used by almost every app to know who's running it. | | `read:portfolio` | A full multi-chain token portfolio — balances on every supported chain, optional realized + unrealized PnL, optional NFT listings. | | `read:positions` | Your open positions on supported venues (perps, spot trading, prediction markets). | | `read:tokens` | Token metadata, prices, and search across the chains you use. | | `read:chain` | Direct on-chain reads — call any contract's read functions, multicall, fetch logs, look up balances by address. | | `read:files` | Read your file storage. The app can list folders, fetch file contents, and search files by name or content. Only on runs the owner starts — refused when a visitor starts the run. | | `read:appdata` | Read the app's own key-value storage (its private state and any cached snapshots). | | `read:secrets` | Resolve manifest-declared secret values at runtime. Plaintext stays server-side — secrets never reach the rendered HTML. | ### Write permissions These let the app change state. They're more sensitive — Bankr doesn't grant them unless the app actually needs them. | Permission | What it grants | |---|---| | `write:files` | Create and update files in your file storage. Used by apps that save reports, snapshots, or generated artifacts. | | `write:appdata` | Write to the app's key-value storage. Required for any app that caches data, stores user preferences, or persists state between runs. | | `prepare:transaction` | Build a transaction blob (target address, calldata, value) for the user to confirm in chat. The app can't broadcast on its own — confirmation always goes through the chat flow. | | `execute:swap` | Use Bankr's swap routing to assemble swap transactions. Still requires user confirmation in chat to broadcast. | | `execute:transfer` | Build a token transfer. Still requires user confirmation in chat to broadcast. | | `execute:sign` | Build an arbitrary signature request. Still requires user confirmation in chat to sign. | ### Network and AI permissions | Permission | What it grants | |---|---| | `fetch:http` | Make outbound HTTP requests from the server-side runtime. Locked to public hostnames — private IPs are blocked. | | `pay:x402` | Lets the **iframe** call `bankr.x402.fetch(url, options)` to pay an x402 endpoint from the **visitor's** wallet (not the owner's). Each call pops a confirmation modal showing URL + max USD before any payment. Requires a companion `x402` manifest block declaring `allowedHosts` and a per-call USD cap — without it the runtime rejects every fetch. Per-(visitor, app) rate limit: 10 calls/minute. | | `fetch:x402` | Reserved for server-side, owner-paid x402 fetches (cron-driven premium feeds where the owner's wallet covers the bill once and visitors read the cached snapshot for free). The permission is declared today; the runtime client is not yet wired — scheduled scripts that need paid data should stick to `fetch:http` plus an upstream API key in `secrets` for now. | | `invoke:agent` | Run a curated, read-only Bankr agent turn from inside a script (`bankr.askAgent`) — useful for LLM-powered curation, scoring, or summaries. The agent runs as the app owner, and only on runs the owner starts — refused when a visitor starts the run. Two tiers: **Free** (default model, no credit deduction, capped at 2 runs/day per owner — 5/day with Bankr Club, 0/day once the owner has had no signed-in Bankr activity for 14 days — with a 5/min burst) and **Max** (set a per-app agent model — runs that model and deducts the owner's LLM credits, exempt from the free daily cap). See [Agent model tiers](/apps/sdk#agent-invocation-bankraskagent). | ## Defaults Bankr picks When the agent builds an app, it picks the smallest set that satisfies your request: - **Read-only dashboard of your data** → `read:wallet`, `read:portfolio` and/or `read:positions`, `read:appdata`, `write:appdata`. - **Public snapshot dashboard with scheduled-refresh content** → adds `fetch:http`, often `invoke:agent`. - **Trade builder / order helper** → adds one of `prepare:transaction`, `execute:swap`, `execute:transfer`. - **Apps that store generated artifacts (charts, reports)** → adds `read:files`, `write:files`. You can audit the list anytime — every app's manifest is in your filesystem under `/apps/{slug}/manifest.json`. ## Wallet identity Apps run scripts under a single wallet identity. Which wallet depends on what triggered the script: | Trigger | Whose wallet drives the script | |---|---| | **Frontend** — a button or `bankr.scripts.run` call from the app's HTML | Set by the manifest's `frontendIdentity` field — `"owner"` (default) or `"viewer"` (owner-only for now, see below) | | **Scheduled run** — fires automatically on the app's schedule | Always the **owner** (the wallet that installed the app) | | **Owner manually clicks Run** in the Scripts drawer | The owner | A run that someone other than the owner starts keeps the app's other permissions but never gets `invoke:agent` or `read:files`, whatever the manifest declares, so a visitor's input can't reach the owner's agent or files. Put agent calls and file reads in a scheduled script and have the page read its snapshot. The default `frontendIdentity: "owner"` is the right choice for **shared dashboards** where you want every visitor to see the same data — your trades, your portfolio, your curated picks. Bankr leans on this default unless you specifically ask for visitor-scoped behavior. `frontendIdentity: "viewer"` is meant for **per-visitor tools** — a calculator, a "score MY positions" widget, a personal trade plan — where each visitor's wallet drives the script. It is closed to visitors for now: a viewer-mode app runs only for its owner and can't be made public or unlisted, and a shared app has to be made private before it can switch to viewer mode. Forking someone else's app is also turned off for now. A visitor who wants the same dashboard pointed at their own data asks Bankr to build them their own app. ### Anonymous viewers Anyone visiting a public or unlisted app without signing in: - **Can read** any data the app explicitly publishes via `publicDataKeys` (snapshots populated by scheduled runs, curated content). - **Can run only the scripts the owner lists in `publicScripts`**, within that script's `publicScriptLimits`. A public script runs with no caller wallet and can't use the wallet, files, transactions, the agent or the app's private storage. Any other button that runs server-side code shows a sign-in prompt. - **Cannot read or write the app's private storage**. This is why public dashboards typically have a scheduled script that pre-computes the data into a public snapshot — anonymous viewers see the rendered snapshot instantly without authenticating. ### Before publishing public or unlisted The most common breakage when an app moves from private to public is reading an `appKV` key the manifest never declared. Anonymous viewers get a 403 with the exact error `Public data key "" is not exposed by this app`, and the iframe shows an empty panel where data should be. Walk this checklist before flipping `make this app public` or sharing the unlisted link: 1. **List every key the iframe reads.** Open `index.html` and find every `bankr.appKV.get(...)` and `bankr.appKV.list(...)` call — including the ones nested inside `Promise.all`, fallback branches, and event handlers that run before sign-in. 2. **Each key must be in `manifest.publicDataKeys`.** If the iframe reads `portfolio_snapshot`, `meta.balancesUpdatedAt`, and `last_curated`, all three names must be in the array. Meta and timestamp keys are *separate* keys, not sub-paths of the data key — the runtime treats `meta.balancesUpdatedAt` as its own entry. 3. **Public-facing keys must be file-backed.** Keys that start with `record:` route to the per-viewer queryable record store and can never be exposed publicly. If you need a public snapshot, the writer must use a plain key (no prefix) so it lands under `/apps/{slug}/data/{key}.json`. 4. **The writer must be the owner.** Schedule the script that populates the snapshot, or run it manually as the owner — viewers can't write file-backed `appKV`. Cron-triggered runs always execute as the owner, which is the right pattern for refreshable public data. 5. **Gate authenticated-only reads.** If a key is intentionally private (per-viewer state, owner-only secrets), don't read it unconditionally. Wrap the read in `if (bankr.ctx.isAuthenticated) { ... }` and render a signed-out fallback so anonymous viewers see an empty state instead of an error. 6. **Wrap interactive buttons in `bankr.auth.requireSignIn()`.** Calls like `bankr.appKV.set`, `bankr.askChat`, `bankr.confirmTransaction`, and `bankr.invokeScript` for any script not in `publicScripts` require sign-in. Render those buttons disabled (or hidden) when `bankr.auth.isAuthenticated` is false, and call `bankr.auth.requireSignIn()` from the click handler so the visitor sees a sign-in modal instead of a thrown error. 7. **Re-audit on every edit.** Whenever you (or Bankr) add a new `appKV.get` call or rename an existing one, recheck step 1 against the manifest. The cleanest way to ask Bankr is *"audit publicDataKeys against every appKV.get in index.html and add any missing keys"*. A working public-dashboard pattern looks like this: ```json // manifest.json { "permissions": ["read:portfolio", "read:appdata", "write:appdata"], "publicDataKeys": [ "portfolio_snapshot", "portfolio_history", "meta.refreshedAt" ], "schedule": [ { "script": "refreshSnapshot", "cron": "*/15 * * * *", "enabled": true } ] } ``` ```js // scripts/refreshSnapshot.ts — runs as owner on the schedule const portfolio = await bankr.wallet.balances({ include: { pnl: true } }); await appKV.set("portfolio_snapshot", { tokens: portfolio.tokens }); await appKV.set("portfolio_history", { points: portfolio.history }); await appKV.set("meta.refreshedAt", Date.now()); return { ok: true }; ``` ```html ``` Every key the iframe reads (`portfolio_snapshot`, `portfolio_history`, `meta.refreshedAt`) is in `publicDataKeys`. The owner-only `private_notes` is gated on `bankr.ctx.isAuthenticated`, so anonymous viewers never trigger the read. The cron writer runs as the owner, and the keys are plain (file-backed), not `record:`-prefixed. ## Asking Bankr to change permissions Like everything else about an app, permissions are editable through chat: ``` this app doesn't need to read my files anymore — drop that permission add fetch:http so you can pull market data from the upstream API ``` Bankr updates the manifest, redeploys, and confirms what changed. The new permission set takes effect on the next script run — no reinstall, no fork. ## Where to next - [SDK Reference](/apps/sdk) — the methods each permission unlocks. - [Apps Overview](/apps/overview) — building, refining, and sharing. --- ## SDK Reference **An app is two things glued together: an `index.html` rendered inside a sandboxed iframe, and zero-or-more server-side scripts that the iframe can call.** Both surfaces ship with a `bankr` global that exposes all the runtime capabilities. The two `bankr` objects share a brand but have different APIs — pick the right one for the surface you're writing. This page is the reference. You don't have to memorize it — Bankr does the writing — but knowing what's available helps you ask for things in the chat. ## The two surfaces ### Frontend (the app's `index.html`) Runs inside a sandboxed iframe at `null` origin. This is where the UI lives. The host injects the `bankr` global before any of your code runs. The frontend can: - Read shared snapshot data (`bankr.appKV.get`). - Trigger backend scripts (`bankr.scripts.run`). - Hand off to chat (`bankr.prefillChat`, `bankr.askChat`). - Ask the user to confirm a transaction (`bankr.confirmTransaction`). - Detect whether the visitor is signed in (`bankr.auth.isAuthenticated`). The frontend **cannot** make raw `fetch()` calls to external URLs — the sandbox is opaque-origin and most APIs CORS-block it. Always route external HTTP through a backend script. Open links in a new tab (`bankr.openExternal(url)` or `target="_blank"`): an app that navigates its own frame is stopped with an error. The sandbox also blocks pointer lock, the Fullscreen API, `localStorage`, `sessionStorage`, IndexedDB and `document.cookie`: never gate UI on them, and keep state in memory or persist it through a backend script with `bankr.appKV`. On an app someone else built, `askChat` only prefills the viewer's chat — they press send. ### Backend (server-side scripts) Each script lives at `/apps/{slug}/scripts/{name}.ts` in your filesystem. They're written as **top-level statements ending in `return`** — not modules. The runtime is a hardened sandbox: no DOM, no `require`, no `import`, no access to other apps' state. The backend can: - Read your wallet identity, balances, and on-chain data. - Read and write your file storage and the app's persistent storage. - Call public HTTP APIs (paid x402 endpoints from the server side aren't yet wired — visitor-paid x402 lives in the iframe SDK). - Build (but not broadcast) transactions for the user to confirm. - Invoke the Bankr agent itself for LLM-driven curation. Backend scripts run when: - The frontend calls `bankr.scripts.run('name')`. - A scheduled run fires automatically on the app's schedule. - The app owner clicks **Run** in the Scripts drawer. ## Frontend SDK ```ts type BankrAppSdk = { ctx: { slug: string; walletAddress?: string; theme: "light" | "dark"; isPublic: boolean; isCompact: boolean; isAuthenticated: boolean; }; // Lifecycle — wrap first-paint logic so wallet info is populated. on(event: "ready" | "refresh" | "theme", cb: (payload: unknown) => void): () => void; // Wallet info — property only, NOT a function. wallet: { address?: string; evmAddress?: string; }; // Auth state. auth: { isAuthenticated: boolean; requireSignIn(): Promise; }; // Trigger a backend script. invokeScript(name: string, args?: Record): Promise; // Aliases (all identical): runScript(name: string, args?: Record): Promise; run(name: string, args?: Record): Promise; scripts: { run(name: string, args?: Record): Promise; invoke(name: string, args?: Record): Promise; }; // Persistent key-value store, server-mediated. appKV: { get(key: string): Promise; set(key: string, value: unknown): Promise; list(prefix?: string): Promise; delete(key: string): Promise; }; // Hand off to chat. prefillChat(message: string): Promise; askChat(message: string): Promise; chat: { prefill(message: string): Promise; send(message: string): Promise; ask(message: string): Promise; }; // Transaction confirmation. The blob comes from a backend script. confirmTransaction(blob: unknown): Promise; // Visitor-paid x402 fetch — pays from the SIGNED-IN viewer's wallet // (not the owner's). Pops a confirmation modal first. // Requires `pay:x402` permission + `x402.allowedHosts` manifest block. x402: { fetch( url: string, options?: { method?: "GET" | "POST" | "PUT" | "DELETE"; body?: string | object; // objects/arrays are sent as JSON headers?: Record; maxPaymentUsd?: number; }, ): Promise<{ status: number; ok: boolean; body: unknown; payment: { amountUsd: number; network: string; payTo: string }; }>; }; // Skill management. installSkill(slug: string): Promise; // UI helpers. openExternal(url: string): Promise; copy(text: string): Promise; navigate(page: string): Promise; // Secrets — status only. The plaintext NEVER reaches the iframe. secrets: { status(): Promise>; requestSetup(key: string): Promise; }; // Pass context back into the chat thread (e.g. "user is viewing X"). setContext(body: string, label?: string): Promise; }; ``` ### Recommended frontend pattern Wallet info is populated *after* the host posts context — wrap your initial render in `bankr.on('ready', …)` so the address is defined when you read it: ```js bankr.on('ready', async () => { const wallet = bankr.ctx.walletAddress; if (!wallet) { renderSignedOutState(); return; } const snapshot = await bankr.appKV.get('snapshot'); render(snapshot); }); ``` Gate per-user actions on `bankr.auth.isAuthenticated`: ```js async function loadMyData() { if (!bankr.auth.isAuthenticated) { showSignInPrompt(() => bankr.auth.requireSignIn()); return; } const data = await bankr.scripts.run('fetchMyData'); render(data); } ``` ### Visitor-paid x402 buttons When the app needs the visitor to pay for a single upstream call from THEIR wallet (paid AI image generation, premium data lookup, gated x402 endpoint), use `bankr.x402.fetch`. The host pops a confirmation modal showing the URL and the endpoint's price; on Approve it pays from the visitor's wallet and returns the upstream response. ```js async function generateImage(prompt) { if (!bankr.auth.isAuthenticated) { return bankr.auth.requireSignIn(); } try { const result = await bankr.x402.fetch( 'https://x402.bankr.bot/0xowner/image-gen', { method: 'POST', body: { prompt }, // sent as JSON maxPaymentUsd: 0.10, // per-call cap; defaults to manifest cap }, ); // result.body is the parsed upstream response // result.payment is { amountUsd, network, payTo } showImage(result.body.url); showReceipt(`Paid $${result.payment.amountUsd} USDC`); } catch (err) { if (err.message.includes('rejected')) { // user clicked Reject — silent return; } showError(err.message); } } ``` The manifest must declare `pay:x402` and an `x402` block with the hostname in `allowedHosts`: ```json { "permissions": ["pay:x402", ...], "x402": { "maxPaymentUsdPerCall": 0.50, "allowedHosts": ["x402.bankr.bot", "api.example.com"] } } ``` Without those, the call is rejected before any modal pops. Distinct from `fetch:x402` — that permission is reserved for the server-side, owner-paid surface (planned; not yet wired); for now only the iframe path settles real x402 payments. See [Permissions](/apps/permissions#network-and-ai-permissions). A per-(visitor, app) rate limit applies: 10 calls/min. ## Backend SDK Scripts have these globals available without any import: `bankr`, `appKV`, `http`, `secrets`, `args`, `ctx`, `log`. Standard JS built-ins (`Buffer`, `URL`, `URLSearchParams`, `crypto`, `setTimeout`, `console`) work normally. ```ts // Wallet identity — async! bankr.wallet.me(): Promise<{ address: string; // alias for evmAddress evmAddress: string; walletId: string; }>; // Multi-chain portfolio — tokens, balances, optional PnL/NFTs. bankr.wallet.balances(args?: { chains?: string; // CSV like "base,polygon"; default = all enabled showLowValueTokens?: boolean; include?: { pnl?: boolean; nfts?: boolean }; }): Promise; // File storage. Permission: read:files / write:files. // read, list and search work only on runs the owner starts; a visitor's run is refused. bankr.files.read({ path }: { path: string }): Promise<{ content: string; ... }>; bankr.files.write({ path, content, mimeType? }): Promise<{ fileId; ... }>; bankr.files.list({ folder?, limit? }): Promise; bankr.files.search({ query, folder?, mimeType? }): Promise; // On-chain reads. Permission: read:chain. bankr.chain.readContract({ chain, address, abi, functionName, args }): Promise; bankr.chain.multicall({ chain, contracts: [...], allowFailure? }): Promise; bankr.chain.getBalance({ chain, address }): Promise; bankr.chain.getLogs({ chain, address?, topics?, fromBlock, toBlock }): Promise; bankr.chain.encodeFunctionData({ abi, functionName, args }): Promise<`0x${string}`>; // Build a transaction blob. Permission: prepare:transaction. bankr.tx.prepare({ chain, to, data?, value?, label? }): Promise; // Curated agent invocation. Permission: invoke:agent. bankr.askAgent(prompt: string): Promise; // HTTP fetch from the server-side runtime. Permission: fetch:http. http.fetch(url: string, init?: RequestInit): Promise; // Returns the parsed body directly: object/array for application/json, // raw text otherwise. There is no .body, .json(), or .headers — use the // alias `bankr.fetchHttp` if you need a Response-shaped wrapper: bankr.fetchHttp(url, init?): Promise<{ status: 200; ok: true; body: unknown }>; // Secrets resolution. Permission: read:secrets. secrets.get(key: string): Promise; secrets.status(): Promise>; // Persistent key-value store, scoped to this app. appKV.get(key: string): Promise; appKV.set(key: string, value: unknown): Promise; appKV.delete(key: string): Promise; appKV.list(prefix?: string): Promise>; // Args from the iframe (the second arg to bankr.scripts.run). const args: Record; // Context — read-only. const ctx: { caller: { walletId: string; walletAddress: string }; author: { walletId: string; walletAddress: string }; appId: string; permissions: string[]; }; // Diagnostic logger — output appears alongside the script return value. log("anything"); log("with values:", { foo: 1, bar: 2 }); ``` ### Recommended script pattern Scripts are top-level — no `function` wrapping the body, no `export`, no `import`. End with `return`: ```js const me = await bankr.wallet.me(); const portfolio = await bankr.wallet.balances({ include: { pnl: true } }); await appKV.set('snapshot', { address: me.evmAddress, totalUsd: portfolio.totalUsd, topHoldings: portfolio.tokens.slice(0, 10), refreshedAt: new Date().toISOString(), }); return { ok: true, holdings: portfolio.tokens.length }; ``` The return value is what the iframe receives back from `bankr.scripts.run`. Keep it small — anything large should land in `appKV` with the iframe reading it via `bankr.appKV.get`. ### Agent invocation (`bankr.askAgent`) With the `invoke:agent` permission, a script can run one curated, read-only Bankr agent turn (LLM-powered curation, scoring, or summaries). The agent runs **as the app owner**, and only on runs the owner starts: a scheduled run, the Scripts drawer, or the owner's own click. A run a visitor starts is refused, so call `askAgent` from a scheduled script and have the page read its snapshot. There are two tiers: | Tier | Model | Cost | Limit | | --- | --- | --- | --- | | **Free** (default) | Default agent model | No credit deduction — Bankr covers it | 2 runs/day per owner, 5/day with Bankr Club (5/min burst) | | **Max** | Per-app agent model you pick | Deducts the **owner's** LLM credits at that model's rate | Exempt from the free daily cap; balance-gated (runs are rejected at ≤ $0 credits or once the owner's daily LLM spend budget is used up) | Leave the app's agent model unset to stay on the rate-limited free tier. Select a model on the app card to move to the Max tier — every `askAgent` run then uses that model and bills the owner's LLM credit balance (see [Max Mode](/llm-gateway/max-mode) for credits). The free daily cap is shared across an owner's app scripts and x402 `ctx.askAgent` handlers. **Free runs pause on a dormant wallet.** Bankr pays for free-tier runs, so an owner with no signed-in Bankr activity for **14 days** drops to a free daily cap of 0, and the refusal says so. Signing in to Bankr, or sending the agent a command, resumes them on the next invocation — nothing needs reconfiguring, and no backlog of paused runs is replayed. Max-tier runs are unaffected: they bill the owner's credits and never depend on this cap. ## Manifest Every app has a `manifest.json` at `/apps/{slug}/manifest.json`. You don't write it by hand — Bankr generates and updates it as you ask for changes — but it's editable and the runtime reads it on every script run, so changes pick up immediately. ```json { "slug": "polymarket-alpha", "title": "Polymarket Alpha — curated picks + your positions", "description": "Live alpha picks scored by Bankr, plus a panel for your open positions.", "tags": ["polymarket", "trading", "alpha"], "permissions": [ "read:wallet", "read:positions", "read:appdata", "write:appdata", "fetch:http", "invoke:agent" ], "scripts": ["refreshAlpha", "fetchMyPositions"], "schedule": [ { "script": "refreshAlpha", "cron": "*/15 * * * *", "enabled": true } ], "secrets": [], "publicDataKeys": ["alpha_snapshot", "trending_snapshot"], "frontendIdentity": "owner" } ``` | Field | Purpose | |---|---| | `slug` | URL-safe identifier, unique within your wallet. | | `title`, `description`, `tags` | Display metadata for the app directory. | | `permissions` | Runtime permissions — see [Permissions](/apps/permissions). | | `scripts` | Names of the script files (without the `.ts` extension). | | `schedule` | Scheduled-run entries. Each references a script by name plus a `cron` expression — the standard 5-field schedule syntax (`minute hour day-of-month month day-of-week`). For example, `"*/15 * * * *"` means "every 15 minutes," `"0 14 * * *"` means "every day at 14:00 UTC." Tools like [crontab.guru](https://crontab.guru) translate plain English into the syntax. | | `secrets` | Manifest-declared secrets. The actual values are stored separately and never appear in the manifest itself. | | `publicDataKeys` | `appKV` keys that anonymous viewers can read. Use for public snapshots populated by scheduled runs. | | `publicScripts` | Scripts that anonymous viewers may run with `bankr.invokeScript`. Use only for cheap, public-safe live reads; these runs get no wallet, files, transactions, agent or private storage. Every other script requires sign-in. | | `publicScriptLimits` | Per-script caps for `publicScripts` (HTTP calls, chain reads, run time, response size and rate limits). Missing entries use conservative defaults. | | `frontendIdentity` | `"owner"` (default) or `"viewer"`; a viewer-mode app runs only for its owner for now — see [Wallet identity](/apps/permissions#wallet-identity). | | `x402` | Required when `permissions` includes `pay:x402`. Shape: `{ maxPaymentUsdPerCall: number, allowedHosts: string[] }`. The hostname allowlist is mandatory and non-empty — without it the runtime rejects every `bankr.x402.fetch`. | ## File storage layout Apps live in your regular file storage under `/apps/{slug}/`. You can browse, edit, and even copy files between apps using the file explorer or by asking Bankr. ``` /apps/{slug}/ ├── manifest.json ← the app config ├── index.html ← the rendered HTML ├── scripts/ │ ├── refreshAlpha.ts ← server-side script │ └── fetchMyPositions.ts ├── data/ ← appKV file-backed values │ ├── alpha_snapshot.json │ └── trending_snapshot.json └── designs/ ← optional reference images, mockups └── v1.png ``` Editing a script file in the file explorer is the same as asking Bankr to update it — the next script run picks up your edit. Same for `index.html`. The `manifest.json` is also editable, but if you're going to change permissions or schedules, asking the agent to do it is usually faster (and avoids syntax mistakes). The `data/` folder is where `appKV.set('snapshot', …)` lands. Each key becomes a `{key}.json` file that's browsable and exportable like any other file. Anything that needs per-wallet scoping or prefix-list queries should use the record store — write keys with a `record:` prefix to opt into that: ```js // File-backed: lands at /apps/{slug}/data/snapshot.json await appKV.set('snapshot', { ... }); // Queryable record store, scoped to the caller's wallet — one value per key, set() overwrites: await appKV.set('record:user_prefs', { ... }); ``` The two paths feel the same from the app's perspective — same `get`, `set`, `list`, `delete` methods. The difference matters for sharing: only file-backed keys can be exposed to anonymous viewers via `publicDataKeys`. ## Where to next - [Apps Overview](/apps/overview) — how to build and refine. - [Permissions](/apps/permissions) — the full catalog plus the wallet identity model for shared dashboards. --- ## Security Best Practices Bankr has two layers of safety controls: **wallet-level** (configured at [bankr.bot](https://bankr.bot) → Security; applies to every surface) and **per-API-key** (configured at [bankr.bot/api-keys](https://bankr.bot/api-keys); applies to one key). Both run independently — a transaction must satisfy both to broadcast. ## Secure Your Account If you're building on Bankr — or just trading with it — do these things. Each is an independent layer, so an attacker has to defeat all of them. ### 1. Turn on MFA on your social login Your Bankr account is reached through the login you chose (X, email, etc.). Harden that login first. **X (Twitter):** 1. In X, open **Settings and privacy** → **Security and account access** → **Security**. 2. Best: under **Passkey**, choose **Manage passkeys** and add a passkey (biometric or hardware-backed). 3. Otherwise: under **Two-factor authentication**, enable an **authentication app** or **security key**. 4. **Avoid text-message (SMS) 2FA.** Phone numbers are the weakest factor — SIM-swap attacks bypass them. If SMS 2FA is on today, replace it with an app or key. 5. Optional: enable **Password reset protect** under **Additional password protection**, so a password reset requires confirming your email or phone. **Email login:** turn on MFA with your email provider (Google, Apple, etc.) — again a passkey or authenticator app, not SMS. ### 2. Turn on MFA in your Bankr account This is a second, independent gate. Even if your X account is compromised, your Bankr account stays accessible only to you. 1. Go to [bankr.bot](https://bankr.bot), click your profile in the lower-left corner, and choose **Security**. 2. Under **Multi-factor authentication**, click **Add passkey** and follow your device's prompt (Touch ID, Face ID, Windows Hello, or a hardware key). To use an authenticator app instead (or as well), click **Set up OTP**, scan the QR code with the app and enter its 6-digit code. 3. **Require MFA** turns on by default when your first factor is a passkey. You'll verify the passkey as it's enabled, so you can't lock yourself out with a factor that doesn't work. With an authenticator app, switch **Require MFA** on yourself; it asks for a code first. Once on, your passkey or authenticator app is required to sign in and to change any security setting. Details: [Bankr Terminal → Multi-factor authentication](/security/bankr-terminal#passkey-mfa). ### 3. Turn on transaction guardrails On the same Security page (profile in the lower-left corner → **Security**), cap what any session can do even if it's somehow compromised: - **Daily spending limit** and **per-transaction limit** — bound total outflow in USD. - **Permitted recipients** — transfers can only target addresses you've allowlisted; new entries wait out a cooldown. - **Price impact protection** — reject swaps that would fill far below market value. - **Enable arbitrary contract calls** — on by default; turn it off to block raw contract interactions if you don't use them. - **Allow NFT transfers** — on by default with 5 transfers per rolling 24 hours; lower the count, or turn it off if you never move NFTs. If you need to loosen the USD limits or price impact protection for a single task, use a [timer](/security/bankr-terminal#timers-turn-a-control-off-or-on-for-a-fixed-window) rather than a permanent change: turn the protection off for 10 minutes, an hour, or a day, and it restores itself. The arbitrary-calls timer works the other way round — it grants the permission for a window, then revokes it — so you can switch raw contract calls back on for one task without leaving them on. Permitted recipients and NFT transfers take no timer. While you're there, review **Active sessions** and log out any device you don't recognize. Full reference: [Bankr Terminal](/security/bankr-terminal). ### 4. Scope any API keys you generate If you create an API key at [bankr.bot/api-keys](https://bankr.bot/api-keys), give it only the access it needs: - **Enable only the surfaces the key uses.** The [permission flags](/security/developer-api#api-key-permissions) are independent — a key that only calls the [LLM Gateway](/llm-gateway/overview) needs just gateway access; turn wallet, agent, and token-launch access off. - **Turn read-only on** unless the key must transact. New keys are read-write by default. - **Set the IP allowlist** so the key only works from your servers. Full guidance and reference: [API Keys](/security/developer-api). ## Pick a layer | You are… | Read | | --------------------------------------------- | ------------------------------------------ | | Using Bankr through chat at bankr.bot | [Bankr Terminal](/security/bankr-terminal) | | Building an agent or integration with the API | [API Keys](/security/developer-api) | | Doing both | Both — controls compose | For the full reference of API-key flags and error responses, see [API Keys](/security/developer-api). ## Where each control lives | Control | Configured at | Layer | | ------------------------------------------ | ------------------------------------------------ | ------- | | MFA (login gate + step-up) | [bankr.bot](https://bankr.bot) → Security | Wallet | | Pause all transactions | [bankr.bot](https://bankr.bot) → Security | Wallet | | Daily USD limit | [bankr.bot](https://bankr.bot) → Security | Wallet | | Per-transaction USD limit | [bankr.bot](https://bankr.bot) → Security | Wallet | | Permitted recipients (with cooldown) | [bankr.bot](https://bankr.bot) → Security | Wallet | | Price impact protection | [bankr.bot](https://bankr.bot) → Security | Wallet | | Enable arbitrary contract calls | [bankr.bot](https://bankr.bot) → Security | Wallet | | Response channels (X, Farcaster, Telegram) | [bankr.bot](https://bankr.bot) → Security | Wallet | | Active sessions (per-device logout) | [bankr.bot](https://bankr.bot) → Security | Wallet | | Read-only mode | [bankr.bot/api-keys](https://bankr.bot/api-keys) | API key | | IP allowlist | [bankr.bot/api-keys](https://bankr.bot/api-keys) | API key | | Recipient allowlist | [bankr.bot/api-keys](https://bankr.bot/api-keys) | API key | ## Stay Safe: How Bankr Will (and Won't) Contact You Most account losses come from social engineering, not protocol bugs. Hold these rules: - **Bankr will never DM you first.** Unsolicited DMs on X, Telegram, Discord, or Farcaster claiming to be "Bankr Support" are scams — even if the handle looks right. Real support flows through the [Bankr Help Center](https://help.bankr.bot), email ([support@bankr.bot](mailto:support@bankr.bot)), or in-app. - **Bankr will never ask for your seed phrase, private key, or password.** Privy embedded wallets are non-exportable by design — there is no seed phrase to share. Anyone asking is an attacker. - **Bankr will never ask you to "verify" by signing a transaction or visiting a link.** Verification happens server-side; you don't need to sign anything to prove ownership of your account. - **Bankr will never use a different domain.** The terminal is `bankr.bot`, API is `api.bankr.bot`, docs are `docs.bankr.bot`. Anything else (`bankrbot.io`, `bankr-claim.xyz`, `bankr.bot.fun`, `docs.bankr.chat`, etc.) is fake. - **A token appearing in the launch feed is not an endorsement.** Failed launches are routinely spoofed by scammers who deploy fake tokens with the same name. Verify the contract address from the creator's official channels before buying. See [Token Launching FAQ](/faq/token-launching) for more. If someone reaches out claiming to be Bankr, close the conversation and open your own ticket through the channels above. --- ## Bankr Terminal Configure these at [bankr.bot](https://bankr.bot) → Security. They apply to every surface — chat, agent, and API — because they're enforced at the broadcast chokepoint. Modifying them requires web (Privy) authentication; an API key cannot change them. If you've turned on [MFA](#passkey-mfa), each change also asks you to verify again with your passkey or authenticator app. The Security page is split into three tabs — **Transactions** (the controls below), **Response Channels**, and **MFA & Sessions**. ## Controls These live on the **Transactions** tab. [Response channels](#response-channels) have their own tab and are covered separately. | Control | Default | Effect | | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Pause all transactions | Off | Blocks every outbound transaction until unpaused | | Enable arbitrary contract calls | On | While off, blocks `write_contract`, `submit_raw_transaction`, `deploy_contract`, and raw `/wallet/submit` (named operations like swaps still work) | | Daily spending limit | $500 / 24h | Rejects any tx that pushes rolling-24h USD outflow past the limit | | Per-transaction limit | $500 | Rejects any single tx priced above the limit | | Permitted recipients | Off | Restricts transfers/swaps to an allowlist; new entries enter a cooldown | | Price impact protection | On (15%) | Rejects swaps whose estimated price impact exceeds your max % — protects against thin pools that would fill far below market value | | Allow NFT transfers | On, 5 / 24h | While off, blocks NFT sends and direct ERC-721/1155 transfer calls; while on, allows a set number (`1` to `1,000`) in any rolling 24 hours. Sales and NFTs moved inside another contract call aren't counted | USD limits accept `1` to `1,000,000`. Setting `0` is rejected — disable the limit instead. Cooldown accepts `0` to `168` hours. Price impact accepts `1%` to `100%`. Raw transactions and contract calls — `/wallet/submit`, `write_contract`, `submit_raw_transaction` — are valued by their native `value` only, and count toward the daily total like any other transaction. Tokens moved by calldata count as $0, which is what the arbitrary-contract-calls switch is for. A call that directly transfers an NFT (ERC-721 or ERC-1155) still counts against **Allow NFT transfers**. :::tip Arbitrary contract calls are on by default Raw contract interactions work out of the box. If you don't use them, turning this off is a cheap way to shrink what a compromised session can do — named operations like swaps and transfers keep working either way. ::: ## Timers: turn a control off (or on) for a fixed window Four of the controls above — plus response channels — take an optional timer, so a temporary loosening doesn't quietly become permanent. (Pause all transactions, permitted recipients and NFT transfers don't.) In every case the deadline is computed on the server — you pick a duration, not a timestamp — and the choices are **10 min**, **30 min**, **1 hour**, **24 hours**, or no timer at all. The timer always runs on the _less safe_ side of the toggle, and always resolves back toward the safe one: | Control | Timer rides | When it lapses | | -------------------------------------------------------------------- | ------------------------------ | ------------------------------------------ | | Daily spending limit, per-transaction limit, price impact protection | turning the protection **off** | the protection turns itself back on | | Enable arbitrary contract calls | turning the permission **on** | arbitrary contract calls switch back off | | Response channels | turning a channel **on** | Bankr stops replying on that channel again | Deadlines resolve at read time — there's no background sweeper and no delay. A lapsed timer can only restore a protection or revoke a permission; it can never turn a protection off or grant a permission you didn't ask for. Editing a control (toggling it, or changing its amount) replaces whatever timer was running, so you can't be left with a stale window you've forgotten about. The Security page shows the running state inline — "Turns back on at …" while a protection is off on a timer, and "Turned back on at …" for a window that has already lapsed. :::note Arbitrary contract calls are now enable-framed The toggle used to read "Disable arbitrary contract calls", off by default. It now reads **"Enable arbitrary contract calls"**, on by default — the same behaviour (calls allowed until you say otherwise), stated the way round that matches the timer, which grants the permission for a window rather than suspending a protection. If you're calling the API, prefer `PATCH /user/security/arbitrary-contract-calls` with `{ enabled, durationMinutes? }`; the old negative-framed route still works but is deprecated. ::: ## Response channels Response channels have their own tab on the Security page and control which platforms Bankr replies to you on. Every channel is on by default. A row appears for each social account you've linked — **X (Twitter)**, **Farcaster**, and **Telegram**. Turning one off stops Bankr replying to you there; your messages still land in chat history, so re-enabling the channel doesn't lose anything said in the meantime. Telegram's `/start` and wallet-linking commands stay live regardless, so switching replies off can never lock you out of account management. ## Pricing & fail-closed behavior Bankr prices each transaction at submission time using on-chain quotes (0x for EVM, Jupiter for Solana). If pricing is unavailable and a USD limit is enabled, the transaction is **rejected** rather than waved through. Disable the limit if you need to proceed unpriced. ## Recipient cooldown Newly-added entries on the permitted-recipients list wait the configured cooldown (default 24h) before they're usable. Re-adding a previously-removed recipient restarts the cooldown. Your own EVM and Solana addresses are always implicitly allowed. ## Spend tracking Successful transactions are recorded in a per-wallet spend log, idempotent on transaction hash, so retries can't inflate the daily counter. Limit, stop, DCA and TWAP order fills count too: each fill's sell side is priced and checked against your limits before it swaps. A refused fill waits and retries hourly instead of pausing the order, and Bankr tells you why, at most once a day per order. ## Example error messages ``` This transaction is $2,400.00, above your per-transaction limit of $500. Adjust the limit or disable it in Security settings to proceed. ``` ``` This transaction would push your 24-hour spending past the $500 limit you set in Security settings (spent so far: $410.00, this transaction: $120.00). Adjust the limit or disable it in Security settings to proceed. ``` ``` 0xabc... was added recently and is still in its safety cooldown period. Available in ~12h. Adjust the cooldown in Security settings if needed. ``` ## Multi-factor authentication {#passkey-mfa} Add a second factor to your account under [bankr.bot](https://bankr.bot) → Security: a **passkey** (WebAuthn — Touch ID, Face ID, Windows Hello, or a hardware key), an **authenticator app** (**Set up OTP**, scan the QR code, then enter the app's 6-digit code), or both. An account can hold several passkeys and one authenticator app. **Require MFA** turns on by default when your first factor is a passkey — the passkey is verified as it's enabled, so you can't lock yourself out with a factor that doesn't work. An authenticator app doesn't turn it on; switch **Require MFA** on yourself once the app is set up (it asks for a code first). You can toggle it off anytime (this also asks you to verify). Once MFA is on, it enforces two tiers: - **Login gate** — signing in requires your passkey or a code from your authenticator app. A successful verification is remembered for **7 days** per session, so you're not prompted on every visit. The [Bankr CLI](/cli#email-login) can't run a passkey in a terminal, so `bankr login email` hands you an approval link to verify in the browser instead; with an authenticator app you can also type its code in the terminal (CLI 0.3.45+). That approval is valid for five minutes only. - **Per-operation step-up** — changing any Security setting, adding or removing a factor, or disabling MFA each require a fresh verification (your passkey or a new authenticator code) at the moment you make the change. Each authenticator code works once. Every five wrong codes lock the app's codes, for 15 minutes the first time and twice as long each time after, up to a day, until a right code resets the count; a passkey still works in the meantime. Enforcement lives at the server, so it covers chat, the agent, and the API session alike — a leaked API key still can't touch these settings. You can manage your factors from the same Security page: name, add and remove passkeys, and set up or remove the authenticator app. :::tip Bankr MFA is independent of your social login's MFA. Turn on both — see [Secure Your Account](/security/overview#secure-your-account). Even if your X account is compromised, an attacker without your second factor can't sign in to Bankr or loosen these settings. ::: ## Active sessions The Security page lists every device signed in to your account — OS and browser, approximate location, IP, and last-seen time, with the current session marked. **Log out** any session you don't recognize; the logout takes effect server-side immediately, and if MFA is on, revoking another session asks you to verify with your passkey or authenticator app. Sessions drop off the list after 60 days of inactivity. With MFA on, each session also shows whether it holds a [login gate](#passkey-mfa) verification: **MFA verified until** the date it lapses, or **No active MFA verification**. A device shows the latter until it completes the MFA check and again once its verification lapses. A CLI login shows it once its five-minute approval ends, since the CLI then works from its API key. Email logins from the [Bankr CLI](/cli) (`bankr login email`) are listed here alongside browser sessions and can be logged out the same way. Run `bankr update` first if you signed in with an older CLI — those sessions predate the change and won't appear. **Sign out of all** clears every session at once — including the device you're on, so you'll be signed out here too. It's the right move when you suspect a compromise and don't want to work down the list one row at a time. The action takes two confirmations and, with MFA on, the same MFA step-up as revoking a single session. Reviewing this list periodically is the fastest way to catch an unauthorized login — if you see a session you can't place, log it out and rotate any credentials that may have leaked. --- ## API Keys API keys are account-level credentials that work across every Bankr developer surface — the [Wallet API](/wallet-api/overview), [Agent API](/agent-api/overview), [token launching](/token-launching/overview), and the [LLM Gateway](/llm-gateway/overview). Each key carries its own permissions and access controls, so you can scope a key to exactly what it needs. Pair these per-key controls with the wallet-level controls in [Bankr Terminal](/security/bankr-terminal) — both layers are enforced. Keys are created and managed at [bankr.bot/api-keys](https://bankr.bot/api-keys). All keys share the `bk_...` format. ## Scope every key to least privilege When you generate a key, enable only the surfaces it needs — the [permission flags](#api-key-permissions) are independent: - **Only using the LLM Gateway?** Enable gateway access and nothing else — turn wallet, agent, and token-launch access off, and turn read-only on. - **Turn read-only on** unless the key must transact. New keys are read-write by default. - **Set the IP allowlist** for any key deployed to servers with known egress IPs. A scoped key caps the blast radius: if it leaks, an attacker gets only the surfaces you enabled. ## Use a dedicated agent wallet For production agents, use a separate Bankr account with its own API key and wallet: - **Blast radius isolation** — a compromised key only affects the agent wallet - **Independent controls** — read-only mode, IP allowlist, rate limits scoped to the agent - **Easy revocation** — rotate the agent key without touching your main account Setup: create a separate account at [bankr.bot](https://bankr.bot), generate a key at [bankr.bot/api-keys](https://bankr.bot/api-keys), configure access controls, fund it with only what the agent needs. ## Recommended configurations | Use case | Read-only | IP allowlist | Recipient allowlist | | ------------------ | --------- | ------------ | ------------------- | | Monitoring bot | Yes | Yes | — | | Trading bot | No | Yes | Yes | | Public-facing demo | Yes | No | — | | Dev / testing | No | No | No | ## API Key Permissions Each API key has independent capability flags: | Flag | Default | Description | | ----------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `walletApiEnabled` | Enabled | Access to wallet write operations (`/wallet/swap-quote`, `/wallet/swap`, `/wallet/transfer`, `/wallet/sign`, `/wallet/submit`, `/wallet/x402-pay`) and fee claims | | `agentApiEnabled` | Enabled | Access to AI agent endpoints (`/agent/prompt`, `/agent/profile`, `/agent/job/*`) | | `tokenLaunchApiEnabled` | Enabled | Access to token deployment (`/token-launches/deploy`). Also gates the deploy tool when using the Agent API. | | `llmGatewayEnabled` | Disabled | Access to the [LLM Gateway](/llm-gateway/overview) at `llm.bankr.bot` and to LLM credit top-ups (`/llm/credits/*`) | | `readOnly` | Disabled | Restricts Wallet/Agent API to read-only operations (no transactions). Toggle it on in web settings for keys that must not transact. | | `allowedIps` | Empty (all IPs) | IP allowlist — accepts IPs and CIDR ranges (e.g., `10.0.0.0/24`) | | `allowedRecipients` | Empty (all addresses) | Wallet allowlist — restricts which addresses the agent can send funds to | Each flag is configured independently. With an API key, `agentApiEnabled` also gates managing the agent's skills, MCP servers, env vars, profile, files, apps, x402 endpoints and webhooks. A read-only key can list them but not change them. ## Read-Only Mode When `readOnly` is enabled on an API key, the agent can only retrieve information — it cannot execute transactions, swaps, transfers, or any state-changing operations. Use as the default for monitoring bots and public-facing surfaces. ### Behavior by Endpoint | Endpoint | Behavior | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `POST /agent/prompt` | Works, but only read tools are available (prices, balances, analytics, research) | | `GET /agent/job/:jobId`, `POST /agent/job/:jobId/cancel` | Works normally | | `POST /wallet/swap`, `/wallet/transfer`, `/wallet/sign`, `/wallet/submit`, `/wallet/x402-pay` | Blocked — returns 403 | | `POST /token-launches/deploy` and fee claims | Blocked — returns 403 | | Agent management writes | Blocked — returns 403 (skills, MCP servers, env vars, profile, files, apps, x402, webhooks) | | `GET /wallet/me`, `GET /wallet/portfolio`, `POST /wallet/swap-quote` | Works normally | Read-only doesn't cover account management: a read-only key can still buy a Bankr Club subscription and top up LLM credits (with `llmGatewayEnabled`). ### Error Responses **Sign endpoint (403):** ```json { "error": "Read-only API key", "message": "This API key has read-only access and cannot sign messages or transactions. Update your API key permissions at https://bankr.bot/api-keys" } ``` **Submit endpoint (403):** ```json { "error": "Read-only API key", "message": "This API key has read-only access and cannot submit transactions. Update your API key permissions at https://bankr.bot/api-keys" } ``` ### How It Works When a read-only key calls `/agent/prompt`, the agent session receives a system directive that removes all write tools. The following tool categories are filtered out: - Token swaps - Token and ETH transfers - NFT purchases and trades - Staking and unstaking - Limit, stop, DCA, and TWAP orders - Token launches and deployments - Leveraged trading positions - Polymarket bets - Fee claims The agent is aware of the restriction and will explain it to users who request write operations. ## IP Allowlist The `allowedIps` array restricts which IP addresses can use the key. Supports both individual IPs and CIDR ranges. Validation runs in the auth middleware before any endpoint logic. - **Empty array** (default) — all IPs are accepted - **One or more entries** — only requests from listed IPs or CIDR ranges are accepted (e.g., `"192.168.1.1"`, `"10.0.0.0/24"`) Minimum CIDR prefix lengths are enforced to prevent overly broad ranges that would effectively disable the allowlist: `/8` for IPv4 and `/16` for IPv6. Ranges broader than these are rejected at key creation time. **Error response (403):** ```json { "error": "IP address not allowed", "message": "IP address not allowed for this API key" } ``` ## Wallet Allowlist The `allowedRecipients` field restricts which wallet addresses the key can send funds or assets to. It applies to transfers, swaps that pay out to another address, a token launch's fee recipient (a deploy naming an unlisted recipient returns `403 Restricted API key`), and any tool that moves value to an external address. An x402 payment is checked against the payee; for an endpoint hosted on Bankr's x402 Cloud that's the endpoint's payout wallet, not the shared fee router. Most useful for autonomous agents where recipients are LLM-resolved. - **Both lists empty** (default) — all recipient addresses are accepted - **An address on either chain** — both chains are restricted to listed addresses plus the user's own wallet (`/wallet/transfer` accepts only addresses on the EVM list) Each chain has its own list: ```json { "allowedRecipients": { "evm": ["0xabc..."], "solana": ["7xKX..."] } } ``` EVM addresses are stored and matched case-insensitively. You can update `evm` and `solana` independently — omit a chain key to leave it unchanged. **Error response when a blocked address is targeted:** ``` Recipient 0xabc... is not in the trusted addresses list. Contact your API key administrator to add this address. ``` The agent is aware of the restriction and will surface this message if a user requests a transaction to an unlisted address. The API-key allowlist is independent from the wallet-level [Permitted Recipients](/security/bankr-terminal#controls). When both are configured, both must pass: - **API-key allowlist** = where this key is allowed to send - **Wallet allowlist** = where this wallet is allowed to send, regardless of key **Webhooks** — a webhook's agent runs check the webhook's own [`allowedRecipients`](/webhooks/security#3-recipient-allowlist), not the key's. So a key with an allowlist can only deploy or update webhooks whose `allowedRecipients` stay within the key's list; anything wider returns 403. ### Operations blocked outright while an allowlist is set Some operations pay a counterparty the key can't name in advance — the address is chosen by a marketplace, an order book, or a contract at execution time, so there's nothing to check against the allowlist. Rather than let those through unchecked, they're **refused entirely** whenever `allowedRecipients` is non-empty on either chain: - NFT buys, mints (Seadrop and Manifold), listings, and collection offers / offer accepts - Polymarket share buys and sells - Hyperliquid perp and spot trades, closes and deposits, and opening Avantis positions (withdrawing from Hyperliquid to your own wallet still works) - Airdrops - Raw `/wallet/submit` calls, and `eth_signTransaction` / `eth_signTypedData_v4` requests on `/wallet/sign` ``` Buying Polymarket shares is not supported when trusted-recipient restrictions are configured on this API key — the counterparty address cannot be validated against the allowlist. Contact your API key administrator. ``` An allowlist on **either** chain locks these down on both — a key hardened for EVM is treated as hardened for uncontrolled-counterparty operations everywhere. If a key needs these operations, leave `allowedRecipients` empty and bound the key with the [IP allowlist](#ip-allowlist) and the wallet-level [USD limits](/security/bankr-terminal#controls) instead. ## Rate Limits ### Daily Message Limits The `/agent/prompt` endpoint requires a [Bankr Club subscription](/faq/bankr-club) or [Max Mode](/llm-gateway/max-mode) with LLM credits. There is no free tier. | Tier | Daily Limit | Requirement | | ---------------- | ------------------------------------------------------------------------------------------------- | ---------------------------- | | Max Mode | 100 messages | LLM credit balance > $0 | | Bankr Club | 1,000 messages | Active subscription ($20/mo) | | Custom (per key) | Set by Bankr for specific keys — not editable at [bankr.bot/api-keys](https://bankr.bot/api-keys) | — | Custom limits override both the Max Mode and Bankr Club defaults. The limit uses a **rolling 24-hour window** from the time of first usage — it does not reset at midnight. **Error response (429):** ```json { "error": "Daily limit exceeded", "message": "You have reached your daily API limit of 100 messages. Upgrade to Bankr Club for 1000 messages/day. Resets at 2025-01-15T12:00:00.000Z", "resetAt": 1736942400000, "limit": 100, "used": 100 } ``` The `resetAt` field is a Unix timestamp (milliseconds) indicating when the counter resets. The `limit` and `used` fields show the current quota and consumption. :::note The "Upgrade to Bankr Club" portion of the message only appears for Max Mode accounts. Bankr Club members and accounts with a custom daily limit see a shorter message without the upgrade prompt. ::: ### Other Rate Limits Endpoints carry their own limits and answer `429` when one is hit. The ones an integration is most likely to meet: | Scope | Limit | | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | | Wallet writes (`/wallet/transfer`, `/wallet/swap`, `/wallet/sign`, `/wallet/submit`) | 10 requests per minute per IP, shared | | API key creation (bankr.bot and `bankr login`) | 20 per hour per IP — `429` "Too many API key creations. Please try again later." | | External orders (`/trading/order`) | 10 requests per second per API key | ## API Key vs LLM Gateway Key A single API key can serve both the Agent API and the LLM Gateway when both flags are enabled. You can also use separate keys: | Config | Agent API | LLM Gateway | | ------------- | --------------- | --------------- | | Single key | `BANKR_API_KEY` | Same key | | Separate keys | `BANKR_API_KEY` | `BANKR_LLM_KEY` | In the CLI: - `bankr login --api-key KEY` sets the Agent API key - `bankr login --llm-key KEY` sets the LLM Gateway key - `bankr config set llmKey KEY` updates the LLM key independently **When to use separate keys:** - Different permission requirements (e.g., agent key is read-only, LLM key only needs gateway access) - Independent revocation — rotate one without affecting the other - Different rate limit tracking ## Layer wallet-level controls on top Even with a hardened API key, the [Bankr Terminal](/security/bankr-terminal) controls still apply. We recommend setting a daily USD limit and a per-transaction limit appropriate for the agent's purpose — they cap total damage if the key is misconfigured or compromised. ## Incident response If you suspect a key is compromised: 1. **Pause** the wallet at [bankr.bot](https://bankr.bot) → Security. Halts every outbound transaction immediately, including in-flight broadcasts. Revoking the key alone does not stop transactions already past auth. 2. **Rotate** the key with **Rotate Key** in its settings at [bankr.bot/api-keys](https://bankr.bot/api-keys) — the replacement keeps every permission flag, allowlist and custom limit, and the old key stops working at once. Update your deployments with the new secret, or revoke the key outright if nothing needs it. 3. **Audit** — review recent transactions and agent job history before unpausing. --- ## Skills Skills are portable instruction packs (a `SKILL.md` file plus optional reference docs) that teach an agent a new capability. The Bankr ecosystem uses skills in **two directions**, and they're easy to confuse — this page exists so you don't. ## The two directions ### 1. Add Bankr to your agent You're using a coding agent or assistant elsewhere — Claude Code, OpenClaw, Cursor, or any other framework that supports skills — and you want it to be able to trade tokens, manage a portfolio, place bets on Polymarket, and so on. Install **the Bankr skill** into that agent. Bankr is the skill, your agent is the host. → [Install the Bankr skill in your agent](/skills/for-other-agents/installation) ### 2. Add skills to your Bankr agent You're running a Bankr agent (the one at [bankr.bot/terminal](https://bankr.bot/terminal)) and you want to extend it with new behaviors — domain-specific workflows, custom playbooks, integrations with services Bankr doesn't natively know about. Install skills **into Bankr**. Bankr is the host, the new skills are guests. → [Add skills to your Bankr agent](/skills/in-bankr/from-github) ## Same format, both directions Either way, a skill is just a `SKILL.md` file with YAML frontmatter and a markdown body, optionally accompanied by a `references/` folder of supporting docs. The same skill file can often work in both directions with no changes. → [SKILL.md format reference](/skills/in-bankr/skill-format) ## Where to next - New to Bankr and using another agent? Start with [Install the Bankr skill](/skills/for-other-agents/installation). - Already using your Bankr agent and want to extend it? Start with [Install a skill from GitHub](/skills/in-bankr/from-github). - Building something to share? See [Contribute a skill](/skills/for-other-agents/contributing-skills) for the public catalog, or [Create a skill manually](/skills/in-bankr/manually) for one that lives in your own agent. --- ## Install the Bankr Skill Add Bankr capabilities to your skills-compatible agent in one command. ## Installation :::tip Install in your agent Tell your agent: > install the bankr skill from https://github.com/BankrBot/skills/tree/main/bankr > ::: That's it. Your agent now has access to all Bankr features. This works in any framework that supports the [SKILL.md format](/skills/in-bankr/skill-format) — Claude Code, OpenClaw, Cursor, and others. :::tip Your agent can help with setup After installing the skill, your agent can walk you through login, LLM gateway configuration, and access controls. Just ask: > help me set up my Bankr API key and LLM gateway > ::: ## What Gets Installed The Bankr skill enables your agent to: - **Trade tokens** on every [supported chain](/getting-started/supported-chains) - **Launch tokens** and earn trading fees - **Set automations** like DCA, limit orders, and stop-losses - **Check balances** and portfolio values - **Query prices** and market data - **Place bets** on Polymarket - **Trade with leverage** via Hyperliquid (primary) or Avantis on Base ## Try It Out After installation, test with these commands: ``` "what is the price of ETH?" "what are my balances?" "buy $5 of BNKR on base" ``` ## Use a Dedicated Agent Wallet :::warning Don't use your personal wallet Your API key is tied to a Bankr wallet, so an agent holding your personal key can move your personal funds. Create a separate Bankr account for the agent, fund it with only what it needs, and scope its key — read-only if it only queries data, an IP allowlist for servers. See [API Keys](/security/developer-api#use-a-dedicated-agent-wallet) for setup and recommended configurations. ::: ## Updating and Uninstalling Tell your agent `update the bankr skill` or `uninstall the bankr skill`. ## Troubleshooting ### "Skill not found" Ensure you're using the correct URL: ``` https://github.com/BankrBot/skills/tree/main/bankr ``` ## Next Steps - [Other available skills](/skills/for-other-agents/available-skills) — Skills from Bankr and partners you can install alongside the Bankr skill - [Contribute a skill](/skills/for-other-agents/contributing-skills) — Build and share your own skills in the public catalog - [Add skills to your Bankr agent](/skills/in-bankr/from-github) — The other direction: extending a Bankr agent with new skills --- ## Other Available Skills The public skills catalog at [github.com/BankrBot/skills](https://github.com/BankrBot/skills) holds skills from Bankr and partner projects that you can install alongside the Bankr skill. Its README lists every skill with a description, and the same catalog is browsable in the **Skills** section of the [Bankr terminal](https://bankr.bot/terminal/skills). ## Repository Structure Each skill is a top-level folder named for the skill: ``` skills/ ├── bankr/ │ ├── SKILL.md │ ├── catalog.json │ └── references/ ├── erc-8004/ │ ├── SKILL.md │ ├── catalog.json │ ├── references/ │ └── scripts/ └── ... ``` - `SKILL.md` — the skill definition (required) - `catalog.json` — how the skill is listed and installed in the Bankr catalog - `references/` and `scripts/` — optional supporting docs and helper scripts ## Installing a Skill Point your agent at the skill's folder: ``` install the skill from https://github.com/BankrBot/skills/tree/main/ ``` For example: ``` install the erc-8004 skill from https://github.com/BankrBot/skills/tree/main/erc-8004 install the botchan skill from https://github.com/BankrBot/skills/tree/main/botchan ``` --- ## Contribute a Skill Build and share your own skill in the public Bankr skills catalog so users on any framework can install it into their agent. Skills are contributed by pull request to [github.com/BankrBot/skills](https://github.com/BankrBot/skills); the **Adding a Skill** section of its README is the checklist maintainers review against. ## Skill Structure Create a top-level folder named for your skill's slug: ``` your-skill-name/ ├── SKILL.md # required: name + description frontmatter, then the agent instructions ├── catalog.json # required: how the skill is listed and installed in the Bankr catalog ├── logo.svg # recommended: square brand mark (PNG works too) ├── references/ # optional: supporting docs └── scripts/ # optional: helper scripts ``` `SKILL.md` follows the [SKILL.md format](/skills/in-bankr/skill-format). Its `description` is what an agent reads to decide when to use the skill, so make it specific. ## catalog.json `catalog.json` must validate, and its `slug` must equal the folder name: ```json { "schemaVersion": 1, "slug": "your-skill-name", "provider": "Your Brand", "providerUrl": "https://your.site", "logo": "logo.svg", "demo": { "title": "demo.sh", "language": "bash", "code": "..." }, "setup": ["Step one", "Step two"], "install": { "type": "bankr", "repoPath": "your-skill-name", "command": "install the your-skill-name skill from https://github.com/BankrBot/skills/tree/main/your-skill-name" } } ``` A skill that installs from somewhere else uses `"install": { "type": "external", "provider": "Acme", "command": "npx skills add acme/skills", "reference": null }` instead. A folder without a valid `catalog.json`, or whose `SKILL.md` has no `description`, is skipped and won't appear in the Bankr catalog. ## Submitting 1. Fork the repository and create a branch. 2. Add your skill folder. 3. Open a pull request describing what the skill does, with example use cases and any keys, funds or other requirements it needs. Maintainers review the PR. Once it merges, the skill installs from its GitHub folder right away; new and changed skills reach the Bankr catalog after a holding period rather than instantly. ## Guidelines - **Be transparent** — say what the skill does, which services it calls, and what it needs from the user. - **Stay safe** — no malicious or hidden functionality. - **Test before submitting** — run the skill in at least one agent. ## Getting Help - Open a ticket at the [Bankr Help Center](https://help.bankr.bot) - Open an issue on the repository - Email [support@bankr.bot](mailto:support@bankr.bot) --- ## Install a Skill from GitHub Your Bankr agent can install skills directly from any public GitHub repository — or from a bankr.bot skill link. This is the fastest way to add a new capability: point your agent at a repo or a link, and it pulls the skill in. ## Install in one message Tell your agent the GitHub URL of the skill you want: ``` install the skill at https://github.com/owner/repo/tree/main/path/to/skill ``` ``` install the botchan skill from https://github.com/BankrBot/skills/tree/main/botchan install the erc-8004 skill from https://github.com/BankrBot/skills/tree/main/erc-8004 install the skill at https://github.com/your-org/your-repo/tree/main/your-skill ``` Your agent will: 1. Fetch the `SKILL.md` file from the URL. 2. Pull in any files in the skill's `references/` folder. 3. Save the skill to your agent so it's available in future conversations. Reinstalling from the same source replaces the installed copy — that's how updates work. If you already have a *different* skill with that name (one you wrote yourself, or one from another source), the install is refused so it can't overwrite it: rename or delete yours first. ## What URLs work The URL should point to a public GitHub repo, folder, or skill file. All of these are accepted: - A `tree//` folder URL containing a `SKILL.md` at its root - A plain `https://github.com/owner/repo` — the agent uses the `SKILL.md` at the root, or the only one in the repo; if there are several, the install lists them so you can pick one with a `tree/` URL - A `blob///SKILL.md` URL — blob URLs are auto-rewritten to their raw equivalent, so they work too - A direct `https://.../skill.md` file URL (including non-GitHub hosts) - Bare `owner/repo` GitHub shorthand, a GitLab URL, or a `git@host:owner/repo` SSH URL The skill folder can also include a `references/` subfolder of supporting markdown — those files are pulled in alongside `SKILL.md` and become available to your agent on demand. ### bankr.bot links You can also paste a link straight out of Bankr's own skills UI — no GitHub URL needed. Each shape installs the skill the page shows: - `https://bankr.bot/terminal/skills/` — a Discover page - `https://bankr.bot/terminal/skills/partner/` — a partner page, which installs that partner's flagship skill - `https://bankr.bot/skills//` — the public share link from the skill drawer's **Copy share link** button ``` install https://bankr.bot/terminal/skills/partner/ ``` If a link doesn't match a catalog entry, the agent says so rather than trying to fetch the page — a mistyped slug gives you a real error, not a format complaint. For the full file format, see the [SKILL.md format reference](./skill-format.md). ## After installation Once installed, your agent will use the skill automatically when a request matches what the skill describes. You can also review or remove installed skills in the **Installed skills** tab of the terminal's [Skills section](https://bankr.bot/terminal/skills) — see [Create a skill manually](./manually.md) for the same UI from the create side. ## Suggested skills Bankr curates a short list of skills for requests the agent can't handle natively. When you ask for something one of them covers and you haven't installed it, the agent names the skill and offers to install it — and installs it only if you agree. Where the agent can't install skills — for example on a read-only API key — it doesn't make the offer. ## Limits - `SKILL.md` is capped at 1 MB; a larger one fails the install. - Each `references/` file is capped at 100 KB. An oversized reference is skipped and named in the install result, and the rest of the skill still installs. - Other files in the skill folder (scripts, templates, data) are copied into your [file storage](/agent/files) under `/skills//`, up to 2 MB per file and 5 MB per skill; files past either cap are skipped and named. - You can have up to 50 skills. If you hit the cap, remove an unused one in the **Skills** section and retry. ## Troubleshooting ### "SKILL.md not found" Confirm the URL points to a folder that has a `SKILL.md` file at its root, or directly to a `SKILL.md` file, and that the branch in a `tree/` URL exists. GitHub `blob/` URLs are accepted (they're rewritten to their raw form automatically). The repository must be public — a private repo reads as not found, so copy its contents into a skill [manually](./manually.md) instead. ### The skill installed but my agent isn't using it Skills are loaded by description match. If the skill's `description` frontmatter doesn't mention the kind of request you're making, your agent may not pick it up. Tell it explicitly: ``` use the skill to ... ``` If that works, consider rewriting the skill's `description` field so it triggers automatically next time. ## Next steps - [Create a skill manually](./manually.md) — write a one-off skill directly in the agent UI without publishing to GitHub. - [SKILL.md format reference](./skill-format.md) — the file format both install paths share. --- ## Create a Skill Manually Sometimes you want a skill that lives only in your agent — a personal playbook, a one-off automation, a private workflow you don't want to publish on GitHub. The **Skills** section of your agent's terminal lets you write one directly, with no repo and no upload step. ## Open the Skills section Go to [bankr.bot/terminal/skills](https://bankr.bot/terminal/skills). **Your skills** lists the skills you've written, and **Installed skills** the ones you've added [from GitHub](./from-github.md) or the catalog. ## Add a new skill Click **Create Skill** and choose **Code editor**. (**Ask Bankr** instead describes the skill in chat and lets the agent write it; **Fork & pull request** is for [contributing to the public catalog](/skills/for-other-agents/contributing-skills).) An editor opens with two areas: - A file tree on the left, starting with a single `SKILL.md` file. - An editor on the right where you write the file's contents. Fill in the `SKILL.md` body. At minimum it needs YAML frontmatter with a `name` and `description`, followed by the markdown instructions your agent should follow. A starter looks like: ```markdown --- name: my-skill description: One-line description of what this skill does and when it applies tags: [trading, automation] --- # My Skill Step-by-step instructions for the agent... When the user asks about X, do Y. If they ask about Z, follow the workflow in references/z-workflow.md. ``` The `description` field is what your agent uses to decide when to load the skill, so write it clearly and concretely. See the [SKILL.md format reference](./skill-format.md) for the full set of frontmatter fields. ## Add reference files For longer skills, you can split detail out into reference files so the main `SKILL.md` stays concise. In the editor's left sidebar, click **Add reference** and give the file a name (e.g. `api-workflow.md`). A new file appears under `references/` and you can write its contents in the editor. Reference files don't load automatically — the main `SKILL.md` should mention them by filename, and your agent will fetch them on demand. This keeps the always-in-context portion small while letting deep workflows stay available. ## Save Click **Create** (or **Save Changes** when editing). Your agent picks the skill up immediately — no restart, no reload. ## Edit or delete Open a skill from **Your skills** to find **Edit skill** and **Delete**. Editing reopens the same editor with the skill's current contents. Deleting asks you to confirm, then removes the skill and all its reference files. ## When to write a skill manually vs. install from GitHub | Situation | Best path | |-----------|-----------| | Personal playbook, won't share | Write it manually here | | Reusable across team / public | Publish to GitHub and [install from URL](./from-github.md) | | Private but used across multiple agents | Write manually in each, or host in a private GitHub repo and copy in | ## Next steps - [SKILL.md format reference](./skill-format.md) — exact field-by-field spec. - [Install a skill from GitHub](./from-github.md) — for skills shared via a repo. --- ## SKILL.md Format Reference Every skill is a single `SKILL.md` file with two parts: a YAML frontmatter block at the top, and a markdown body with the instructions for the agent. Optionally, a sibling `references/` folder can hold supporting docs. This page describes the file format. The same format is used whether you're [installing from GitHub](./from-github.md), [writing one manually in the Skills tab](./manually.md), or [contributing to the public catalog](/skills/for-other-agents/contributing-skills). ## File layout ``` your-skill/ ├── SKILL.md # required ├── references/ # optional — companion docs │ ├── workflow-a.md │ └── workflow-b.md └── scripts/ # optional — resource files └── helper.sh ``` ## SKILL.md anatomy ```markdown --- name: my-skill description: What this skill does and when the agent should use it tags: [trading, defi] version: 1 visibility: private metadata: clawdbot: emoji: "⚡" homepage: "https://example.com/my-skill" requires: bins: [git, curl] packages: [some-npm-package] --- # My Skill Markdown instructions the agent reads when this skill is loaded. For detailed workflows, see references/workflow-a.md. ``` ## Frontmatter fields ### Required | Field | Type | Description | | ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Short, slug-friendly identifier. This is how the skill is referenced in install commands and the Skills list. | | `description` | string | One-sentence description of what the skill does and when it should be used. **This is what the agent reads to decide whether to load the skill** — write it clearly and concretely. | ### Optional | Field | Type | Default | Description | | -------------------- | --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tags` | array of strings | `[]` | Keywords used for search and filtering, e.g. `[trading, defi, polymarket]`. | | `recommended-models` | array of strings | `[]` | Up to 10 model ids the skill was built for. Advisory: when the conversation runs on another model, the agent mentions it once and carries on. | | `version` | number | `1` | For other hosts. Bankr keeps its own version number, bumped on every edit or re-install. | | `visibility` | `private` \| `public` | `private` | Read when a skill is created in the Skills editor: `public` gives it a share link anyone can install from and submits it for review for the Bankr catalog. Installs from a URL start `private`. | ### Metadata block The `metadata.clawdbot` block carries cross-framework hints — fields that some hosts use for richer display or pre-flight checks. Bankr reads it when it installs a skill from a URL. | Field | Type | Description | | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- | | `metadata.clawdbot.emoji` | string | Single emoji shown next to the skill in lists and UIs. | | `metadata.clawdbot.homepage` | string (URL) | Link to the skill's homepage, repo, or docs. | | `metadata.clawdbot.requires.bins` | array of strings | Command-line binaries the skill expects to be installed (e.g. `[git, curl]`). Hosts may warn the user if they're missing; Bankr's sandbox doesn't install them, or language runtimes such as Python. | | `metadata.clawdbot.requires.packages` | array of strings | npm packages the skill needs. When the agent runs the skill in its sandbox, Bankr installs them first; pin exact versions (`pkg@1.2.3`) for repeatable runs. A version the agent adds for a run must satisfy yours, or the run fails. | ## The body Everything after the closing `---` is the skill's instruction body. It's plain markdown, written for the agent — describe what the skill does, when to use it, what tools or APIs to call, and any edge cases to watch for. A few rules of thumb: - **Be concrete.** "When the user asks about X, do Y" works better than "this skill helps with X." - **Keep it short.** The body lives in the agent's context every time the skill is active. If it's long, move detail into `references/` files and link to them from the body — the agent will fetch them on demand. - **Reference your own files by relative path.** `see references/api-workflow.md` is enough; the agent resolves the file at fetch time. ## Resource files Resource files are binary or text assets that you can attach to a skill — scripts, configuration files, data files, templates, etc. They are stored alongside the skill and accessible to the agent at runtime. ### Creating resource files In the terminal's Skills section, open your skill in the editor and click **Add resources**. Provide a relative path (e.g., `scripts/helper.sh`) and enter the file content. The MIME type is inferred from the file extension. Resource files are stored under `/skills/{skill-name}/{path}` in the agent's virtual filesystem. ### Path rules - Must be a relative path (no leading `/`) - No path traversal (`..`) or empty segments - Max 255 characters ### Using resource files The agent accesses resource files via the `use_skill_file` tool, which loads text content inline (up to 200 KB). For binary files (images, PDFs), the agent receives metadata and can pass the path to CLI tools for processing. Resources are copied on install — when another agent installs your skill, they get their own copy of all resource files. ### Supported file types Text files are rendered inline: shell scripts, Python, TypeScript, JavaScript, JSON, YAML, TOML, SQL, Markdown, CSV, HTML, and others. Binary files (images, PDFs) are handled by reference. ## Reference files Files inside `references/` are optional companion docs. They're not loaded into context automatically — the main `SKILL.md` should mention them, and your agent fetches the relevant one when the situation calls for it. This is the right place for: - Step-by-step workflows that only apply to a subset of requests. - API specs, schema dumps, or long examples. - Edge-case handling notes. Each file is plain markdown. There's no required structure beyond that. ## Frontmatter-less skill files Some skills published for other agents (the Anthropic-style `skill.md` convention) ship without a YAML frontmatter block — just a heading and prose. These still install: Bankr synthesizes the missing `name` (from the first heading) and `description` (from the first prose or blockquote paragraph) and keeps the **full document** as the skill body, losslessly. Frontmatter is still recommended when you author your own skills — it gives you explicit control over `name`, `description`, `tags`, and visibility — but it's no longer a hard requirement for installing an existing one. ## Validation When a skill is installed, the file is validated against this format. The most common errors are: - **Missing `name` or `description`.** A frontmatter block must include both. Bankr derives them only for a file with no frontmatter block at all (see [Frontmatter-less skill files](#frontmatter-less-skill-files)). - **File too large.** `SKILL.md` is capped at 1 MB and each reference file at 100 KB. The editor rejects an oversized file; an install from a URL fails on an oversized `SKILL.md` but only skips an oversized reference. Fix the file and re-install — the same install command will overwrite the previous version. ## Portability A skill written in this format is portable across hosts: the same `SKILL.md` that runs in your Bankr agent will also run in any other framework that supports the format (Claude Code, OpenClaw, Cursor, …). That's the point — write once, install anywhere. ## Next steps - [Install a skill from GitHub](./from-github.md) - [Create a skill manually](./manually.md) - [Contribute a skill](/skills/for-other-agents/contributing-skills) to the public catalog --- ## Token Launching Overview Launch a token for your AI agent and earn trading fees automatically. This is how agents fund themselves. ## Why Launch a Token? When you launch a token through Bankr: 1. **Liquidity pool is created** — Your token is immediately tradeable 2. **Trading fees accumulate** — Every trade generates fees 3. **Fees flow to you** — Claim your earnings anytime 4. **Fund your compute** — Use fees to pay for your agent's API costs 5. **Hold an allocation** — by default, 15% of supply vests to you over 1 year (30-day cliff); on Arc it's opt-in ## Launching via Natural Language Simply tell Bankr what you want to deploy. **Tokens deploy to Robinhood Chain by default** — say `on base`, `on arbitrum` or `on arc` to deploy there instead: ``` "deploy a token called MyAgent with symbol AGENT" "launch a token called CoolBot" ``` Available via the Bankr Terminal, `bankr agent`, and social platforms. ## Launching via Social (Built-in Virality) Deploy directly from X (Twitter) by tagging @bankrbot: ``` @bankrbot deploy a token called MyAgent ``` This creates instant social proof and discoverability for your token. ## Launching via CLI The Bankr CLI provides an interactive wizard for token launches with full control over metadata and fee routing: :::note Chain defaults differ by surface Chat, social and API deploys default to **Robinhood Chain**; the CLI and the web launch form default to **Base**. ::: ```bash # Interactive wizard (recommended for first-time launches) bankr launch # Headless launch with all options bankr launch --name "MyToken" \ --image "https://example.com/logo.png" \ --tweet "https://x.com/user/status/123" \ --website "https://example.com" \ --yes # Launch on Robinhood Chain bankr launch --name "MyToken" --chain robinhood --yes # Launch on Robinhood Chain quoted in tokenized AAPL instead of WETH bankr launch quotes --chain robinhood # list what you can pair with bankr launch --name "MyToken" --chain robinhood --quote AAPL --yes # With fee recipient (route fees to collaborators) bankr launch --name "MyToken" --fee "@partner" --fee-type x --yes ``` The wizard asks for the token name (required), symbol, image, chain (Base, Robinhood Chain or Arbitrum), the quote token — WETH, a [tokenized stock](#stock-paired-launches) or an [additional quote token](#additional-quote-tokens) — creator vesting, fee collection, tweet, website and fee recipient; any flag you pass skips its prompt. All `bankr launch` commands deploy to Base unless `--chain robinhood` or `--chain arbitrum` is passed, and display a summary before confirmation. Use `--yes` to skip confirmation in automated scripts. `bankr launch quotes --chain ` prints the quote tokens a launch can pair with there; pass one to `--quote` by symbol or address. **Install the CLI:** ```bash npm install -g @bankr/cli ``` See the [CLI documentation](/cli#bankr-launch) for full options and examples. ## Launching with OpenClaw For AI agents using [OpenClaw](https://openclaw.ai), the **Token Strategist** skill provides intelligent token planning and deployment: ``` install the skill from https://github.com/BankrBot/token-strategist ``` Token Strategist evaluates your concept against five market forces, sets up fee distribution, and executes launches through the Bankr CLI. This is ideal for agents that need to autonomously manage token economics and deployment strategy. Learn more: [Token Strategist on GitHub](https://github.com/BankrBot/token-strategist) ## Deployment Limits Every Bankr wallet — Standard, Bankr Club, partner organization and provisioned partner wallets alike — gets **3 counted launch attempts per rolling 24 hours**. You can also deploy at most **one token per minute**. On Base, all 3 attempts are eligible for gas sponsorship when the wallet is otherwise eligible; on Robinhood Chain and Arbitrum the launch wallet pays network gas from its own ETH, and on Arc in USDC. Partner sponsorship still follows the organization's sponsorship policy. **A slot is handed back whenever the launch provably never reached the chain.** Bankr reserves quota when a deploy starts and releases it on validation, resolution, pricing and metadata-pinning failures — everything that fails before the deploy is submitted. Submit-stage failures release the slot only when Bankr can prove nothing was broadcast; if a signer error or a timeout leaves that in doubt, the slot deliberately stays counted rather than risk handing back a launch that actually landed. What counts is a completed launch, a launch still in flight, and any failure that may have gone out. Simulations never reserve or consume a slot; retail simulations still run the wallet-age check, but the minimum-balance check stays off. Because simulations are quota-free, they carry their own ceiling: **20 simulations per Bankr wallet per rolling 24 hours**. Exceeding it returns `429` with "Too many launch simulations in the last 24 hours." Partner deploy paths are exempt, as they are from the other retail gates. Quota-free is not the same as always available: a wallet that has already used all 3 counted launch attempts in the window can't simulate either, and gets the same `429` a real deploy would. Simulating still doesn't consume a slot — it just respects an exhausted wallet. The same rule applies to the other launch controls: the per-fee-recipient daily cap and the duplicate-name caps (per wallet and global) count only launches that went out, so a run of failed attempts no longer locks you out of relaunching the same name. After the third counted attempt, wait until the oldest attempt leaves the rolling 24-hour window before trying again. Partner-specific organization and fee-recipient controls still apply in addition to the wallet cap. Separately, Bankr caps deploys from a single network (IP address) at **roughly 10 successful deploys per 24 hours**. Only deploys that succeed are counted — failed attempts and rate-limited requests are not — and deploys made with an org **Partner Key** are exempt, since many end-users share one partner server's IP. Provisioned wallets deploying with their own API key are counted. Exceeding it returns `429` with "Too many token deployments from this network." Treat the number as approximate: the counter lives in the API process serving you and its 24-hour window starts at your first counted deploy rather than each deploy ageing out individually. :::note Retail launch-wallet requirements (anti-sybil) Bankr may require a retail launch wallet to be **at least 24 hours old** (measured from when Bankr created the wallet, not from the age of an X or other social account) and to hold a **minimum native ETH balance on the launch chain**. Both controls are runtime switches; a launch that fails one answers with `TOKEN_LAUNCH_WALLET_TOO_NEW` or `TOKEN_LAUNCH_MIN_BALANCE_REQUIRED`. Even with both off, on Robinhood Chain and Arbitrum the wallet needs enough native ETH to pay the launch's own gas, and Arc launches need **0.5 USDC** (Arc's gas token). A wallet whose only sign-in is an email address still waits **72 hours** before it can launch; this anti-farm control is independent of the switches above. Linking an X, Farcaster or Telegram account lifts it — those identities are what the wait substitutes for. These checks run before Bankr reserves launch quota, pins metadata, or submits a transaction, so an eligibility rejection does not consume a launch attempt or gas. Validated active partner-organization and provisioned-wallet launch paths are exempt from both retail requirements. The exemption is available only while the organization is active with token launching enabled and, for a provisioned wallet, the wallet remains active and linked to that organization. These gates run on every launch path — chat, X, Telegram, `/agent/prompt` and the REST deploy routes alike — so the same answer comes back wherever you launch from. Launching is also unavailable from some regions. A launch blocked by a region or account-shape gate answers with a deliberately generic `TOKEN_LAUNCH_NOT_AVAILABLE`: "Token launches are not available for this wallet right now." If you believe you've hit one of these in error, open a ticket at the [Bankr Help Center](https://help.bankr.bot). ::: :::warning Spam detection High-volume deploys in a short period can trigger Bankr's automated spam protections and result in **temporary or permanent restrictions** on your account. This is enforced hardest on the X (Twitter) path, where a mention can kick off a deploy: repeatedly breaching the one-per-minute limit will **restrict your account for 24 hours** — a limited state, not a lockout (you can still log in, view balances, and withdraw), you just have to wait for it to lift before launching again. Legitimate high-volume use cases (e.g. programmatic deploy products) may be accommodated — open a ticket at the [Bankr Help Center](https://help.bankr.bot) explaining your use case before scaling up. ::: ## Five-Minute Balance Cap For the first **five minutes** after a non-partner Doppler launch, each wallet may hold no more than **2% of the token's total supply**. A buy or transfer that would leave the receiving wallet above 2% fails until the cap expires. This balance cap is separate from the **14-second anti-snipe fee decay**: the anti-snipe mechanism changes the swap fee, while this rule limits the recipient's token balance. Partner launches are exempt. The expiry is encoded on-chain at launch, so existing tokens keep the expiry configured when they launched. ## Fee Structure This section and the launch options below describe Doppler launches (`launch.launchType: doppler`). Arc launches run on [Bankr Launch v3](#bankr-launch-v3-arc) instead, and while v3 rolls out on Arbitrum, an Arbitrum launch that doesn't name a `provider` may be served by v3 as well: the deploy response's `provider` (and `launch.launchType` on `GET /token-launches/{tokenAddress}`) says which path a launch took, and sending `"provider": "doppler"` keeps Doppler. Every trade pays a **0.7% swap fee on the pool** — and **95% of it goes to you, the creator** (0.665% of trading volume). On top of that, the hook adds the **Bankr protocol fee + BNKR buyback and LP fee** — including your token's own **0.285% LP fee**, which automatically compounds as permanently locked liquidity in your pool, deepening your coin's liquidity floor with every trade. All-in, the total swap fee is **1.75%** of trading volume: | Recipient | Share of volume | | ------------------------------------------------------------------------------- | --------------- | | **Creator (you)** — 95% of the 0.7% pool swap fee; paid directly, claim anytime | **0.665%** | | **LP fee** (via hook) — compounds as permanently locked liquidity in your pool | **0.285%** | | Bankr protocol fee (via hook) | 0.475% | | BNKR buyback (via hook — BNKR buybacks + protocol-owned BNKR liquidity) | 0.2375% | | Protocol (Doppler) | ~0.0875% | That's the 0.7% pool fee with 95% going to you, plus the hook-added Bankr protocol fee + BNKR buyback and LP fee — and since the LP fee compounds in your token's own pool, the creator side totals 0.95% of volume. Fees accumulate in your token and the pool's quote token (WETH by default). Use the Terminal or `bankr agent "claim my token fees"` to collect your share. :::note Existing tokens are unaffected Fee schedules are fixed at launch and never change retroactively. Tokens launched earlier keep the schedule they launched with — the creator's 95% of the 0.7% pool fee works the same; only the hook add-on differs. The split above applies to new launches only. ::: ## Token Supply Each token's supply is fixed and non-mintable after deployment. Standard launches use **100 billion tokens**, allocated at launch as follows: | Allocation | Share | Where it goes | | --------------- | ----- | ------------------------------------------------------- | | Liquidity pool | 85% | Seeded into the Uniswap V4 pool — immediately tradeable | | Creator vesting | 15% | Vested to the fee recipient over 1 year (30-day cliff) | ### Creator vesting By default, every Doppler launch premints **15% of supply to the fee recipient** and vests it over **1 year total**, with a **30-day cliff**: nothing unlocks for the first 30 days, then it vests continuously until fully unlocked at the one-year mark (the cliff is _inside_ the one-year window, not added to it). The remaining **85%** seeds the liquidity pool, so trading starts clean. - **Recipient** — the fee recipient set at launch (your own wallet by default, or a third party you designate — the same address that earns the creator fee share). - **Fixed at launch** — the vesting recipient is locked when the token is created and can't be reassigned. [Transferring your fee rights](/token-launching/transferring-fees) later does **not** move the vested allocation; it stays with the original recipient. - **Optional** — you can turn vesting off at launch. Ask the agent to deploy "with no vesting", pick **No vesting** in the web launch flow's Vesting step, or pass `disableVesting: true` to the deploy API (`--no-vesting` in the CLI). With vesting off, **100% of supply** is sold into the pool and no allocation is preminted. A Doppler launch has no custom percentage or schedule — vesting is either the default 15% or off. #### Claiming vested tokens Vested supply sits in the token's own escrow until you release it — it does not land in your wallet automatically. In the web terminal, a **Creator Vesting** section on the token page and the trade panel shows the schedule (cliff date, fully-vested date, percent unlocked) and breaks the allocation into **Total allocation**, **Claimable now**, **Claimed** and **Locked**. **Claim vested tokens** releases everything currently claimable to the vesting recipient's wallet. The same vested row and claim action appear on the launches card and in the token's Manage drawer. Before the cliff the button shows the unlock date instead — nothing is releasable in the first 30 days. The schedule itself is public on-chain data and renders for every viewer; only the vesting recipient can claim. The recipient is fixed at launch and non-transferable — [transferring your fee rights](/token-launching/transferring-fees) does not move the vested allocation. Three endpoints back this: | Endpoint | Auth | Purpose | | --------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /token-launches/{tokenAddress}/vesting` | None | Schedule and position. `?beneficiary=0x…` checks a specific wallet; defaults to the launch's recorded vesting recipient. `404` for non-Bankr tokens. | | `POST /token-launches/{tokenAddress}/vesting/build-claim` | None | Unsigned `release()` transaction for an external wallet to sign locally. `release` only ever pays `msg.sender`, so holding the key is the authorization. | | `POST /token-launches/{tokenAddress}/vesting/claim` | Same as fee claims | Custodial claim from your Bankr wallet. | A claim releases everything releasable at the moment it mines rather than a fixed quoted amount, so it won't revert if a second release lands first — it reverts only when there is genuinely nothing to release. ### Quote-only fees By default, creator fees accrue as a mix of the launched token and the quote token (e.g. WETH). At launch you can instead opt into **quote-only fees**, so all creator fees are collected in the quote token — your total take is identical either way. Ask the agent to "launch a token with quote-only fees", toggle it in the web launch form, pass `quoteOnlyFees: true` to the deploy API, or use `--quote-only-fees` in the CLI. Like the fee schedule itself, this option is fixed at launch. ### Degen mode **Degen mode** starts your token at a **$2,500 market cap** instead of the standard starting valuation — a much smaller float to climb through, so early trades move the chart far harder in both directions. - **Explicit opt-in.** Ask the agent for "degen mode" by name, or flip the **Degen mode** switch in the web launch form; the API takes `degenMode: true`. The agent won't infer it from a token called DEGEN or from generally risk-hungry phrasing. - **Only the starting valuation changes.** Supply, the fee schedule, and creator vesting are exactly as they are on a standard launch. - **Fixed at launch**, like every other launch option, and **$2,500 is the only setting** — there's no custom starting market cap. - **Not available on partner launches.** A deploy that combines an org **Partner Key** with degen mode is rejected. ### Stock-paired launches Instead of pairing the new token's pool with WETH, a launch on **Robinhood Chain** or **Base** can pair it with a registry **tokenized stock** — a Robinhood Stock Token (AAPL, TSLA, NVDA, SPY, and ~190 more) or a Coinbase B20 equity on Base — so the token trades against equity exposure rather than against ETH. - **Listing what you can pair with.** `GET /token-launches/quote-tokens?chain=robinhood` (or `chain=base`) returns every quote token the chain offers, the default first: WETH, then the chain's fixed allowlist (BNKR and musebook on Robinhood Chain; BNKR, ba3Pump, cbHYPE, cbZEC and TAO on Base), then every stock Bankr can price there. Each entry names the deploy field that selects it (`deployField`) and, for stocks, an advisory `illiquid` verdict. The same list backs the web launch form's picker and `bankr launch quotes --chain ` in the CLI. See [List quote tokens](/token-launching/api-reference/list-launch-quote-tokens). - **Choosing one.** Pass the stock's contract address as `pairedStockAddress` in the deploy body (a ticker is rejected — the address pins the deployment on that chain), together with `provider: "doppler"` so the pairing is honoured by the provider that listed it. In the CLI, `bankr launch --chain robinhood --quote TSLA` resolves the symbol for you; the agent takes a ticker or company name ("launch X paired with TSLA on robinhood"). - **Only priceable, active stocks are offered.** The launch curve's tick math needs a live USD price, so a stock whose feed is stale or whose deployment the issuer retired is refused up front rather than failing late. A thin stock pool (`illiquid: true`) still launches — it is just hard to trade until liquidity arrives. - User-key launches only; not available on Arbitrum or on partner-key deploys. Cannot be combined with `pairedTokenAddress`; omit both to use WETH. Deploying a stock-quoted pool has no location gate — only trading the stock leg is geo-verified, like any other tokenized-stock trade. ### Additional quote tokens A launch can quote the new token's pool in one of its chain's fixed allowlisted tokens instead of WETH. In the deploy API, pass the matching `chain` with one of these fixed `pairedTokenAddress` values; each address is valid only on its own chain. **Base** (`chain: "base"`) — **BNKR**, **ba3Pump**, **cbHYPE**, **cbZEC**, or **TAO**. ba3Pump is Bankr-bridged PUMP from Solana; cbHYPE and cbZEC are Coinbase-wrapped crypto assets, not tokenized stocks; TAO is Bittensor's TAO on Base. - BNKR — `0x22af33fe49fd1fa80c7149773dde5890d3c76f3b` - ba3Pump — `0x5577a294ae5a21446a11b0e4100ca83803995720` - cbHYPE — `0xB200000000000000000000451d033a5000cb479e` - cbZEC — `0xB2000000000000000000008501b13360000cb2EC` - TAO — `0xf3081494b87e8d5fb7960f066e931d1d0e6e3d67` cbHYPE and cbZEC remain visible while their reviewed Aerodrome USDC pools are being seeded, but can only be selected or deployed after Bankr verifies at least $10,000 of two-sided pool value and executable depth. Their readiness refreshes automatically; an unavailable price or liquidity check returns a retryable conflict without starting a launch. **Robinhood Chain** (`chain: "robinhood"`) — **BNKR** (the Robinhood Chain BNKR contract, a different address from Base BNKR) or **musebook**, a token launched on Robinhood Chain through Bankr. - BNKR — `0x178E54df3D091EE4D0B2534742eF9e3692b76526` - musebook — `0x91A2DAe9699f0B82540B5886b0d8759C22820bA3` This option is available for user-key launches only and is not offered on Arbitrum. `pairedTokenAddress` cannot be combined with `pairedStockAddress`; omit both to use WETH. Trading volume in the additional quote-token launch pools remains eligible for the weekly developer rebate under the same rules as WETH-quoted launches. :::note Partner / org launches Launches deployed with an org **Partner Key** sell the full 100% into the pool and do **not** include creator vesting. ::: ## Bankr Launch v3 (Arc) Arc launches, and Arbitrum launches that v3 serves during its rollout there, run on **Bankr Launch v3** (`provider: "bankr_v3"`; `launch.launchType` is `bankr_v3`) rather than Doppler, so the fee schedule, supply and launch options above don't apply: - **Pool and fees** — one Uniswap v3 pool at the 1% fee tier, quoted in native USDC (Arc's only quote token and its gas token). Its LP fees split **70% creator / 30% Bankr**; there is no launch fee. - **Supply** — 1 billion tokens. - **Creator vesting is off by default.** Set `launchV3.vestPercent` (whole percent, up to 50) for a 1-year schedule with a 30-day cliff; vested supply plus any dev buy can't exceed 50% of supply. Vested tokens are claimed as in [Claiming vested tokens](#claiming-vested-tokens). - **Dev buy** — `launchV3.devBuy.amount` buys your token with that many USDC as the pool's first swap, inside the launch transaction. - **Fees to holders** — `launchV3.holderSharePercent` (1–100) streams that share of the creator's fees to token holders, paid per `launchV3.holderMode`: `token`, `paired` (USDC) or `both` (the default). `launchV3.holderVestPercent` streams part of the vested slice to holders on the same schedule. - **Receive fees as** — `launchV3.creatorFeeMode`: `quote` (default: token-side fees are sold into USDC gradually, at most 5% price impact per sale), `token`, or `both` (each leg in kind). It changes what you're paid in, never how much. `quoteOnlyFees`, `degenMode` and `disableVesting` are Doppler-only: a v3 launch that sets one to `true` is rejected with `400`. `pairedStockAddress` and `pairedTokenAddress` have no effect on a v3 launch. The launch wallet pays gas in USDC and needs at least 0.5 USDC plus any dev buy. Launch on Arc from chat, the web launch form or the API (the CLI covers Base, Robinhood Chain and Arbitrum); claim and transfer creator fees as in [Claiming Fees](/token-launching/claiming-fees) and [Transferring fees](/token-launching/transferring-fees#bankr-launch-v3-tokens). ## End-to-end Flow Most integrations follow the same three-step lifecycle. Each step has a narrative guide and, for endpoints currently covered, an interactive "Try it" reference. ### 1. Deploy Launch a new token on Robinhood Chain, Base, Arbitrum, or Arc (default Robinhood Chain). Returns the token address, pool and fee split. Pass `"chain": "base"`, `"chain": "arbitrum"` or `"chain": "arc"` in the request body to deploy there — partner deploys remain Base-only, Doppler launches on Arbitrum are WETH-paired (no `pairedStockAddress` / `pairedTokenAddress`), and Arc launches run on [Bankr Launch v3](#bankr-launch-v3-arc) (an Arbitrum launch that doesn't name a `provider` may be served by v3 too while it rolls out there). To quote a pool in something other than WETH, read `GET /token-launches/quote-tokens?chain=` first and send the entry's address in the field it names — see [Stock-paired launches](#stock-paired-launches). - **Interactive reference**: [Deploy a token →](/token-launching/api-reference/deploy-token-launch) - **Endpoint**: `POST /token-launches/deploy` - **Auth**: `X-Partner-Key` (org-level) **or** `X-API-Key` / `Authorization: Bearer` (wallet-level) ```bash curl -X POST https://api.bankr.bot/token-launches/deploy \ -H "Content-Type: application/json" \ -H "X-Partner-Key: bk_ptr_YOUR_KEY" \ -d '{ "tokenName": "MyToken", "tokenSymbol": "MTK", "feeRecipient": { "type": "wallet", "value": "0x…" } }' ``` ### 2. Check fees Query claimable + claimed + historical fees for a Doppler or Clanker token or beneficiary (Bankr Launch v3: `GET /launch-v3/:tokenAddress/fees?account=`). **Unauthenticated**. - **Interactive reference**: [Check fees →](/token-launching/api-reference/get-token-fees) - **Guide**: [Reading Creator Fees →](/token-launching/reading-fees) - **Per-token snapshot**: `GET /token-launches/:tokenAddress/fees?days=30` - **Per-wallet dashboard**: `GET /public/doppler/creator-fees/:walletAddress` - **Scan all beneficiary positions for a wallet**: `GET /public/doppler/beneficiary-fees/:walletAddress` ```bash curl "https://api.bankr.bot/token-launches/0xTokenAddress/fees?days=30" ``` ### 3. Claim Collect your share of trading fees. **One HTTP call** — server auto-detects Doppler, Clanker or Bankr Launch v3, builds the calldata, signs via Privy, and broadcasts. - **Guide**: [Claiming Fees →](/token-launching/claiming-fees) - **Interactive reference**: [Claim token-launch fees →](/token-launching/api-reference/claim-token-launch-fees) - **Endpoint**: `POST /token-launches/:tokenAddress/fees/claim` - **Auth**: `X-API-Key` / `Authorization: Bearer` (user API key) ```bash curl -X POST https://api.bankr.bot/token-launches/0xTokenAddress/fees/claim \ -H "Authorization: Bearer $BANKR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Response: `{ transactionHash, status, signer, chainId, description, blockNumber?, gasUsed? }`. > **External wallets** (Safe multisig, hardware wallets, third-party signers) use the batch-capable public endpoint `POST /public/doppler/build-claim` — see [Claiming Fees](/token-launching/claiming-fees) for the self-custody flow. ## Discover Recent Launches List the 50 most recent Bankr token launches. **Unauthenticated**. Programmatic access to the data behind [bankr.bot/launches](https://bankr.bot/launches). - **Interactive reference**: [List launches →](/token-launching/api-reference/list-token-launches) - **Endpoint**: `GET /token-launches` ```bash curl https://api.bankr.bot/token-launches ``` ## Next Steps - [Fee Redirecting](/token-launching/fee-splitting) — Route fees to collaborators or treasury - [Claiming Fees](/token-launching/claiming-fees) — How to collect your earnings - [Token Launching API (interactive)](/token-launching/api-reference/overview) — Try lifecycle endpoints from your browser - [Partner API (interactive)](/partnership/api-reference/overview) — Partner-admin endpoints (provision wallets, API keys) --- ## Fee Redirecting Route your share of trading fees to collaborators, treasury wallets, or partners. ## How Fee Redirecting Works The creator's share of trading fees — 0.665% of volume on a Doppler launch, 95% of the 0.7% pool fee — goes to the fee beneficiary address, your Bankr wallet by default. Fee redirecting sends that share to a different address of your choosing; the rest of the split is unchanged (see the [Fee Structure](/token-launching/overview#fee-structure)). It works the same on older tokens, whose fee schedule stays fixed at launch. ## Setting a Fee Beneficiary You can set a fee beneficiary **during deployment** or **after deployment**. ### During Deployment Specify a different beneficiary when deploying: ``` "deploy TeamToken with fees going to 0x1234..." "launch MyToken and make 0xABC... the beneficiary" "deploy a token where fees go to alice.eth" "deploy a token where fees go to @0xdeployer on x" ``` This sets the beneficiary from the start. The specified address receives your creator share (0.665% of trading volume). ### After Deployment The current fee beneficiary can transfer their rights to a new address. [Transferring Fees to a New Wallet](/token-launching/transferring-fees) covers every path, including Bankr Launch v3 (Arc) tokens. #### From the Web Open the token's Trade page (`bankr.bot/terminal/trade/`) and click **Transfer fee recipient** — or **Edit fee recipient** in the token's Manage drawer under **Your Tokens**. You can connect your Bankr wallet or an external wallet to sign the transfer. The modal includes a two-step confirmation to prevent accidental transfers. #### From Chat ``` "transfer my beneficiary share on token 0x1234... to 0x5678..." "change who receives fees for 0x1234... to 0xABC..." ``` :::danger Irreversible Fee beneficiary transfers are **permanent and irreversible**. The entire creator share allocation moves to the new address. Only the current beneficiary can transfer rights. ::: Unclaimed fees follow the share to the new address, so [claim first](/token-launching/claiming-fees) if you want them at the old one. The [creator vesting](/token-launching/overview#creator-vesting) allocation never moves: it stays with the fee recipient set at launch. ## Claiming Redirected Fees Only the **current fee beneficiary** can claim fees: ``` "claim my fees for TokenName" "claim fees for 0x1234..." ``` If you transferred your beneficiary rights to someone else, you can no longer claim fees from that token. The new beneficiary must claim. See [Claiming Fees](/token-launching/claiming-fees) for details. --- ## Reading Creator Fees Query accrued, claimable, and historical creator fees for any Doppler or Clanker token launched through Bankr — programmatically, on-chain, or from the CLI. For a Bankr Launch v3 (Arc) token, read `GET /launch-v3/:tokenAddress/fees?account=0x…` instead. All reads are **unauthenticated** — no partner key or API key required. Use these endpoints to build your own dashboards, trigger claims from an agent, or track earnings across multiple wallets. --- ## REST API The Bankr web app and the `bankr fees` CLI call these same public endpoints. Base URL: `https://api.bankr.bot`. ### Fee data for a token Per-token claimable and claimed fees, daily earnings for charts, and lifetime totals. Cached server-side for 5 minutes. **Request** ```bash curl "https://api.bankr.bot/token-launches/0xTokenAddress/fees?days=30" ``` `days` is optional (default 30, max 90) and controls the `dailyEarnings` window. The older `GET /public/doppler/token-fees/:tokenAddress` path returns the same response but is deprecated. The response schema — per-token `claimable` / `claimed` amounts, `share`, `poolId` and `initializer`, a `dailyEarnings` series and lifetime totals — is in the [Check fees reference](/token-launching/api-reference/get-token-fees). The `initializer` is the Fees Manager contract for this token's pool — the same address you'd call `collectFees(poolId)` on. When a token entry also carries `feesContract` (a [quote-only fees](/token-launching/overview#quote-only-fees) launch, whose creator position lives on the hook), use that address instead. Each token entry also names its launch `chain`. Both `initializer` and `poolId` are stable once a pool is deployed, so cache them. ### Claimable fees for a specific beneficiary Cheap single-address lookup, read live from the chain. Use this to gate a "Claim" button in your UI. **Request** ```bash curl "https://api.bankr.bot/public/doppler/claimable-fees/0xTokenAddress?beneficiary=0xYourAddress" ``` **Response (eligible)** ```json { "eligible": true, "tokenAddress": "0x1234...5678", "share": "57.00%", "claimableFees": { "token0": "0.0042", "token1": "125000.0000", "token0Label": "WETH", "token1Label": "MTK" } } ``` **Response (not eligible)** ```json { "eligible": false, "tokenAddress": "0x1234...5678" } ``` ### All tokens for a creator Returns every Doppler and Clanker token where the address was set as the creator beneficiary at launch, with aggregated totals and unified daily timeline. A position transferred to the address later doesn't appear here — check it per token with the claimable-fees lookup above. **Request** ```bash curl "https://api.bankr.bot/public/doppler/creator-fees/0xYourAddress?days=30" ``` The response has the same shape as **Fee data for a token** above, but `tokens[]` contains one entry per token the address creates, and `dailyEarnings`/`totals` are summed across all of them. --- ## On-chain reads If you want to skip the API entirely, all claimable amounts are live on-chain. Each pool has a **Fees Manager** contract (the `initializer` address returned by the API). The formula: ``` claimable = (currentCumulatedFees + uncollectedInPool - lastCumulatedFeesForBeneficiary) × shares / 1e18 ``` ### ABI (subset) ```solidity function getShares(bytes32 poolId, address beneficiary) view returns (uint256); function getCumulatedFees0(bytes32 poolId) view returns (uint256); function getCumulatedFees1(bytes32 poolId) view returns (uint256); function getLastCumulatedFees0(bytes32 poolId, address beneficiary) view returns (uint256); function getLastCumulatedFees1(bytes32 poolId, address beneficiary) view returns (uint256); function collectFees(bytes32 poolId) returns (uint256 fees0, uint256 fees1); function updateBeneficiary(bytes32 poolId, address newBeneficiary); ``` `collectFees` is used by [claim flows](/token-launching/claiming-fees). `updateBeneficiary` is used by [transfer flows](/token-launching/transferring-fees). ### viem example ```ts const client = createPublicClient({ chain: base, transport: http() }); // Resolve `initializer` + `poolId` from the token-fees API (or the deploy response) const [cumulated, lastClaimed, shares, sim] = await Promise.all([ client.readContract({ address: initializer, abi, functionName: "getCumulatedFees1", args: [poolId], }), client.readContract({ address: initializer, abi, functionName: "getLastCumulatedFees1", args: [poolId, beneficiary], }), client.readContract({ address: initializer, abi, functionName: "getShares", args: [poolId, beneficiary], }), client.simulateContract({ address: initializer, abi, functionName: "collectFees", args: [poolId], account: beneficiary, }), ]); const [uncollected0, uncollected1] = sim.result; const claimableWeth = ((cumulated + uncollected1 - lastClaimed) * shares) / 10n ** 18n; ``` The `poolId` and `initializer` for a token never change, so you can cache them once and re-use them forever. `poolId` is in the deploy response; both come back from every call to `GET /token-launches/:tokenAddress/fees`. --- ## CLI The Bankr CLI wraps the same REST endpoints with a terminal dashboard: ```bash bankr fees # All tokens for your account bankr fees --token 0xTokenAddress # Fees for a single token bankr fees --days 7 # Last 7 days bankr fees --json # Raw JSON — pipe into jq / scripts ``` See the [CLI reference](/cli#bankr-fees-address) for full options. --- ## Building claim transactions (no private key needed) If you hold the private key yourself (e.g. an agent wallet or multisig signer), build unsigned claim transactions via: **Request** ```bash curl -X POST https://api.bankr.bot/public/doppler/build-claim \ -H "Content-Type: application/json" \ -d '{ "beneficiaryAddress": "0xYourAddress", "tokenAddresses": ["0xTokenAddress"] }' ``` Up to 50 token addresses per request. No auth — the signing wallet's private key is the authorization. **Response** ```json { "transactions": [ { "tokenAddress": "0x1234...5678", "tokenName": "My Token", "tokenSymbol": "MTK", "to": "0xFeesManagerAddress...", "data": "0xabcdef...", "chainId": 8453, "gasEstimate": "390000", "maxFeePerGas": "100000000", "maxPriorityFeePerGas": "1000000", "description": "Collect fees for MTK" } ], "errors": [] } ``` Sign each transaction with the beneficiary's key and broadcast. `gasEstimate` already includes a 30% buffer. Per-token errors (e.g. "Address is not a beneficiary for this pool") come back in the `errors[]` array — successful transactions still return alongside them. Each transaction names its `chainId`; the signing wallet needs a little native gas on that chain. See [Claiming Fees](/token-launching/claiming-fees#gas) for the gas-sponsorship rules across all claim paths. --- ## Caching & rate limits - Server-side cache: 5 minutes per `(address, days)` or `(tokenAddress, days)` pair - The `/public/doppler/*` endpoints allow 20 requests per minute per IP and answer `429` beyond that; poll at most every 30s per token - `poolId` and `initializer` never change once a pool is deployed; cache them client-side --- ## Claiming Fees Collect your share of trading fees from your deployed tokens. > Looking to **read** fees without claiming? See [Reading Creator Fees](/token-launching/reading-fees) for REST, on-chain, and CLI options. :::note Doppler launches This page covers Doppler launches — those whose `launch.launchType` is `doppler` (`GET /token-launches/:tokenAddress` reports it). A `bankr_v3` launch (every Arc launch, and any Arbitrum launch whose `provider` was `bankr_v3`) claims from its own Creator Fee Vault or Fee Locker: use the Fees section on the token's Trade page or in **Your Tokens**, `POST /token-launches/:tokenAddress/fees/claim` (it detects v3 launches too), or `GET /launch-v3/:tokenAddress/fees?account=` + `POST /launch-v3/:tokenAddress/fees/build-claim` to self-sign. The v3 Fees section shows the launch's fee recipient and their claimable balance to every viewer, not just to the recipient. To change who receives them, see [Transferring fees → Bankr Launch v3 tokens](/token-launching/transferring-fees#bankr-launch-v3-tokens). ::: ## Who Can Claim Only the **current fee beneficiary** can claim fees from a token. By default, this is the deployer wallet. If you've redirected fees to another address, only that address can claim. ## Your Share You receive **0.665% of your token's trading volume** — 95% of the 0.7% pool swap fee; your token's 0.285% LP fee compounds as locked liquidity in its own pool and never needs claiming. See the [Fee Structure](/token-launching/overview#fee-structure) for the full split. Fee schedules are fixed at launch, and claiming works the same on earlier tokens. ## Checking Your Fees See how much you've accumulated: ``` "check my fees for TokenName" "how much fees have I earned from 0x1234...?" "show all my tokens with unclaimed fees" ``` This shows fees for tokens where you're the current beneficiary. ## Claiming Fees ### From the Web Open the token's Trade page (`bankr.bot/terminal/trade/`) or **Your Tokens** in the terminal and click **Claim fees**. You can connect either your Bankr wallet or an external wallet (e.g. MetaMask, Coinbase Wallet). The page will check your eligibility and show your claimable amounts before you confirm. - **Bankr wallet**: Signs in with your existing Bankr account and executes the claim server-side. **Gas is sponsored by Bankr** on Base, Robinhood Chain and Arbitrum — you can claim with a $0 ETH balance. On Arc nothing is sponsored, so the claim spends a little native USDC from your Bankr wallet. The server submits the `collectFees` transaction via your Privy-managed wallet. - **External wallet**: Connects via WalletConnect/RainbowKit and signs the transaction in your wallet. **You pay the gas** — make sure the wallet holds a little native gas on the token's chain. ### Gas | Claim path | Who pays gas | Gas needed in signing wallet | | ------------------------------------------------------------ | ----------------- | ----------------------------- | | Web UI with Bankr wallet | Bankr (sponsored); on Arc, you | None (a little USDC on Arc) | | Web UI with external wallet | You | A little on the token's chain | | `POST /token-launches/:tokenAddress/fees/claim` (auth'd API) | Bankr (sponsored); on Arc, you | None (a little USDC on Arc) | | `POST /public/doppler/build-claim` + self-sign | You | A little on the token's chain | | CLI `bankr fees claim` (uses your Bankr account) | Bankr (sponsored) | None | | CLI `bankr fees claim-wallet` (your private key, Base only) | You | A little ETH on Base | ### API example — single-call claim (recommended) `POST /token-launches/:tokenAddress/fees/claim` builds, signs, and broadcasts in one call. Auto-detects Doppler, Clanker and Bankr Launch v3. ```bash curl -X POST https://api.bankr.bot/token-launches/0xTokenAddress/fees/claim \ -H "Authorization: Bearer $BANKR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' # → { "transactionHash": "0x...", "status": "success", "signer": "0x...", "chainId": 8453, "description": "..." } ``` Auth: Privy JWT (web) or API key (CLI/partners) via `Authorization: Bearer `. Requires `walletApiEnabled` on the key. Returns a single submitted-tx receipt. Legacy endpoints `/user/doppler/claim`, `/user/doppler/execute-claim`, `/clanker/claim`, and `/agent/doppler/claim` are deprecated: they still respond, with `Deprecation` and `Sunset` headers, but their sunset date has passed — use the unified endpoint. Gas sponsorship covers up to **10 transactions per day** per wallet across all sponsored paths, and at most **$3 of gas per day**; whichever runs out first ends sponsorship until the window resets. This is usually more than enough for fee claims, but high-volume agents claiming many tokens daily, or claiming on Robinhood Chain during a fee spike, should account for these ceilings. This matters for agent wallets and partner integrations: if you don't pre-fund agent wallets at creation, route claims through a Bankr-managed wallet or the authenticated claim endpoint to avoid the chicken-and-egg problem of needing ETH to claim ETH. ### From Chat Collect your earnings via natural language: ``` "claim my fees for TokenName" "claim fees for 0x1234..." ``` ## What You Receive When you claim fees, you receive two assets: | Asset | Description | | --------------------------------- | -------------------------- | | Your token | Your share of the swap fee | | The quote token (WETH by default) | Your share of the swap fee | Both accumulate in the Uniswap V4 liquidity pool and are claimed together. :::note Quote-only launches Tokens on the 1.75% schedule claim exactly like earlier launches — your creator share accrues on the pool's fees manager and pays out in both tokens. Only launches with the [quote-only fees](/token-launching/overview#quote-only-fees) option claim from the hook contract's fees manager instead (the claim APIs resolve this automatically), and the entire creator share arrives in the quote token (e.g. WETH) — there is no launched-token leg. ::: ## Claim Frequency You can claim at any time. There's no minimum threshold, but consider gas costs when claiming small amounts. ## Viewing Your Tokens See all tokens where you're a fee beneficiary: ``` "show all my deployed tokens" "list my tokens with fees" "check what tokens I'm a beneficiary for" ``` ## Fee Dashboard (CLI) The Bankr CLI includes a dedicated fee dashboard that gives you a full picture of your historical earnings and projections: ```bash bankr fees ``` The dashboard displays: - **Claimable and claimed WETH** at a glance - **Daily earnings chart** with bar graph and sparkline visualization - **Key statistics**: total earned, daily average, best day, active days, and current streak - **Projected earnings**: estimated monthly and yearly income based on your daily average - **Per-token breakdown**: claimable and claimed amounts for each token you've deployed You can customize the lookback period (1–90 days) and look up fees by token address: ```bash bankr fees --days 7 # Last 7 days bankr fees --token 0xTokenAddress # Fees for a specific token bankr fees --json # Raw JSON for scripting ``` To claim directly from the CLI: ```bash # Claim a single token (requires Bankr account) bankr fees claim 0xTokenAddress # Claim all fees for any wallet using your own private key (no Bankr account needed) bankr fees claim-wallet ``` The `claim-wallet` command automatically reads `BANKR_PRIVATE_KEY` from a `.env` file in the current directory, derives your wallet address, scans all launches where you're a beneficiary, and lets you claim in bulk. It signs on Base only and skips launches on other chains — claim those from the web with your external wallet, or build them with `POST /public/doppler/build-claim`. See the [CLI documentation](/cli#bankr-fees-claim-wallet-address) for full details. ## For Partners If you're a Bankr partner deploying tokens via the [Deploy API](/token-launching/api-reference/deploy-token-launch), your partner wallet accumulates a share of trading fees from every token launched through your integration. Use `claim-wallet` to claim fees across all your tokens in bulk: ```bash # Set your partner wallet private key in .env echo "BANKR_PRIVATE_KEY=0xYourPartnerWalletKey" > .env # Scan all launches and claim fees bankr fees claim-wallet --all --yes ``` This is the recommended way for partners to collect their fee share. It scans all launches where your wallet is a beneficiary (creator, partner, or any other role), shows claimable amounts, and submits claim transactions directly. ## Troubleshooting **"No fees to claim"** - Your token may not have had recent trading activity - Fees might have already been claimed - Check if fees have accumulated: `"check my fees for TokenName"` **"Not authorized to claim"** - You must be the current fee beneficiary for the token - If you transferred beneficiary rights, the new beneficiary must claim - Check who the current beneficiary is: `"who is the beneficiary for 0x1234...?"` - To move beneficiary rights to a new wallet, see [Transferring Fees to a New Wallet](/token-launching/transferring-fees) --- ## Transferring Fees to a New Wallet Change who receives trading fees on an already-launched token — useful when moving from an EOA to a multisig, handing ownership to someone else, or rotating keys. Which path applies depends on how the token launched: `GET /token-launches/:tokenAddress` reports it as `launch.launchType`. Everything up to [Bankr Launch v3 Tokens](#bankr-launch-v3-tokens) describes a `doppler` launch; a `bankr_v3` launch (every Arc launch, and any Arbitrum launch whose `provider` was `bankr_v3`) transfers through its own contracts and endpoints, so skip to that section. ## Who Can Transfer Only the **current fee beneficiary** can transfer their share. If you're already the deployer, that's you. If fees were transferred to you previously, you're the current beneficiary. On-chain the transfer is a call to `updateBeneficiary(poolId, newBeneficiary)` on the Fees Manager contract — only the current beneficiary's signature is valid. ## What Happens to Already-Accrued Fees The beneficiary transfer is **forward-only on the pool's share pointer**. Fees already in the pool go to whoever is the beneficiary **at claim time**, not whoever was the beneficiary when they accumulated. If you want to collect pre-transfer fees at the old wallet, [claim them first](/token-launching/claiming-fees), _then_ transfer. ## Paths ### Bankr wallet (gas sponsored) If the current beneficiary is a Bankr-managed wallet, execute server-side — no ETH needed in the wallet. - **Web**: **Transfer fee recipient** on the token's Trade page (`bankr.bot/terminal/trade/`), or **Edit fee recipient** in its Manage drawer under **Your Tokens** - **Chat**: `"transfer fees for 0xTokenAddress to 0xNewWallet"` - **Authenticated API**: `POST /user/doppler/execute-transfer-beneficiary` with your Privy JWT ### External wallet (self-sign) If you hold the private key yourself (EOA, Ledger, etc.), use the public helper to build an unsigned transaction and sign locally. No authentication required — your signature _is_ the authorization. **Request** ```bash curl -X POST https://api.bankr.bot/public/doppler/build-transfer-beneficiary \ -H "Content-Type: application/json" \ -d '{ "tokenAddress": "0xTokenAddress", "currentBeneficiary": "0xOldWallet", "newBeneficiary": "0xNewMultisig" }' ``` **Response** ```json { "to": "0xFeesManagerAddress...", "data": "0xabcdef...", "chainId": 8453, "description": "Transfer fee beneficiary for MyToken" } ``` Sign and broadcast with the **current beneficiary's** private key on the chain named by `chainId`; the signing wallet needs a little native gas there. If `currentBeneficiary` isn't actually a beneficiary on this pool, the endpoint returns `403`. ### Direct on-chain If you'd rather skip the API and encode the call yourself, the ABI is: ```solidity function updateBeneficiary(bytes32 poolId, address newBeneficiary); ``` Call it on the pool's Fees Manager (the `initializer` address returned by `GET /token-launches/:tokenAddress/fees`). See [Reading Creator Fees → On-chain reads](/token-launching/reading-fees#on-chain-reads) for resolving `initializer` and `poolId`. For [quote-only fees](/token-launching/overview#quote-only-fees) launches on the 1.75% schedule, the creator's fee entry lives on the **hook contract** instead — its fees manager sits at the hook address, not the initializer. Call `updateBeneficiary` there. Default launches keep the creator's entry on the initializer as before. The API paths above resolve the correct contract for you either way. ## Bankr Launch v3 Tokens Launch v3 tokens don't have a Doppler Fees Manager, so `updateBeneficiary` and the `/public/doppler/*-transfer-beneficiary` endpoints don't apply to them. The creator position lives on one of two contracts, and the API resolves which for you: | Creator fee mode | Contract | Call | | -------------------------------- | ----------------- | -------------------------------------- | | `quote` (the default) or `token` | Creator Fee Vault | `setBeneficiary(token, newRecipient)` | | `both` — fees paid in kind | Fee Locker | `setFeeRecipient(token, newRecipient)` | So a default Arc launch transfers through the **vault**; a vault launch whose creator fee beneficiary was never set falls back to the locker. The API resolves this for you, so you don't need to know the launch's mode to transfer. Only the **current** recipient (or vault beneficiary) can hand the position on — the contract re-checks the signer. ### Web Open the token's Trade page (`bankr.bot/terminal/trade/`) and use **Transfer fee recipient** in the Fees section. The v3 Fees section shows the launch's fee recipient and their claimable balance to **every** viewer — you no longer have to be signed in as the recipient to see what's waiting — while the transfer and claim actions still require the recipient's signature. ### Bankr wallet (server-signed) ```bash curl -X POST https://api.bankr.bot/launch-v3/0xTokenAddress/recipient/transfer \ -H "Content-Type: application/json" \ -H "x-access-token: " \ -d '{ "newRecipient": "0xNewMultisig" }' # → { "txHash": "0x..." } ``` Signed server-side with your Bankr wallet. Returns `403` when the signed-in wallet isn't the current recipient, `400` when `newRecipient` already receives the token's fees, and `404` when the token isn't a Launch v3 token on a chain where v3 is deployed. Arc is not gas-sponsored, so an Arc transfer spends native USDC from the signing wallet — keep a little there. ### External wallet (self-sign) ```bash curl -X POST https://api.bankr.bot/launch-v3/0xTokenAddress/recipient/build \ -H "Content-Type: application/json" \ -d '{ "account": "0xCurrentRecipient", "newRecipient": "0xNewMultisig" }' # → { "transaction": { "to": "0x...", "data": "0x...", "value": "0x0", "chainId": 5042, "description": "..." } } ``` No authentication — your signature is the authorization. Sign and broadcast the returned transaction with the **current recipient's** key on the chain named by `chainId`. ### What happens to already-accrued fees On the locker path, changing the recipient first settles the fees accrued so far to the outgoing recipient (best effort). On the vault path the change is forward-only, as on Doppler: fees already in the vault go to whoever is the beneficiary **at claim time**, so claim from the token page's Fees section first if you want them at the old wallet. ## Multisig Migration (common partner flow) Moving a partner fee wallet (or a personal EOA) to a multisig typically means running the transfer once per launched token. Workflow: 1. Pull the list of tokens where the old wallet is a beneficiary: ```bash curl "https://api.bankr.bot/public/doppler/creator-fees/0xOldWallet" ``` 2. For each `tokens[].tokenAddress`, build a transfer transaction (see above) 3. Sign and broadcast each with the old wallet's key 4. Optionally update your [Fee Wallet configuration](/partnership/token-launching#fee-wallet-configuration) so **future** launches route to the multisig automatically Changing the Fee Wallet setting in the Token Launch tab is forward-only — it does not touch existing tokens. See [Fee Wallet Retroactivity](/partnership/token-launching#retroactivity). ## Gas | Path | Who pays gas | Gas needed | | ---------------------------------------------------------------- | ----------------------------------------------- | ----------------------------- | | Bankr wallet via web UI, chat, or `execute-transfer-beneficiary` | Bankr (sponsored, up to 10 tx or $3 of gas/day) | None | | External wallet via `build-transfer-beneficiary` + self-sign | You | A little on the token's chain | | Direct on-chain `updateBeneficiary` call | You | A little on the token's chain | ## Troubleshooting **"Address is not a beneficiary for this pool"** — the `currentBeneficiary` you passed doesn't hold shares in the pool. Double-check it matches the creator / current beneficiary. Query `GET /public/doppler/claimable-fees/:tokenAddress?beneficiary=0x...` to verify. **Transaction reverts** — the signing wallet must be the current beneficiary. If you recently transferred the beneficiary away, your old wallet no longer has permission. **Accrued fees disappeared after transfer** — they didn't disappear. They're now claimable by the new beneficiary (see [What Happens to Already-Accrued Fees](#what-happens-to-already-accrued-fees) above). --- ## Glidepath Glidepath is an AI-paced exit for builders. It lets you take profit in your own token **gradually** — fed back into the pool in slices so small the market barely registers them — instead of dumping your stack and nuking your own chart. Your tokens, your terms, with your chart and reputation intact. ![Without Glidepath, one big sell craters the chart; with Glidepath, the same tokens are sold in tiny slices the market absorbs while price keeps trending up.](/img/glidepath-comparison.svg) ## The problem it solves Builders earn fees in their own token. The moment they sell that stack into the pool, the chart craters, holders get wrecked, and trust evaporates — and they torch their own long-term upside doing it. The mere _possibility_ of that dump is just as damaging. "The dev might sell" is an overhang priced into every launch, capping the bid before anyone actually sells a token. Glidepath removes both problems: the dump and the fear of it. ## What Glidepath is — and isn't **It does not pull liquidity.** Glidepath never touches your pool's LP. It's your own committed tokens, fed back into the pool in small slices — each one sized by AI to live market conditions. Nothing about your liquidity position changes; only the tokens you explicitly commit are sold, gradually, over time. ## Why a steady glide is healthy for the chart Every slice is a tiny fraction of pool depth, spread over time. Organic buy volume absorbs it, so price keeps trending instead of taking a wick. A small, steady, absorbable flow is nothing like a surprise market dump. The chart sees ordinary sell pressure it can digest — not a cliff. :::tip Committing can be bullish Once "the dev might dump" is off the table, buyers price in less risk. The overhang that caps every launch disappears. **Less rug risk → stronger bid.** A credible, capped, public commitment to glide out can be bullish for your token. ::: ## Fund your project without dumping Before you commit, Glidepath shows what that same stack is worth at **higher** market caps. You don't have to dump to fund your project. Grind the coin up, and the same tokens fund you many times over — your treasury grows _with_ your chart, not against it. The market caps shown on your token page are a value preview, not sell targets: keep building toward them, then come back and start a Glidepath when the time is right. ## How it works 1. **Preview.** Open the **Glidepath** tab in your token's Manage drawer (**Your Tokens** in the terminal) — available for Doppler launches on Base and Robinhood Chain — and enter how much of your token you'd consider gliding out. You'll see what it's worth today and what the same stack would be worth at higher market caps — a what-if preview, not a prediction or a sell price. 2. **Commit.** When you're ready, confirm. Your committed tokens are locked to a vesting wallet. You decide _if_, _when_, and _how much_ — nobody forces a sell. 3. **Heads-up window.** Selling doesn't start immediately. After a short window (about 48 hours), the glide begins selling from the **current market cap** — not from the higher caps in the preview. 4. **AI-paced slices.** The AI analyzes the pool's live liquidity and trading volume to size each sale and its cadence. Every slice is capped to a fraction of real liquidity — the AI can size _under_ the cap, never over — so each sell barely moves the chart. 5. **Transparent envelope.** Your token page shows a live exit envelope — committed, sold, and remaining — so holders always know the full picture. The exact timing of each slice is fuzzed so it can't be front-run. ## You stay in control Nobody forces a sell, and you set the terms. But once you commit, the rules are fixed and public: - Tokens are locked to a vesting wallet. - After the heads-up window, they exit in small slices. - Each slice is capped to a fraction of real liquidity. You can cancel at any time. Sells stop immediately when you do: | When you cancel | What happens | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Within ~30 minutes of committing (before selling starts) | Instant undo — your tokens return to your wallet right away. | | After selling has started | Sells stop immediately; any **unsold** tokens return to your wallet after a 7-day cooldown. | The 7-day cooldown is public: holders see the cancellation before you regain custody. Tokens already sold during the glide can't be reclaimed — those proceeds are yours. ## For holders Holders see a capped, transparent glide instead of a hidden float and a 3am chart nuke. "The dev might dump" becomes a known, capped, visible number on the token page. ## Bottom line - **Creators** — take profit on your terms, chart and reputation intact. - **Holders** — the dev's exit becomes a known, capped, visible number. For once, you and your holders want the exact same thing: number go up. This is what launching on Bankr is meant to mean — credible commitment, built in. ## Related - [Token Launching Overview](/token-launching/overview) — how launches and creator fees work - [Claiming Fees](/token-launching/claiming-fees) — collect your share of trading fees - [Fee Redirecting](/token-launching/fee-splitting) — route fees to collaborators or a treasury --- ## List recent token launches Returns the 50 most recent token launches deployed via Bankr (Doppler and Bankr Launch v3), sorted by `createdAt` descending; each entry's `launchType` says which. **Unauthenticated**. Programmatic access to the data behind [bankr.bot/launches](https://bankr.bot/launches). ## Endpoint ``` GET https://api.bankr.bot/token-launches ``` ## Example ```bash curl https://api.bankr.bot/token-launches ``` ## Response ```json { "launches": [ { "activityId": "65b…", "status": "deployed", "launchType": "doppler", "tokenName": "Example", "tokenSymbol": "EXM", "chain": "base", "tokenAddress": "0x…", "deployer": { "walletAddress": "0x…" }, "feeRecipient": { "walletAddress": "0x…" }, "timestamp": 1714000000000 } ] } ``` --- ## Bankr CLI The Bankr CLI (`@bankr/cli`) is a command-line interface built on top of the Agent API. It handles authentication, prompt submission, job polling, and result display out of the box. ## Installation :::tip Install the CLI ```bash npm install -g @bankr/cli ``` ::: After installing, the `bankr` command is available everywhere: ```bash bankr --version ``` ### Alternative: bun ```bash bun install -g @bankr/cli ``` ### Run without installing ```bash npx @bankr/cli what is the price of ETH? ``` ## Updating Update the CLI to the latest version without remembering your package manager: ```bash bankr update ``` To check if an update is available without installing: ```bash bankr update --check ``` The CLI auto-detects whether you installed with npm, bun, pnpm, or yarn and runs the appropriate global install command. Behaviour that arrived in a specific release is marked on this page, for example (0.3.43+), and the [changelog](./cli-changelog.md) lists what changed in each version. If a command or flag described here is missing from yours, run `bankr update`. ## Setup ### Login Credentials are stored in `~/.bankr/config.json`. You can also set keys via environment variables (`BANKR_API_KEY`, `BANKR_LLM_KEY`). Email and SIWE login create a new API key each time. Key creation (including the web form) is limited to 20 attempts per hour per IP address; past that, login fails with `Too many API key creations. Please try again later.` #### Email login Sign in with your email address. This creates a wallet, accepts terms, and generates an API key — all without visiting the Bankr Terminal. Headless login (`--code` or `--ni`) accepts the [Terms of Service](https://bankr.bot/terms) as part of logging in (0.3.43+; earlier versions need `--accept-terms`), so scripts and agents don't need to pass a flag. By completing a headless login you accept the Terms on the account's behalf. ```bash # Interactive: prompts for email, OTP code, key options bankr login email # Two-step headless login (for scripts and agents): # Step 1 — send OTP, then exit bankr login email user@example.com # Step 2 — verify OTP and complete setup bankr login email user@example.com --code 123456 --key-name "My Key" --read-write --llm ``` | Option | Description | | ------------------- | ------------------------------------------------------------------------------------------------ | | `--code ` | OTP code received via email (step 2 of headless login) | | `--accept-terms` | Accept [Terms of Service](https://bankr.bot/terms) without prompting (implied by headless login from 0.3.43) | | `--key-name ` | Display name for the API key (e.g. "My Agent"). Prompted if omitted; headless runs default to `CLI--