BOB Gateway
Swap native BTC to and from tokens on EVM chains and Tron through BOB Gateway, and track the orders.
เซิร์ฟเวอร์ MCP แบบโฮสต์
npx add-mcp 'https://mcp.gobob.xyz/mcp'ติดตั้งลง Claude Code, Codex, Cursor และอื่นๆ
เอกสาร
Gateway for AI Agents (/gateway/agents)
Gateway for AI Agents [#gateway-for-ai-agents]
Gateway is the best swaps engine for native BTC. It supports a growing set of assets and chains — run gateway-cli routes --json to see what is available.
Agents reach that engine in two ways:
- The Gateway MCP server and agent skills. Connect Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot or any other MCP client to the hosted server at
https://mcp.gobob.xyz/mcp. The agent quotes and prepares the swap, and the user's own wallet signs it. See Connect an agent over MCP. - The Gateway CLI. Any agent that can run a shell command can use it. No SDK to bind, no language to match, no service to host. A Python agent, a TypeScript agent, a shell script, or a scheduled job can all call the same interface and get structured output back.
What your agents can do [#what-your-agents-can-do]
Swap BTC to and from ETH, USDC, USDT, WBTC, cbBTC, DAI, PAXG, XAUt, and more — across Ethereum, Base, BSC, Arbitrum, Avalanche and other major chains. Gateway handles solver liquidity, cross-chain settlement, and on-chain verification. Your agent just calls `quote` and `swap`. Get real-time quotes with slippage, fees, and the exact receive amount before the agent executes anything. Return unsigned PSBTs or EVM transactions and pass them to your own signer. Or sign inside a trusted sandbox and track settlement asynchronously.Who this is for [#who-this-is-for]
Building autonomous agents in Python, TypeScript, or any language that can shell out. The CLI gives you a clean tool interface without writing a Gateway SDK wrapper yourself. Adding Bitcoin swap capabilities to an agent framework (LangChain, LlamaIndex, AgentKit, or your own). Wrap the CLI in a tool function and expose it to the model. Agents that allocate capital, execute yield strategies, or rebalance across chains — and need to touch native BTC as part of those workflows. Ask Claude Code, Codex, Cursor or another coding agent to quote a swap, prepare it for your wallet, or track an order. Connect the hosted MCP server and add the agent skills — nothing to wrap or host.Connect an agent over MCP [#connect-an-agent-over-mcp]
The Gateway MCP server at https://mcp.gobob.xyz/mcp (streamable HTTP) exposes the public V4 API as tools. It is a pass-through: it holds no keys and signs nothing. The agent prepares the order and tells the user what to sign; the user's own wallet signs and broadcasts every transaction, token approvals included.
| Tool | API | What it does |
|---|---|---|
get_routes | GET /v4/get-routes | Lists supported routes, optionally filtered by src_chain and dst_chain |
get_quote | GET /v4/get-quote | Quotes a swap |
create_order | POST /v4/create-order | Creates an order from a quote and returns what the user signs: a deposit address or PSBT for onramps, a transaction otherwise |
quote_and_create | GET /v4/get-quote, then POST /v4/create-order | Quotes a swap and creates the order in one call, returning both. For use once the user has decided to swap |
register_tx | PATCH /v4/register-tx | Optional: broadcasts a fully signed onramp Bitcoin transaction. Deposits are detected on-chain without it |
get_order | GET /v4/get-order/{id} | Looks up one order by order id or source transaction hash |
wait_for_order | GET /v4/get-order/{id} every 15 seconds | Waits up to about 45 seconds for an order's status to leave inProgress, then returns the order as get_order does |
get_orders | GET /v4/get-orders/{addresses} | Lists the orders of up to 20 addresses |
get_max_spendable | GET /v4/get-max-spendable/{address} | The most BTC an address can send after network fees |
Agent skills [#agent-skills]
Three agent skills teach the agent how to use Gateway well. They follow the open Agent Skills format, so they work in any agent that reads SKILL.md files.
| Skill | Use it to |
|---|---|
gateway-swap | Quote a swap, create the order after you confirm, and get exactly what to sign — including the token approval, checked against the Gateway spender |
gateway-order-status | Look up an order or an address's history and explain its status and refunds |
gateway-integrate | Write or review code that integrates Gateway with the SDK, the REST API, or the CLI. Works without the MCP server |
Install [#install]
The `bob-gateway` plugin bundles the skills and the MCP server:```bash
claude plugin marketplace add bob-collective/bob-plugins
claude plugin install bob-gateway@bob
```
The plugin reads `GATEWAY_API_KEY` from the environment Claude Code starts in.
The `bob-gateway` plugin bundles the skills and the MCP server:
```bash
codex plugin marketplace add bob-collective/bob-plugins --ref main
codex plugin add bob-gateway@bob
```
The plugin connects without an API key. To send one, install the skills on their own and connect the server yourself:
```bash
npx skills add bob-collective/bob-plugins -g -a codex
codex mcp add bob-gateway --url https://mcp.gobob.xyz/mcp --bearer-token-env-var GATEWAY_API_KEY
```
```bash
npx skills add bob-collective/bob-plugins
```
Then add the server to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"bob-gateway": {
"url": "https://mcp.gobob.xyz/mcp",
"headers": { "Authorization": "Bearer ${env:GATEWAY_API_KEY}" }
}
}
}
```
Install the skills with `npx skills add bob-collective/bob-plugins`, or copy the skill directories into `.agents/skills/` in your project. Then add a streamable HTTP MCP server named `bob-gateway` with the URL `https://mcp.gobob.xyz/mcp` and an optional `Authorization: Bearer ` header.
The [plugin README](https://github.com/bob-collective/bob-plugins/tree/main/plugins/bob-gateway#install) has ready-made configuration for Gemini CLI, GitHub Copilot and Claude Code without the plugin.
Then ask in plain words — "how much USDC on Base do I get for 0.01 BTC?", "swap 100 USDT on Ethereum to BTC", or "where is my order?".
API key [#api-key]
An API key is optional: every tool works without one. With a key, Gateway applies your integrator pricing to quotes and orders, and your orders show up in your partner dashboard. Set it as GATEWAY_API_KEY in the environment your agent starts from — never paste it into the chat.
The server applies the same regional restrictions as the Gateway API, so it refuses connections from blocked jurisdictions.
Why the CLI is a good agent tool [#why-the-cli-is-a-good-agent-tool]
Agents call tools and read structured output. The Gateway CLI is built around that interface. None of this is an AI feature — it is good CLI design, which turns out to be most of what an agent needs.
Add `--json` to any `quote`, `swap`, `balance`, `routes`, or `status` call and get structured output. Errors come back structured too — an agent can branch on a failure instead of parsing prose.```bash
gateway-cli quote --src BTC --dst USDC:base --amount 100USD --json
```
The `--unsigned` flag returns an unsigned Bitcoin PSBT or EVM transaction and stops. The agent never holds a key. It passes the payload to whatever signer or policy layer you trust, and that layer decides whether to sign.
`--no-wait` submits a swap and returns an order ID instead of blocking until settlement. The agent moves on; your polling loop checks status separately.
`--amount 100USD` resolves to the correct amount of BTC at the current price. "Move a hundred dollars of Bitcoin to Base" maps almost word-for-word onto a command.
Keys and endpoints come from environment variables. No config file left behind — the right way to inject secrets into a sandbox or container.
The agent loop [#the-agent-loop]
An agentic swap follows a consistent pattern: discover what is possible, get a quote, decide, then settle.
### Install the CLI [#install-the-cli]Install globally with npm so `gateway-cli` is on the PATH wherever the agent runs.
```bash
npm install -g @gobob/gateway-cli
gateway-cli --help
```
### Discover available routes [#discover-available-routes]
The agent queries available routes so it isn't guessing at assets or chains.
```bash
gateway-cli routes --json
```
### Get a quote [#get-a-quote]
Slippage, fees, and the real receive amount become visible here. The agent should always quote before committing.
```bash
gateway-cli quote \
--src BTC \
--dst USDC:base \
--amount 100USD \
--json
```
### Settle — without handing over a key [#settle--without-handing-over-a-key]
Return an unsigned transaction and pass it to your signer:
```bash
gateway-cli swap \
--src BTC \
--dst USDC:base \
--amount 100USD \
--unsigned \
--json
```
Or, if the CLI is running inside a trusted sandbox, submit and move on:
```bash
# Returns an order ID immediately
gateway-cli swap \
--src BTC \
--dst USDC:base \
--amount 100USD \
--no-wait \
--json
```
### Track settlement [#track-settlement]
Poll the order ID until the swap settles. The agent can check in between other work.
```bash
gateway-cli status <order-id> --json
```
To list all orders for an address — useful for agents that need to reconcile outstanding positions:
```bash
gateway-cli orders <address> --json
```
The CLI currently uses the V3 SDK/API. For a direct V4 integration, submit signed raw Bitcoin transaction hex to `PATCH /v4/register-tx` for onramps; a txid alone is not accepted. Offramp and token-swap transactions are indexed from the source chain. See the [V4 migration notes](/gateway/migration).
Expose Gateway to a model [#expose-gateway-to-a-model]
Wrapping the CLI in a tool takes a few lines. Here is a minimal Python example:
import subprocess, json
def gateway_swap(src: str, dst: str, amount: str) -> dict:
"""Swap native BTC and EVM tokens via BOB Gateway. Returns an unsigned tx for your signer to approve."""
out = subprocess.run(
["gateway-cli", "swap", "--src", src, "--dst", dst,
"--amount", amount, "--unsigned", "--json"],
capture_output=True, text=True, check=True,
)
return json.loads(out.stdout)
Give the model that function plus matching quote and status tools and the loop runs itself. The agent quotes, reasons about the result, requests an unsigned swap, your signer approves, and the agent tracks settlement to completion. "Swap $100 of BTC to USDC on Base" becomes a sequence of tool calls with a signature you control in the middle.
Example: the Gateway starter bot [#example-the-gateway-starter-bot]
The gateway-starter-bot is a minimal, educational example of a trading bot built entirely on the Gateway CLI. It's a single bash script that demonstrates the full agent loop in a real strategy.
The bot executes a **"buy the dip"** round-trip:
- BTC to X — swap BTC → USDT on Ethereum.
- Watch — poll the reverse quote (USDT → BTC) until BTC gets cheaper.
- Buy the dip — swap USDT → BTC, ending with more sats than it started with.
The interesting part: there is no external price feed. The gateway quote is the price signal. The bot sold a known number of satoshis; it buys back the moment the gateway would return more sats than were sold (by a configurable threshold). Fees and slippage are already priced into the quote — one tool, one source of truth.
The entire strategy is gateway-cli ... --json piped through jq. Read dip-bot.sh top to bottom — that's the whole thing.
# Safe to run — quotes only, no real swaps
./dip-bot.sh --dry-run
Example dry-run output:
! DRY RUN — no real swaps will be executed. Quotes only.
▸ Trade size 100USD | dip threshold 500bps | poll 60s | max wait 3600s
▸ Onramp: 100USD of BTC -> USDT on Ethereum
✓ Sold 0.00094000 BTC (94000 sats), now holding USDT
▸ Will buy back when a quote returns >= 0.00098700 BTC (98700 sats)
▸ No dip yet: quote 0.00094100 BTC < target 0.00098700 BTC. Waiting 60s…
✓ Dip detected: quote returns 0.00098750 BTC (>= target)
▸ Summary:
sold: 0.00094000 BTC (94000 sats)
bought: 0.00098750 BTC (98750 sats)
net: +0.00004750 BTC (4750 sats)
Live mode performs real swaps with real funds on mainnet. Use a throwaway wallet with a small balance, and always run `--dry-run` first.
Educational "buy the dip" bot — a single bash script. Read it, run it, adapt it.
BOB Gateway integration paths [#bob-gateway-integration-paths]
The MCP server and the CLI are the fastest paths into BOB Gateway, not the only ones. The same engine is available through multiple surfaces:
| Path | Best for |
|---|---|
| MCP server + agent skills | Claude Code, Codex, Cursor and any other MCP client. Hosted at mcp.gobob.xyz, nothing to wrap or run, and the user's wallet signs. |
| Gateway CLI | Any agent that can shell out. Zero binding, works in any language, fastest to prototype. |
| Gateway SDK | Agents built in TypeScript or Node. Type-safe, same swap engine, suitable for production web services. |
| Gateway API | Any language, server-to-server. Full control over request/response handling. |
Gateway has already powered experiments like a Bitcoin yield bot built on Coinbase AgentKit. Frameworks evolve fast — the engine underneath does not. Whether an agent reaches Gateway through a CLI, an MCP server, or next year's framework, it is calling the same swaps engine for native BTC. Build the Bitcoin layer once and let the toolchains find it.
Try it [#try-it]
Set your keys and run a quote to verify the setup:
export BITCOIN_PRIVATE_KEY=...
export EVM_PRIVATE_KEY=...
# Or stay in unsigned mode — no keys required for quoting
gateway-cli quote --src BTC --dst USDC:base --amount 100USD --json
The Gateway skills, install steps for each agent, and the Claude Code and Codex plugin.
Source code, installation, and full command reference.
Integration guides, supported routes, and SDK reference.
Use the REST API directly from your agent.
Show us what you build.