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 Base
3. Earn trading fees — 68% of swap fees flow to your agent’s wallet
4. Pay for compute — Fees fund LLM costs via the LLM Gateway
5. Repeat — The agent keeps running as long as the token has trading activity

Agent Wallet

Every agent gets a cross-chain wallet that works across nine networks:

• Base — Primary EVM chain with gas sponsorship
• Ethereum — ETH mainnet for high-value operations
• Polygon — Low-cost EVM transactions with Polymarket
• Unichain — Uniswap’s native L2 with gas sponsorship
• World Chain — Worldcoin’s L2 with gas sponsorship
• Arbitrum — Leading Ethereum L2 with deep DeFi liquidity
• BNB Chain — Deep DeFi liquidity with gas sponsorship
• Solana — High-speed SVM transactions
• Hyperliquid — High-performance L1 for perpetual futures and spot trading

Gas fees are sponsored by Bankr on Base, Polygon, Unichain, World Chain, and BNB Chain. To start transacting, you’ll need a Bankr Club subscription or LLM credits for Max Mode. See Supported Chains for the full capability matrix.

Token Launching

Deploy a token for your agent and earn trading fees automatically. Tokens launch with a 1.2% swap fee, split as:

Launch via natural language, the CLI, or the Deploy API.

Automatic LLM Payments

The LLM Gateway 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, limit orders, stop orders, DCA, TWAP orders, leveraged trading, Polymarket, NFTs, and 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

Next Steps

• Quick Start Guide — Get running in 5 minutes
• Token Launching — Deploy your agent’s token
• Features Overview — See everything Bankr can do
• LLM Gateway — Route LLM traffic through Bankr

Quick Start

Get your AI agent trading in under 5 minutes.

:::info Subscription Required Bankr requires a Bankr Club subscription ($20/mo in BNKR) or Max Mode with LLM credits to use. Set up your account at bankr.bot. :::

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 :::

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, generate an API key, and enable the features you need (Agent API for prompts, Wallet API for transfers).

2. Send a Prompt

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

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

See the Agent API documentation for full details.

Option 3: Claude Plugins

For Claude Code users, install the Bankr plugin:

claude plugin marketplace add BankrBot/claude-plugins

Then install the specific plugin you need:

• bankr-agent — Trading and Polymarket
• bankr-agent-dev — Developer toolkit

Option 4: Bankr CLI

Install the CLI globally and start prompting from your terminal:

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 for the full command reference.

What’s Next?

Now that you’re connected, explore what you can do:

• Features Table — Complete list of capabilities with example prompts
• Token Launching — Deploy a token and earn trading fees
• Automations — Set up DCA, limit orders, and stop-losses

Supported Chains

Bankr supports nine blockchain networks, each with different capabilities and trade-offs.

Chain Overview

Base

Base is the primary chain for Bankr with the most features enabled.

Capabilities:

• Token swaps via Uniswap V2/V3/V4 and Aerodrome
• Token launching with fee sharing
• Limit orders, stop orders, DCA, TWAP
• NFT buying, selling, and minting
• Leveraged trading via Avantis (commodities, forex, crypto)
• Gas sponsorship for transactions

Block Explorer: Basescan

Ethereum

Ethereum mainnet for high-value operations.

Capabilities:

• Token swaps via Uniswap V2/V3/V4
• NFT buying, selling, and minting

Note: Gas is not sponsored on Ethereum mainnet due to high costs.

Block Explorer: Etherscan

Polygon

Low-cost EVM chain with Polymarket support.

Capabilities:

• Token swaps via Uniswap V2/V3/V4
• Polymarket betting
• NFT buying, selling, and minting
• Gas sponsorship for transactions

Block Explorer: Polygonscan

Unichain

Uniswap’s native L2 chain.

Capabilities:

• Token swaps via Uniswap V2/V3/V4
• NFT buying, selling, and minting
• Gas sponsorship for transactions

Block Explorer: Uniscan

World Chain

World Chain (Worldcoin’s L2) with gas sponsorship.

Capabilities:

• Token swaps via Uniswap V3/V4
• Cross-chain swaps
• Gas sponsorship for transactions

Block Explorer: Worldscan

Arbitrum

Leading Ethereum L2 with deep DeFi liquidity.

Capabilities:

• Token swaps via Uniswap V2/V3/V4
• Cross-chain swaps

Note: Gas is not sponsored on Arbitrum.

Block Explorer: Arbiscan

BNB Chain

BNB Chain (formerly Binance Smart Chain) with deep DeFi liquidity.

Capabilities:

• Token swaps via Uniswap V2/V3/V4

• Cross-chain swaps

• Gas sponsorship for transactions

Block Explorer: BscScan

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

Solana

High-speed SVM chain for fast trading.

Capabilities:

• Token swaps via Jupiter aggregator
• Cross-chain swaps

Note: Gas sponsorship is limited on Solana.

Block Explorer: Orb Markets

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 MATIC 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, 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.
• 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.
• 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 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 Base, claim & transfer trading fees, manage clanker/doppler tokens
• Portfolio: balances, PnL, positions across all 9 supported chains, 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
• 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

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, sign in, and ask what's the price of ETH?
2. Read the Access page to pick between Bankr Club (base model, 1,000 msgs/day) or Max Mode (premium models, pay-per-token).
3. Check 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 — how durable context works
• Access: Bankr Club & Max Mode — pricing and model selection
• Token Launching — the self-funding flywheel for agents
• x402 Cloud — pay-per-request API support
• Skills — install Bankr in another agent, or extend your Bankr agent with new skills
• 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.

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 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 all live there — browsable, editable, and shared across every surface the agent runs on.

Tiers

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)

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.

Uploading From the Web

Open 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, ask a support agent 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 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 (with default Gemini Flash model), or use Max Mode for premium models pay-as-you-go.

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 terminal, resetting at UTC midnight. 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
• 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, XMTP, 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 base model (Gemini 3 Flash) with a generous 1,000 messages/day, 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 — pass a different token (BNKR, ETH, any Base ERC-20) and the agent will swap it 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 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 (Claude Opus, Gemini 3.1 Pro, GPT-5.4, 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, click the Max button above the chat input, then click the model name to pick one.

CLI: pass --model to any prompt:

bankr "analyze my portfolio" --model claude-opus-4.8

See the full Max Mode docs 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:

add $25 in LLM credits

Web: bankr.bot/llm?tab=credits

CLI:

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

Max Mode falls back to the default model (Gemini 3 Flash) and your message still gets processed — nothing fails. Enable auto top-up above to avoid falling back unexpectedly.

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 the 1,000 msgs/day of base-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 and check 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 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 support ticket through the web UI.

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.

To install multiple skills from a repo:

install all skills from https://github.com/BankrBot/skills

Bankr will list the available skill directories and install each one.

See the Bankr skill installation guide for the full repo structure, other available skills, and how to contribute your own via PR.

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 100KB, and each reference file is capped at 100KB. Plenty for prose instructions; not for stuffing a whole repo. :::

MCP Servers

Model Context Protocol 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 any required headers.

Chat: describe the server in plain English:

add an MCP server named "Linear" at https://mcp.linear.app/mcp
with Authorization header "Bearer "

The `` 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.

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.

Using Env Vars

The agent reads env vars automatically when a tool needs them. You refer to a var by name with the `` placeholder, e.g. in an MCP server header:

Authorization: Bearer 

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 `` 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

Limits

Automation limits depend on your account tier:

Managing Automations

"show my automations"
"cancel my limit order"
"pause my DCA order"
"resume my BNKR automation"
"cancel all my automations"

You can also manage automations from the terminal sidebar or via the API:

• GET /user/automation — List active automations
• POST /user/automation/:taskId/pause — Pause an automation
• POST /user/automation/:taskId/resume — Resume a paused automation
• POST /user/automation/:taskId/cancel — Cancel an automation
• DELETE /user/automation/:taskId — Delete an automation

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"

Agent command automations use the same limits as other automation types. Each execution counts as one run against your 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.

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 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:

BROWSER_CREDENTIAL_<SITE>_<FIELD>

<SITE> is a label you choose for the site (letters, numbers, underscores, or hyphens). <FIELD> 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:

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:

BROWSER_CREDENTIAL_SHOP_ALLOWED_ORIGINS=https://shop.example.com,https://checkout.example.com

The full website address has to match exactly — same scheme (https), same subdomain (www.amazon.com is not the same as amazon.com), and no trailing path.

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 — full address with https://, no path. For example, https://www.amazon.com, not https://www.amazon.com/ap/signin.
• 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.

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.

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. 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 maximum USD, the visitor’s wallet settles USDC on Base, 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. Per-(visitor, app) rate limits cap abuse: 10 calls/minute, $10/day.

If you want to publish a paid endpoint that other apps and agents can consume — not just consume one — see x402 Cloud. For the wire-level details on consuming x402 from inside an app see Permissions and the SDK reference.

Sharing & forking

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 — by default, scripts run as the owner so visitors get a consistent view. If a visitor wants their own personalized copy, the app page shows a Fork button: one click duplicates the app under their wallet, where it now runs against their data.

For apps that genuinely need each visitor’s own identity (per-user calculators, viewer-specific trade builders), you can ask Bankr to switch the app to “viewer mode” — the agent flips a single setting in the manifest. See Permissions for the details.

Before flipping an app to public or sharing the unlisted link, walk the public-app checklist — 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 — what an app can read, write, and execute on your behalf.
• SDK Reference — 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.

Write permissions

These let the app change state. They’re more sensitive — Bankr doesn’t grant them unless the app actually needs them.

Network and AI permissions

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:

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" makes sense for per-visitor tools — a calculator, a “score MY positions” widget, a personal trade plan. Each visitor’s wallet drives the script.

If a visitor on a shared dashboard wants the same thing pointed at their data, they don’t need to argue with the manifest — they just click Fork and get their own copy under their wallet.

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).
• Cannot trigger scripts — anonymous viewers see a sign-in prompt for any button that runs server-side code.
• 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 "<k>" 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.invokeScript, bankr.appKV.set, bankr.askChat, and bankr.confirmTransaction always 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:

// manifest.json
{
  "permissions": ["read:portfolio", "read:appdata", "write:appdata"],
  "publicDataKeys": [
    "portfolio_snapshot",
    "portfolio_history",
    "meta.refreshedAt"
  ],
  "schedule": [
    { "script": "refreshSnapshot", "cron": "*/15 * * * *", "enabled": true }
  ]
}

// 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 };

<!-- index.html — runs in the public iframe -->
<script>
  bankr.on("ready", async () => {
    const [snapshot, history, meta] = await Promise.all([
      bankr.appKV.get("portfolio_snapshot"),
      bankr.appKV.get("portfolio_history"),
      bankr.appKV.get("meta.refreshedAt"),
    ]);
    render(snapshot, history, meta);

    // Owner-only "edit notes" — gated, never thrown for visitors.
    if (bankr.ctx.isAuthenticated) {
      const notes = await bankr.appKV.get("private_notes");
      renderNotes(notes);
    }
  });
</script>

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
switch this to viewer mode so each user sees their own positions

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 — the methods each permission unlocks.
• 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.

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

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<void>;
  };

  // Trigger a backend script.
  invokeScript(name: string, args?: Record<string, unknown>): Promise<unknown>;
  // Aliases (all identical):
  runScript(name: string, args?: Record<string, unknown>): Promise<unknown>;
  run(name: string, args?: Record<string, unknown>): Promise<unknown>;
  scripts: {
    run(name: string, args?: Record<string, unknown>): Promise<unknown>;
    invoke(name: string, args?: Record<string, unknown>): Promise<unknown>;
  };

  // Persistent key-value store, server-mediated.
  appKV: {
    get(key: string): Promise<unknown | null>;
    set(key: string, value: unknown): Promise<void>;
    list(prefix?: string): Promise<string[]>;
    delete(key: string): Promise<void>;
  };

  // Hand off to chat.
  prefillChat(message: string): Promise<void>;
  askChat(message: string): Promise<void>;
  chat: {
    prefill(message: string): Promise<void>;
    send(message: string): Promise<void>;
    ask(message: string): Promise<void>;
  };

  // Transaction confirmation. The blob comes from a backend script.
  confirmTransaction(blob: unknown): Promise<void>;

  // Visitor-paid x402 fetch — settles USDC on Base 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;
        headers?: Record<string, string>;
        maxPaymentUsd?: number;
      },
    ): Promise<{
      status: number;
      ok: boolean;
      body: unknown;
      payment: { amountUsd: number; network: string; payTo: string };
    }>;
  };

  // Skill management.
  installSkill(slug: string): Promise<void>;

  // UI helpers.
  openExternal(url: string): Promise<void>;
  copy(text: string): Promise<void>;
  navigate(page: string): Promise<void>;

  // Secrets — status only. The plaintext NEVER reaches the iframe.
  secrets: {
    status(): Promise<Array<{
      key: string;
      scope: "author" | "viewer";
      required: boolean;
      set: boolean;
      preview?: string;
    }>>;
    requestSetup(key: string): Promise<void>;
  };

  // Pass context back into the chat thread (e.g. "user is viewing X").
  setContext(body: string, label?: string): Promise<void>;
};

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:

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:

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 max USDC; on Approve it settles via the visitor’s wallet on Base and returns the upstream response.

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: JSON.stringify({ prompt }),
        headers: { 'content-type': 'application/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:

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

Per-(visitor, app) rate limits apply: 10 calls/min, $10/day cap.

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.

// 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<WalletPortfolioResult>;

// File storage. Permission: read:files / write:files.
bankr.files.read({ path }: { path: string }): Promise<{ content: string; ... }>;
bankr.files.write({ path, content, mimeType? }): Promise<{ fileId; ... }>;
bankr.files.list({ folder?, limit? }): Promise<UserFileSummary[]>;
bankr.files.search({ query, folder?, mimeType? }): Promise<UserFileSummary[]>;

// On-chain reads. Permission: read:chain.
bankr.chain.readContract({ chain, address, abi, functionName, args }): Promise<unknown>;
bankr.chain.multicall({ chain, contracts: [...], allowFailure? }): Promise<unknown[]>;
bankr.chain.getBalance({ chain, address }): Promise<bigint>;
bankr.chain.getLogs({ chain, address?, topics?, fromBlock, toBlock }): Promise<Log[]>;
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<TxButton>;

// Curated agent invocation. Permission: invoke:agent.
bankr.askAgent(prompt: string): Promise<string>;

// HTTP fetch from the server-side runtime. Permission: fetch:http.
http.fetch(url: string, init?: RequestInit): Promise<unknown>;
// 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<string>;
secrets.status(): Promise<Array<{ key; required; set; allowedHosts }>>;

// Persistent key-value store, scoped to this app.
appKV.get(key: string): Promise<unknown | null>;
appKV.set(key: string, value: unknown): Promise<void>;
appKV.delete(key: string): Promise<boolean>;
appKV.list(prefix?: string): Promise<Array<{ key; value }>>;

// Args from the iframe (the second arg to bankr.scripts.run).
const args: Record<string, unknown>;

// 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:

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.

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.

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

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 when the value is small JSON. Each key becomes a {key}.json file that’s browsable and exportable like any other file. Larger values or anything that needs atomic uniqueness / prefix-list queries should use the record store — write keys with a record: prefix to opt into that:

// File-backed: lands at /apps/{slug}/data/snapshot.json
await appKV.set('snapshot', { ... });

// Queryable record store, scoped to caller wallet, atomic uniqueness on (app, wallet, key):
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 — how to build and refine.
• 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 → Security; applies to every surface) and per-API-key (configured at bankr.bot/api-keys; applies to one key). Both run independently — a transaction must satisfy both to broadcast.

Pick a layer

For the full reference of API-key flags and error responses, see Agent API → Access Control.

Where each control lives

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 email (support@bankr.bot), the Discord support channel where you open the ticket, 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, 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 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 → 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.

Controls

USD limits accept 1 to 1,000,000. Setting 0 is rejected — disable the limit instead. Cooldown accepts 0 to 168 hours.

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.

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
(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.

Developer API

For agents and integrations using the Bankr API. Pair these with the wallet-level controls in Bankr Terminal — both layers are enforced.

For the full reference of every flag and error response, see Agent API → Access Control.

Use a dedicated agent wallet

For production agents, use a separate Bankr account with its own API key and wallet:

• Blast radius isolation — a compromised key only affects the agent wallet
• Independent controls — read-only mode, IP allowlist, rate limits scoped to the agent
• Easy revocation — rotate the agent key without touching your main account

Setup: create a separate account at bankr.bot, generate a key at bankr.bot/api-keys, configure access controls, fund it with only what the agent needs.

Recommended configurations

Read-only mode

Strips all write tools (swaps, transfers, NFT trades, staking, orders, deployments, leveraged positions, Polymarket bets, fee claims) from agent sessions and returns 403 on /wallet/sign, /wallet/submit, /wallet/transfer. Use as the default for monitoring bots and public-facing surfaces. See Access Control → Read-Only Mode.

IP allowlist

Restricts which IPs can use the key. Validation runs in auth middleware before any endpoint logic. Supports IPs and CIDR ranges; minimum prefix lengths are /8 (IPv4) and /16 (IPv6). See Access Control → IP Allowlist.

Recipient allowlist

Restricts which addresses the key can send funds to. EVM and Solana lists are independent. Most useful for autonomous agents where recipients are LLM-resolved.

This is independent from the wallet-level Permitted Recipients. When both are configured, both must pass:

• API-key allowlist = where this key is allowed to send
• Wallet allowlist = where this wallet is allowed to send, regardless of key

See Access Control → Wallet Allowlist.

Layer wallet-level controls on top

Even with a hardened API key, the Bankr Terminal controls still apply. We recommend setting a daily USD limit and a per-transaction limit appropriate for the agent’s purpose — they cap total damage if the key is misconfigured or compromised.

Incident response

If you suspect a key is compromised:

1. Pause the wallet at bankr.bot → Security. Halts every outbound transaction immediately, including in-flight broadcasts. Revoking the key alone does not stop transactions already past auth.
2. Revoke the key at bankr.bot/api-keys.
3. Rotate — generate a new key with the same access profile and update deployments.
4. Audit — review recent transactions and agent job history before unpausing.

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

2. Add skills to your Bankr agent

You’re running a Bankr agent (the one at 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

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

Where to next

• New to Bankr and using another agent? Start with Install the Bankr skill.
• Already using your Bankr agent and want to extend it? Start with Install a skill from GitHub.
• Building something to share? See Contribute a skill for the public catalog, or Create a skill 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 :::

That’s it. Your agent now has access to all Bankr features.

This works in any framework that supports the SKILL.md 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 across Base, Ethereum, Polygon, Unichain, World Chain, Arbitrum, BNB Chain, and Solana
• 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 Create a separate Bankr account for your agent instead of using your main account. This isolates your personal funds from the agent’s activity. :::

Your API key is tied to a Bankr wallet. If you give your agent your personal API key, it has access to your personal wallet and all its funds. Instead:

1. Create a new Bankr account at bankr.bot specifically for the agent
2. Generate an API key at bankr.bot/api-keys
3. Fund it with small amounts — only what the agent needs for its tasks
4. Configure access controls — enable read-only mode if the agent only needs to query data, or add an IP allowlist to restrict where it can connect from

This way, if the key is compromised or the agent misbehaves, only the dedicated wallet is affected — not your personal holdings.

Recommended configurations

See Access Control for full details on read-only mode, IP allowlisting, and rate limits.

Requirements

• An agent that supports the SKILL.md format (Claude Code, OpenClaw, Cursor, etc.)

Uninstalling

To remove the skill:

uninstall the bankr skill

Updating

Skills update automatically. To force an update:

update the bankr skill

Troubleshooting

“Skill not found”

Ensure you’re using the correct URL:

https://github.com/BankrBot/skills

“Unable to execute trade”

Check that:

• You have sufficient balance for the trade
• You have gas for the transaction (or gas sponsorship applies)
• The token/pair exists on the specified chain

Next Steps

• Other available skills — Other Bankr-published skills you can install alongside the Bankr skill
• Contribute a skill — Build and share your own skills in the public catalog
• Add skills to your Bankr agent — The other direction: extending a Bankr agent with new skills

Other Available Skills

The public Bankr skills catalog at github.com/BankrBot/skills contains additional skills you can install alongside the Bankr skill.

Repository Structure

Skills are organized by provider:

skills/
├── bankr/
│   └── bankr/
│       └── SKILL.md
├── 8004.org/
│   └── erc-8004/
│       └── SKILL.md
├── botchan/
│   └── botchan/
│       └── SKILL.md
└── ...

Each skill contains:

• SKILL.md — Skill definition (required)
• references/ — Documentation files
• scripts/ — Helper utilities

Bankr

Provider: bankr

AI-powered crypto trading via natural language. The main Bankr skill for:

• Portfolio management
• Token trading
• DeFi operations
• Token launching

:::tip Install in your agent

install the bankr skill from https://github.com/BankrBot/skills :::

ERC-8004

Provider: 8004.org

Agent registration on Ethereum using trustless agent NFTs.

install the erc-8004 skill from https://github.com/BankrBot/skills

Botchan

Provider: botchan

CLI for onchain agent messaging on Base with:

• Feed posting
• Direct messaging capabilities

install the botchan skill from https://github.com/BankrBot/skills

QRCoin

Provider: qrcoin

URL bidding platform on Base blockchain.

install the qrcoin skill from https://github.com/BankrBot/skills

Yoink

Provider: yoink

Onchain capture-the-flag game.

install the yoink skill from https://github.com/BankrBot/skills

Coming Soon

Additional providers are being developed:

• Base — Base chain utilities
• Neynar — Farcaster integration
• Zapper — Portfolio tracking

Installing Multiple Skills

You can install multiple skills:

install the bankr skill from https://github.com/BankrBot/skills

install the botchan skill from https://github.com/BankrBot/skills

Listing Installed Skills

Check what skills are installed:

list my installed skills

Skill Discovery

Browse all available skills:

show available skills from https://github.com/BankrBot/skills

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.

Repository

Skills are contributed via pull request to:

https://github.com/BankrBot/skills

Skill Structure

Each skill requires this structure:

your-provider/
└── your-skill/
    ├── SKILL.md          # Required: Skill definition
    ├── references/       # Optional: Documentation
    └── scripts/          # Optional: Helper utilities

Creating a Skill

1. Fork the Repository

git clone https://github.com/BankrBot/skills.git
cd skills

2. Create Provider Directory

If you’re a new provider:

mkdir -p your-provider/your-skill

3. Write SKILL.md

Create your-provider/your-skill/SKILL.md:

# Your Skill Name

Brief description of what your skill does.

## Capabilities

- Capability 1
- Capability 2
- Capability 3

## Usage Examples

“example command 1” “example command 2”

## Requirements

- Any prerequisites
- API keys needed
- etc.

For the full frontmatter spec, see the SKILL.md format reference.

4. Add References (Optional)

Documentation in references/:

references/
├── api-docs.md
├── getting-started.md
└── advanced-usage.md

5. Add Scripts (Optional)

Helper utilities in scripts/:

scripts/
├── setup.sh
└── helpers.ts

Best Practices

Clear Documentation

• Write clear, specific descriptions
• Include usage examples
• Document all prerequisites

Testing

• Test your skill thoroughly before submitting
• Include test cases in your PR description

Commit Messages

Use descriptive commit messages:

git commit -m "Add weather-forecast skill for real-time weather data"

Submitting a Pull Request

1. Create a Branch

git checkout -b add-your-skill

2. Commit Changes

git add .
git commit -m "Add your-skill for description"

3. Push and Create PR

git push origin add-your-skill

Then create a pull request on GitHub with:

• Clear description of the skill
• Example use cases
• Any dependencies or requirements

Review Process

After submitting:

1. Maintainers review your PR
2. Feedback may be requested
3. Once approved, skill is merged
4. Skill becomes available to all users

Guidelines

• Maintain quality — Clear, well-documented definitions
• Be helpful — Skills should solve real problems
• Stay safe — Don’t include malicious functionality
• Respect users — Be transparent about capabilities and limitations

Getting Help

• Open an issue for questions
• Email support@bankr.bot
• Join the community Discord
• Check existing skills for examples

Install a Skill from GitHub

Your Bankr agent can install skills directly from any public GitHub repository. This is the fastest way to add a new capability — point your agent at a repo, 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 bankr skill from https://github.com/BankrBot/skills/tree/main/bankr/bankr
install the botchan skill from https://github.com/BankrBot/skills/tree/main/botchan/botchan
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.

If a skill with the same name already exists, the new version replaces it — that’s how updates work.

What URLs work

The URL should point to a folder in a public GitHub repo that contains a SKILL.md at its root. Both the tree/<branch>/<path> form and a plain https://github.com/owner/repo (when the skill is at the repo root) are accepted.

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.

For the full file format, see the SKILL.md format reference.

After installation

Once installed, your agent will use the skill automatically when a request matches what the skill describes. You can also list, review, or remove installed skills from the Skills tab in your agent’s terminal — see Create a skill manually for the same UI from the create-side.

Limits

• Each skill file is capped at 100 KB. If a SKILL.md or any reference file exceeds this, the install will fail with a clear message — split or trim the content and try again.
• Each user has a maximum number of installed skills. If you hit it, remove an unused skill from the Skills tab and retry.

Troubleshooting

“Couldn’t find SKILL.md at that URL”

Confirm the URL points to a folder that has a SKILL.md file at its root. GitHub URLs that point to a single file (or a blob/ URL) won’t work — you need the folder URL.

“Repository is private”

The skill repo must be publicly accessible. Private repos aren’t supported via the GitHub install flow — copy the contents into your agent manually instead. See Create a skill manually.

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-name> skill to ...

If that works, consider rewriting the skill’s description field so it triggers automatically next time.

Next steps

• Create a skill manually — write a one-off skill directly in the agent UI without publishing to GitHub.
• SKILL.md format reference — 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 tab in your agent’s terminal lets you write one directly, with no repo and no upload step.

Open the Skills tab

1. Go to your agent’s terminal at bankr.bot/terminal.
2. Open the settings panel.
3. Select the Skills tab.

You’ll see a list of every skill currently installed in your agent — both ones you’ve installed from GitHub and ones you’ve written here.

Add a new skill

Click + Add at the top of the Skills tab. 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:

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

Each row in the Skills list has Edit and Delete buttons. Editing reopens the same editor with the skill’s current contents. Deleting prompts for confirmation, then removes the skill and all its reference files.

When to write a skill manually vs. install from GitHub

Next steps

• SKILL.md format reference — exact field-by-field spec.
• Install a skill from GitHub — 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, writing one manually in the Skills tab, or contributing to the public catalog.

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

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

Optional

Metadata block

The metadata.clawdbot block carries cross-framework hints — fields that some hosts use for richer display or pre-flight checks.

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 Skills tab of the Bankr terminal, open your skill in the editor and click + Add resource. 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.

Validation

When a skill is installed, the file is validated against this format. The most common errors are:

• Missing frontmatter. The file must start with --- on the first line.
• Missing name or description. Both are required.
• File too large. Each file (SKILL.md or any single reference) is capped at 100 KB.

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
• Create a skill manually
• Contribute a skill 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

Launching via Natural Language

Simply tell Bankr what you want to deploy. Tokens deploy to Base by default:

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

# 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

# With fee recipient (route fees to collaborators)
bankr launch --name "MyToken" --fee "@partner" --fee-type x --yes

The CLI wizard prompts for:

• Token name (required)
• Image URL (optional)
• Associated tweet for social proof (optional)
• Project website (optional)
• Fee recipient: X/Farcaster handle, ENS, or wallet address (optional)

All bankr launch commands deploy to Base and display a summary before confirmation. Use --yes to skip confirmation in automated scripts.

Install the CLI:

npm install -g @bankr/cli

See the CLI documentation for full options and examples.

Launching with OpenClaw

For AI agents using OpenClaw, 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

Deployment Limits

Gas is sponsored within these limits.

:::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. Repeatedly hitting the daily cap or bot-like deploy patterns will flag your account. Legitimate high-volume use cases (e.g. programmatic deploy products) may be accommodated — open a support ticket explaining your use case before scaling up. :::

Fee Structure

Tokens launch with a 1.2% swap fee on the Uniswap V4 pool. Trading fees are split:

Fees accumulate in your token and WETH. Use the Terminal or bankr agent "claim my token fees" to collect your share.

Token Supply

Fixed supply of 100 billion tokens (not mintable after deployment).

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 Base. Returns the token address and Uniswap V4 pool metadata.

• Interactive reference: Deploy a token →
• Endpoint: POST /token-launches/deploy
• Auth: X-Partner-Key (org-level) or X-API-Key / Authorization: Bearer (wallet-level)

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 token or beneficiary. Unauthenticated.

• Interactive reference: Check fees →
• Guide: Reading Creator 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

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 vs Clanker, builds the calldata, signs via Privy, and broadcasts.

• Guide: Claiming Fees →
• Interactive reference: Claim token-launch fees →
• Endpoint: POST /token-launches/:tokenAddress/fees/claim
• Auth: X-API-Key / Authorization: Bearer (user API key)

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

• Interactive reference: List launches →
• Endpoint: GET /token-launches

curl https://api.bankr.bot/token-launches

Next Steps

• Fee Redirecting — Route fees to collaborators or treasury
• Claiming Fees — How to collect your earnings
• Token Launching API (interactive) — Try lifecycle endpoints from your browser
• Partner API (interactive) — 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

When your token is traded, a 1.2% swap fee is collected. Your creator share (57% of fees) goes to the fee beneficiary address. By default, this is your bankr wallet. With fee redirecting, you can route your 57% share to a different address.

The remaining fees are automatically distributed:

• Bankr: 36.1%
• Bankr Ecosystem: 1.9%
• Protocol (Doppler): 5%

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 57% creator share.

After Deployment

The current fee beneficiary can transfer their rights to a new address.

From the Token Page

Navigate to the token detail page at /launches/<tokenAddress> and click Transfer Fee Recipient. 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 57% share allocation moves to the new address. Only the current beneficiary can transfer rights. :::

Fee Beneficiary vs Vault Recipient

These are separate addresses that can be configured independently:

Example with both:

"deploy a token with fees to 0xABC... and vault to 0xDEF..."

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 for details.

Reading Creator Fees

Query accrued, claimable, and historical creator fees for any Bankr-launched token — programmatically, on-chain, or from the CLI.

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.bot/launches/ web UI and bankr fees CLI both call these 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 2 minutes.

Request

curl "https://api.bankr.bot/public/doppler/token-fees/0xTokenAddress?days=30"

days is optional (default 30, max 90) and controls the dailyEarnings window.

Response

{
  "address": "0x87be4da49869fd055d5a60cac2a6dc61fdd3052d",
  "chain": "base",
  "days": 30,
  "tokens": [
    {
      "tokenAddress": "0x1234...5678",
      "name": "My Token",
      "symbol": "MTK",
      "poolId": "0xabcd...1234",
      "initializer": "0xFeesManager...",
      "share": "57.00%",
      "token0Label": "WETH",
      "token1Label": "MTK",
      "claimable": { "token0": "0.0042", "token1": "125000.0000" },
      "claimed":   { "token0": "0.1234", "token1": "500000.0000", "count": 3 },
      "source": "doppler"
    }
  ],
  "dailyEarnings": [
    { "date": "2026-04-14", "weth": "0.0012" },
    { "date": "2026-04-15", "weth": "0.0031" }
  ],
  "lifetimeEarnedWeth": "1.2345",
  "lifetimeDays": 42,
  "lifetimeBestDay": { "date": "2026-03-22", "weth": "0.0891" },
  "totals": { "claimableWeth": "0.0042", "claimedWeth": "0.1234", "claimCount": 3 }
}

The initializer is the Fees Manager contract for this token’s pool — the same address you’d call collectFees(poolId) on. Both initializer and poolId are stable once a pool is deployed, so cache them.

Claimable fees for a specific beneficiary

Cheap single-address lookup — one on-chain read. Use this to gate a “Claim” button in your UI.

Request

curl "https://api.bankr.bot/public/doppler/claimable-fees/0xTokenAddress?beneficiary=0xYourAddress"

Response (eligible)

{
  "eligible": true,
  "tokenAddress": "0x1234...5678",
  "share": "57.00%",
  "claimableFees": {
    "token0": "0.0042",
    "token1": "125000.0000",
    "token0Label": "WETH",
    "token1Label": "MTK"
  }
}

Response (not eligible)

{ "eligible": false, "tokenAddress": "0x1234...5678" }

All tokens for a creator

Returns every Doppler and Clanker token where the address is a creator beneficiary, with aggregated totals and unified daily timeline.

Request

curl "https://api.bankr.bot/public/doppler/creator-fees/0xYourAddress?days=30"

Response shape matches 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)

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. updateBeneficiary is used by transfer flows.

viem example

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. Both are returned in every deploy response and every call to GET /public/doppler/token-fees/:tokenAddress.

CLI

The Bankr CLI wraps the same REST endpoints with a terminal dashboard:

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

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

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

The signing wallet must hold ETH on Base to pay gas. See Claiming Fees for the gas-sponsorship rules across all claim paths.

Caching & rate limits

• Server-side cache: 2 minutes per (address, days) or (tokenAddress, days) pair
• No rate limits on public read endpoints currently, but be polite — 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 for REST, on-chain, and CLI options.

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 57% of the 1.2% swap fee collected on trades. The remaining fees are automatically distributed to Bankr (36.1%), Bankr Ecosystem (1.9%), and Protocol (5%).

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 Token Page

Navigate to the token detail page at /launches/<tokenAddress> 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 — you can claim with a $0 ETH balance. 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 small amount of ETH on Base.

Gas

API example — single-call claim (recommended)

POST /token-launches/:tokenAddress/fees/claim builds, signs, and broadcasts in one call. Auto-detects Doppler vs Clanker.

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 <token>. 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 remain functional through their deprecation window but now emit Deprecation and Sunset response headers.

Gas sponsorship covers up to 10 transactions per day per wallet across all sponsored paths. This is usually more than enough for fee claims, but high-volume agents claiming many tokens daily should account for this ceiling.

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:

Both accumulate in the Uniswap V4 liquidity pool and are claimed together.

Claim Frequency

You can claim at any time. There’s no minimum threshold, but consider gas costs when claiming small amounts.

Recommended approach:

• Check fees periodically: "show my unclaimed fees"
• Claim when accumulated amount justifies gas cost
• Gas is low on Base, so you can claim frequently

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:

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:

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:

# 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. See the CLI documentation for full details.

For Partners

If you’re a Bankr partner deploying tokens via the Deploy API, 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:

# 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

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.

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, 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: navigate to the token page at bankr.bot/launches/<tokenAddress> and use the “Transfer Beneficiary” action
• 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

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

{
  "to": "0xFeesManagerAddress...",
  "data": "0xabcdef...",
  "chainId": 8453,
  "description": "Transfer fee beneficiary for MyToken"
}

Sign and broadcast with the current beneficiary’s private key. The signing wallet must hold a small amount of ETH on Base for gas.

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:

function updateBeneficiary(bytes32 poolId, address newBeneficiary);

Call it on the pool’s Fees Manager (the initializer address returned by GET /public/doppler/token-fees/:tokenAddress). See Reading Creator Fees → On-chain reads for resolving initializer and poolId.

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:

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

Gas

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 above).

List recent token launches

Returns the 50 most recent token launches deployed via Bankr (Doppler v4), sorted by createdAt descending. Unauthenticated.

Programmatic access to the data behind bankr.bot/launches.

Endpoint

GET https://api.bankr.bot/token-launches

Example

curl https://api.bankr.bot/token-launches

Response

{
  "launches": [
    {
      "activityId": "65b…",
      "status": "deployed",
      "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

npm install -g @bankr/cli

:::

After installing, the bankr command is available everywhere:

bankr --version

Alternative: bun

bun install -g @bankr/cli

Run without installing

npx @bankr/cli what is the price of ETH?

Updating

Update the CLI to the latest version without remembering your package manager:

bankr update

To check if an update is available without installing:

bankr update --check

The CLI auto-detects whether you installed with npm, bun, pnpm, or yarn and runs the appropriate global install command.

Setup

Login

Credentials are stored in ~/.bankr/config.json. You can also set keys via environment variables (BANKR_API_KEY, BANKR_LLM_KEY).

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.

# 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 --accept-terms --key-name "My Key" --agent-api --read-write --llm

New key defaults (CLI):

When --code is omitted and an email address is provided, the CLI sends the verification code and exits — no credentials are saved. Pass --code with the received code to complete login.

Any option not provided will be prompted interactively, so you can mix headless and interactive:

# Send OTP headlessly, then verify with interactive prompts for key options
bankr login email user@example.com --code 123456

API key login

If you already have a bk_... API key (from the Bankr Terminal or another source):

# Log in directly with an API key
bankr login --api-key bk_YOUR_KEY

# Log in with a separate LLM gateway key
bankr login --api-key bk_YOUR_KEY --llm-key YOUR_LLM_KEY

# Print the Bankr Terminal URL (for generating a key)
bankr login --url

SIWE login (headless agents)

Sign in with an Ethereum wallet using Sign-In with Ethereum. Designed for headless agents and automated environments where no browser or email is available.

# Basic SIWE login (read-write by default)
bankr login siwe --private-key 0xYOUR_PRIVATE_KEY

# Custom key name, read-only
bankr login siwe --private-key 0x... --key-name "My Agent" --read-write

The CLI fetches a nonce from the Bankr API, constructs and signs an EIP-4361 message with the provided private key, then verifies with the API to create a wallet and generate an API key.

Interactive menu

bankr login

Presents a menu to choose your login method: sign in with email, open the Bankr Terminal to generate an API key, or paste an existing key.

Verify setup

bankr whoami

Displays your API key (masked), API URL, connection status, wallet addresses, linked wallets, social accounts, Bankr Club status, referral code, and score.

Non-interactive mode

For headless environments — CI/CD pipelines, Docker containers, cron jobs, or any context where prompts would hang — use the --not-interactive (alias --ni) global flag.

# Either form works, before or after the subcommand
bankr --ni launch --name MyToken
bankr launch --ni --name MyToken

# Or set the env var
export BANKR_NOT_INTERACTIVE=1
bankr launch --name MyToken

The flag does three things:

1. Skips confirmation prompts — equivalent to passing --yes to commands that support it.
2. Suppresses optional prompts — fields the CLI would normally ask about (token symbol, image URL, etc.) default to empty.
3. Fails fast on required input — exits with a clear error instead of hanging on a prompt.

Headless flag combos

Some commands need extra flags to be fully headless. Without them, --ni exits with an error:

Examples

# Cron — claim creator fees nightly
BANKR_PRIVATE_KEY=0x... bankr --ni fees claim-wallet --all

# CI — programmatic token launch (simulate without broadcasting)
bankr --ni launch --name MyToken --symbol MTK --simulate

# Docker entrypoint — auto top-up LLM credits
bankr --ni llm credits add 50

# Pipeline — agent in non-interactive mode (reads from stdin)
echo "summarize today's trades" | bankr --ni agent prompt

# Two-step email login in CI
bankr --ni login email user@example.com                            # step 1: send OTP
bankr --ni login email user@example.com --code 123456 --accept-terms   # step 2: complete

Read-only commands (whoami, wallet portfolio, tokens search, agent status, etc.) don’t prompt at all, so --ni is harmless but redundant on them.

Commands

bankr agent [text...]

Send a prompt to the Bankr AI agent. Submits the prompt, polls for completion, and displays the result.

bankr agent what is the price of ETH?

Thread options

Continue a multi-turn conversation using threads:

# Continue the most recent thread
bankr agent --continue "and what about SOL?"
bankr agent -c "compare them"

# Continue a specific thread by ID
bankr agent --thread thr_ABC123 "tell me more"

The response includes a threadId that is automatically saved. Use --continue to pick up where you left off, or --thread to resume any previous thread.

Interactive and piped input

If no text is provided, the CLI opens an interactive input (which avoids shell expansion issues with $ signs):

bankr agent
# Enter your prompt: buy $50 of ETH on base

You can also pipe input:

echo "buy $50 of ETH on base" | bankr agent

bankr wallet

Wallet operations. Running bankr wallet with no subcommand shows your wallet info (same as bankr whoami).

bankr wallet portfolio

Show wallet portfolio across all supported chains. See Portfolio Endpoint.

bankr wallet portfolio                    # Token balances
bankr wallet portfolio --pnl              # With profit/loss
bankr wallet portfolio --nfts             # With NFT holdings
bankr wallet portfolio --all              # Everything
bankr wallet portfolio --chain base       # Single chain
bankr wallet portfolio --json             # Raw JSON output
bankr wallet portfolio --low-value        # Include dust tokens

bankr wallet transfer

Transfer tokens to an EVM address or ENS name. Supports token symbol resolution.

bankr wallet transfer --to 0x... --amount 100 --token USDC
bankr wallet transfer --to vitalik.eth --amount 0.01 --native
bankr wallet transfer --to name.base.eth --amount 10 --token USDC
bankr wallet transfer --to 0x... --amount 10 --token USDC --chain polygon

bankr wallet sign

Sign messages, typed data, or transactions without broadcasting.

bankr wallet sign --type personal_sign --message "Hello, Bankr!"
bankr wallet sign --type eth_signTypedData_v4 --typed-data '{"domain":{...},...}'
bankr wallet sign --type eth_signTransaction --transaction '{"to":"0x...","chainId":8453}'

bankr wallet submit

Submit transactions to the blockchain.

bankr wallet submit tx --to 0x... --chain-id 8453 --value 1000000000000000000
bankr wallet submit json '{"to":"0x...","chainId":8453,"value":"1000000000000000000"}'

:::note Sign, submit, and transfer are write operations. Read-only API keys will receive a 403 error. See Access Control. :::

bankr agent

AI agent commands. Running bankr agent "buy ETH" sends a prompt. The default bankr "buy ETH" shortcut also works.

bankr agent status <jobId>

Check the status of a previously submitted job.

bankr agent cancel <jobId>

Cancel a pending or processing job.

bankr agent skills

Show all available agent skills with examples.

bankr agent profile

Manage your agent profile page (create, update, delete, add-update).

bankr whoami

Show current authentication and account info:

bankr whoami

bankr tokens

Token search and info (public, no auth required).

bankr tokens search USDC
bankr tokens search ETH --chain 1
bankr tokens info 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

bankr skills

List all available Bankr AI agent skills with examples:

bankr skills

bankr launch

Launch a token on Base through an interactive wizard. The wizard guides you through providing token details, including name, image, social links, and fee recipients.

# Interactive wizard (prompts for all details)
bankr launch

# Headless with all options specified
bankr launch --name "MyToken" --symbol "MTK" --image "https://example.com/logo.png" -y

# With fee recipient
bankr launch --name "MyToken" --fee "@myhandle" --fee-type x -y

Options

Fee Recipients

Direct a portion of trading fees to collaborators, partners, or your treasury:

# X (Twitter) handle
bankr launch --name "MyToken" --fee "@partner" --fee-type x

# Farcaster handle
bankr launch --name "MyToken" --fee "@partner" --fee-type farcaster

# ENS name
bankr launch --name "MyToken" --fee "partner.eth" --fee-type ens

# Wallet address
bankr launch --name "MyToken" --fee "0x..." --fee-type wallet

The wizard displays a summary and asks for confirmation before submitting the launch. Use --yes to skip confirmation in scripts and automated deployments.

:::note This is a write operation. Read-only API keys will receive a 403 error. See Access Control. Token launches are subject to deployment limits. :::

bankr fees [address]

View a full fee earnings dashboard for your deployed tokens. Displays claimable and claimed WETH, a daily earnings chart, per-token breakdown, and projected monthly/yearly earnings based on your daily average.

# Dashboard for your authenticated wallet
bankr fees

# Dashboard for a specific wallet address
bankr fees 0x1234...

# Look up fees by token contract address
bankr fees --token 0xTokenAddress

# Custom lookback period (1-90 days, default 30)
bankr fees --days 7

# Raw JSON output (for scripting)
bankr fees --json

The dashboard includes:

• Claimable / Claimed WETH summary cards
• Daily earnings chart with sparkline visualization
• Statistics: total earned, daily average, best day, active days, current streak
• Projections: estimated monthly and yearly earnings based on your daily average
• Per-token breakdown: claimable and claimed amounts for each token

bankr fees claim <tokenAddress>

Claim accumulated fees for a specific token:

# Claim with confirmation prompt
bankr fees claim 0xTokenAddress

# Skip confirmation (for scripts)
bankr fees claim 0xTokenAddress --yes

:::note This is a write operation. Read-only API keys will receive a 403 error. See Access Control. :::

bankr fees claim-wallet [address]

Claim earned Doppler fees using your own private key — no Bankr account needed. Scans all launches where your wallet is a fee beneficiary, shows claimable amounts, and submits claim transactions directly from the CLI.

# Derive address from BANKR_PRIVATE_KEY in .env
bankr fees claim-wallet

# Specify address explicitly (key prompted or read from .env)
bankr fees claim-wallet 0xYourAddress

# Claim all tokens without interactive selection
bankr fees claim-wallet --all

# Skip all confirmation prompts (for scripts)
bankr fees claim-wallet --all --yes

# Use a custom RPC endpoint
bankr fees claim-wallet --rpc https://your-rpc.com

Environment variables:

Create a .env file in your working directory:

BANKR_PRIVATE_KEY=0xYourPrivateKey
BANKR_API_KEY=your-api-key

The CLI automatically reads .env from the current directory. When BANKR_PRIVATE_KEY is set and no address argument is provided, the address is derived from the key automatically.

bankr llm models

List all models available through the Bankr LLM Gateway:

bankr llm models

If you’re authenticated, the CLI fetches the live model list from the gateway. Otherwise it shows the built-in catalog.

bankr llm credits

Check your LLM gateway credit balance:

bankr llm credits

Shows your current USD credit balance for LLM gateway usage. Returns an error if your balance is exhausted or if authentication fails.

bankr llm credits add <amount>

Top up your LLM gateway credits from your wallet. Pay on any supported EVM chain — Base, Polygon, Ethereum, Arbitrum, or BNB Chain — and the CLI picks the chain holding the highest USD balance of your chosen token.

bankr llm credits add 25                   # Defaults to Base USDC
bankr llm credits add 25 --token USDC      # USDC on the chain with the largest balance
bankr llm credits add 25 --token USDT      # USDT on the chain with the largest balance
bankr llm credits add 50 --token ETH       # Native ETH (Base / Ethereum / Arbitrum)
bankr llm credits add 25 --token 0x...     # By contract address
bankr llm credits add 25 -y                # Skip confirmation prompt

USDC and USDT are sent directly when they’re an accepted stablecoin on the resolved chain. Any other token is auto-swapped to the chain’s preferred stablecoin (USDC on most chains, USDT on BNB) with ≤5% slippage protection.

:::note This is a write operation. Read-only API keys will receive a 403 error. See Access Control. :::

bankr llm credits auto

View or configure automatic LLM credit top-ups:

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

When --amount, --threshold, or --tokens are provided without --enable/--disable, auto top-up is implicitly enabled. Token symbols/addresses are resolved across every supported chain (Base, Polygon, Ethereum, Arbitrum, BNB Chain) — the chain holding the highest USD balance for each token is saved alongside it. The worker tries the saved tokens in priority order and routes each on its own chain.

bankr llm setup <target>

Generate configuration to use the Bankr LLM Gateway with your coding agent. Supported targets:

bankr llm setup openclaw             # OpenClaw JSON config
bankr llm setup openclaw --install   # Write to ~/.openclaw/openclaw.json
bankr llm setup opencode             # OpenCode JSON config
bankr llm setup opencode --install   # Write to ~/.config/opencode/opencode.json
bankr llm setup cursor               # Cursor IDE setup instructions
bankr llm setup claude               # Claude Code env var config

The --install flag (available for OpenClaw and OpenCode) merges the Bankr provider into your existing config file without overwriting other providers.

bankr llm claude [args...]

Launch Claude Code with all API requests routed through the Bankr LLM Gateway:

bankr llm claude
bankr llm claude --model claude-sonnet-4.5

This spawns claude with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN set automatically from your Bankr config. If a separate llmKey is configured, it uses that; otherwise it falls back to your API key. All arguments are passed through to Claude Code.

bankr llm opencode [args...]

Launch OpenCode with all API requests routed through the Bankr LLM Gateway:

bankr llm opencode
bankr llm opencode --model claude-sonnet-4.5

This spawns opencode with the Bankr provider automatically configured. If the OpenCode config doesn’t include the Bankr provider, it runs bankr llm setup opencode --install first. All arguments are passed through to OpenCode.

bankr club

Manage your Bankr Club membership from the CLI.

bankr club                              # Show membership status (default)
bankr club status                       # Same as above
bankr club signup                       # Subscribe (monthly, USDC default)
bankr club signup --yearly              # Subscribe yearly
bankr club signup --token BNKR          # Pay with BNKR (direct transfer)
bankr club signup --token ETH           # Pay with ETH (swapped to USDC at checkout)
bankr club signup --token 0x4200...     # Pay with any Base ERC-20 by address
bankr club signup --yes                 # Skip confirmation prompt
bankr club cancel                       # Cancel subscription

Pricing is $20/month or $198/year (saves ~$42). The actual on-chain amount depends on the chosen token’s price at quote time. Non-direct tokens (anything other than USDC or BNKR) are swapped to USDC at checkout with ≤5% slippage protection.

bankr x402

x402 Cloud commands for deploying, managing, and calling paid API endpoints. See the full x402 CLI Reference for all commands.

Key commands:

bankr x402 init                    # Scaffold project
bankr x402 add <name>              # Add a service
bankr x402 deploy [name]           # Deploy services
bankr x402 list                    # List deployed endpoints
bankr x402 search <query>          # Search the marketplace
bankr x402 schema <url>            # View endpoint schema
bankr x402 call <url>              # Call with automatic payment
bankr x402 call <url> -i           # Interactive mode — prompt for inputs
bankr x402 revenue [name]          # View earnings
bankr x402 env set KEY=VALUE       # Set encrypted env var

bankr config get [key]

Read configuration values. Without a key, shows all config:

bankr config get          # show all
bankr config get apiKey   # show API key
bankr config get apiUrl   # show API URL
bankr config get llmKey   # show LLM gateway key
bankr config get llmUrl   # show LLM gateway URL

bankr config set <key> <value>

Set a configuration value. Supported keys: apiKey, apiUrl, llmKey, llmUrl.

bankr config set llmKey YOUR_LLM_KEY

bankr logout

Clear stored credentials:

bankr logout

bankr sounds

Manage CESP (CLI Event Sound Packs) sound effects. Without a subcommand, displays the current sound configuration status.

bankr sounds                        # Show current config
bankr sounds enable                 # Enable sounds
bankr sounds disable                # Disable sounds
bankr sounds install <pack>         # Install a pack from the CESP registry
bankr sounds search [query]         # Search available packs
bankr sounds list                   # List installed packs
bankr sounds use <pack>             # Set the active sound pack
bankr sounds volume [level]         # Get or set volume (0.0–1.0)
bankr sounds mute                   # Mute all sounds
bankr sounds unmute                 # Unmute sounds
bankr sounds test [category]        # Play a test sound

Sound packs are installed to ~/.bankr/sounds/ and provide audio feedback for CLI events like task completion or errors.

bankr update

Update the CLI to the latest published version:

bankr update              # Check and install latest version
bankr update --check      # Check only, don't install

Default command

Any unrecognized arguments are treated as a prompt:

bankr what is the price of BNKR?
# equivalent to: bankr agent what is the price of BNKR?

Thread options (--thread, --continue) are only available on the agent subcommand.

Configuration

The CLI uses this config precedence (highest to lowest):

1. Environment variable — BANKR_API_KEY, BANKR_LLM_KEY, BANKR_API_URL, BANKR_LLM_URL
2. Config file (~/.bankr/config.json)
3. Defaults (API URL: https://api.bankr.bot, LLM URL: https://llm.bankr.bot)

Separate LLM key

If your LLM gateway key differs from your Bankr API key, you can configure them separately. The LLM key is used for all LLM gateway calls (bankr llm models, bankr llm credits, bankr llm setup, bankr llm claude). When not set, the API key is used for both.

# Set during login (interactive prompt or flag)
bankr login --llm-key YOUR_LLM_KEY

# Or set via config
bankr config set llmKey YOUR_LLM_KEY

# Or via environment variable
export BANKR_LLM_KEY=your_llm_key_here

Access Controls

The CLI uses the same API key as the REST API, so all server-side access controls apply:

• Read-only key — bankr agent works, but the agent can only query data (prices, balances, analytics). It cannot execute swaps, transfers, or other write operations.
• IP allowlist — requests from IPs not on the allowlist are rejected with a 403 error.
• Rate limits — the same daily message limits apply (100/day standard, 1,000/day Bankr Club).

Credential storage — The API key is stored in ~/.bankr/config.json. Never commit this file to version control. Run bankr logout on shared machines and consider chmod 600 ~/.bankr/config.json to restrict file permissions.

See Access Control for full details.

Programmatic usage

The CLI also exports its API client for use in Node.js/TypeScript projects:

// Submit and poll
const { jobId, threadId } = await submitPrompt("what is the price of ETH?");
const result = await pollJob(jobId, {
  onStatus: (s) => console.log(s.status),
});
console.log(result.response);

// Continue the conversation using the threadId
const { jobId: jobId2 } = await submitPrompt("and what about BTC?", threadId);
const result2 = await pollJob(jobId2);
console.log(result2.response); // agent has context from the first question

// Get user info
const info = await getUserInfo();
console.log(info.address, info.score);

// Get wallet balances
const balances = await getBalances(["base", "solana"]);
for (const [chain, data] of Object.entries(balances.balances)) {
  console.log(`${chain}: $${data.total}`);
}

See the npm package for the full API surface.

x402 Cloud

Deploy paid API endpoints in minutes. Bankr handles hosting, payments, and discovery.

x402 Cloud lets you deploy serverless API endpoints that agents and developers pay for automatically using the x402 payment protocol. Write a simple handler function, set your price, deploy with one command — and start earning.

:::tip Dashboard Manage your endpoints at bankr.bot/x402 — view usage, revenue, logs, and configure settings. :::

Why x402 Cloud?

How It Works

Developer                          Agent / Client
    │                                    │
    │  bankr x402 deploy                 │  GET /weather?city=London
    │──────────────────►                 │─────────────────────────►
    │                                    │  ◄── 402 + PaymentRequirements
    │  Handler runs on                   │
    │  Bankr infrastructure              │  Signs payment, retries
    │                                    │─────────────────────────►
    │                                    │  ◄── 200 { temp: 72 }
    │                                    │
    │  Revenue appears                   │  Payment settled on-chain
    │  in dashboard                      │

1. You write a handler and deploy via CLI
2. An agent calls your endpoint — gets a 402 with pricing
3. The agent’s wallet signs a payment and retries
4. Bankr verifies the payment, runs your handler, settles on-chain
5. You see the request, logs, and revenue in your dashboard

Create Endpoints via Chat

You can create, deploy, and manage x402 endpoints entirely through the Bankr agent — no CLI or local setup needed. Describe what you want and Bankr writes the TypeScript handler, deploys it, and gives you the live URL.

create an x402 endpoint called "sentiment" that takes a stock ticker
and returns a sentiment score from recent news. charge $0.005 per request.

The agent handles the full lifecycle:

Endpoints created through chat are identical to CLI-deployed ones — same runtime, same URL format (https://x402.bankr.bot/<wallet>/<name>), same billing. You can manage chat-created endpoints with the CLI and vice versa.

Handler Context

Your handler receives a ctx object with optional capabilities you can enable at deploy time:

Each capability is opt-in — the agent declares what your handler needs when deploying and only those fields are populated at runtime.

Environment Variables

Endpoints can read secrets via process.env. Declare the variable names at deploy time (values are never passed through chat). Set the actual values through Terminal Settings or the CLI. The agent’s x402 env vars are stored in a separate encrypted scope from your regular agent env vars.

Pricing

No credit card required. Your first 1,000 requests each month are completely free. After that, a flat 5% platform fee applies. Payments are settled on-chain in USDC on Base. Your earnings go directly to your wallet address — no invoicing, no delayed payouts.

Quick Start(X402-cloud)

Get a paid API endpoint live in under 5 minutes.

Prerequisites

• Bankr CLI installed and authenticated (bankr login)

1. Initialize

bankr x402 init

This creates:

• x402/ directory for your service handlers
• bankr.x402.json config file

2. Add a Service

bankr x402 add weather

This scaffolds x402/weather/index.ts with a starter template.

3. Add Dependencies (optional)

If your handler needs npm packages, add a package.json to your service directory:

cd x402/weather
bun add zod @langchain/openai   # or any npm packages you need

When you answer “yes” to “Will this service use npm packages?” during bankr x402 add, a package.json is scaffolded automatically.

4. Write Your Handler

Edit x402/weather/index.ts. Your handler is a plain function that receives a Request and returns data:

export default async function handler(req: Request) {
  const url = new URL(req.url);
  const city = url.searchParams.get("city") ?? "New York";

  // Your business logic here — call external APIs, process data, run models
  const weather = await getWeather(city);

  return {
    city,
    temperature: weather.temp,
    conditions: weather.conditions,
    timestamp: new Date().toISOString(),
  };
}

async function getWeather(city: string) {
  // Use process.env for your API keys (set via bankr x402 env set)
  const apiKey = process.env.WEATHER_API_KEY;
  const res = await fetch(
    `https://api.weather.example/v1/current?city=${city}&key=${apiKey}`,
  );
  return res.json();
}

That’s it. No x402 imports, no payment middleware, no blockchain code. Bankr wraps the payment layer around your handler automatically.

You can return plain objects, strings, or any JSON-serializable value — Bankr auto-wraps them into a JSON response. You can also return a full Response object if you need to set custom status codes, headers, or return non-JSON content like HTML or images.

5. Set Environment Variables (optional)

If your handler uses API keys or secrets:

bankr x402 env set WEATHER_API_KEY=your-api-key-here

Environment variables are encrypted at rest and available as process.env in your handler. You can set them before or after deploying. See Security for details.

6. Define Your Schema

The schema is how agents and humans know how to use your service. It describes your inputs and outputs using JSON Schema — what fields to send, what types they are, and what comes back.

Why this matters:

• AI agents use the schema to call your endpoint correctly without any hardcoded integration
• The Bankr CLI reads it for interactive mode (bankr x402 call -i), prompting users for each field
• The marketplace displays it so people can understand your service at a glance

Add the schema field to your service in bankr.x402.json:

{
  "network": "base",
  "currency": "USDC",
  "services": {
    "weather": {
      "description": "Real-time weather data for any city",
      "price": "0.001",
      "methods": ["GET"],
      "schema": {
        "input": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name (e.g. 'London', 'New York')"
            },
            "units": {
              "type": "string",
              "description": "Temperature units",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["city"]
        },
        "output": {
          "type": "object",
          "properties": {
            "temperature": { "type": "number", "description": "Current temperature" },
            "conditions": { "type": "string", "description": "Weather conditions (e.g. 'sunny', 'cloudy')" },
            "timestamp": { "type": "string", "description": "ISO 8601 timestamp" }
          }
        }
      }
    }
  }
}

Tips for good schemas:

• Add description to every property — this is what agents and the interactive CLI show to users
• Mark fields as required so callers know what’s mandatory
• Use enum for fields with a fixed set of values
• For POST services, input properties map to JSON body fields. For GET services, they map to query parameters.

See Config File for the full schema reference including arrays, nested objects, and legacy formats.

7. Configure Pricing

Set the price field in bankr.x402.json (already shown above), or use the interactive configurator:

bankr x402 configure weather

Prices are in USD, paid in USDC. The minimum is 0.000001. Consider your per-request costs (API calls, inference, compute) and add a margin.

8. Deploy

bankr x402 deploy

Output:

✔ Deployed 1 service(s)

  Service:  weather
  URL:      https://x402.bankr.bot/0xYourWallet/weather
  Price:    $0.001 USDC/req
  Version:  1

Your endpoint is live. Agents can now discover and pay for it automatically.

9. Test It

Inspect the schema

Check what your endpoint expects before calling it:

bankr x402 schema https://x402.bankr.bot/0xYourWallet/weather

Call with the CLI

The easiest way to test is with bankr x402 call:

# Direct call with query params
bankr x402 call https://x402.bankr.bot/0xYourWallet/weather?city=London

# Interactive mode — the CLI reads the schema and prompts for each field
bankr x402 call https://x402.bankr.bot/0xYourWallet/weather -i

Without payment (returns 402)

curl -i https://x402.bankr.bot/0xYourWallet/weather?city=London

With payment (using x402-fetch)

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const wallet = createWalletClient({ account, chain: base, transport: http() });
const paidFetch = wrapFetchWithPayment(fetch, wallet, BigInt(1_000_000));

const res = await paidFetch(
  "https://x402.bankr.bot/0xYourWallet/weather?city=London",
);
console.log(await res.json());
// { city: "London", temperature: 12, conditions: "cloudy", timestamp: "..." }

Next Steps

• View logs and revenue in the dashboard
• Learn about security for your environment variables
• CLI reference for all available commands

Config File

The bankr.x402.json file defines your x402 Cloud services — pricing, methods, and schemas for agent discovery.

Created automatically by bankr x402 init and updated by bankr x402 add and bankr x402 configure.

Example