BitPlan Gateway developer docs
Base URL https://gateway.bitplan.dev. OpenAPI at /openapi.json, discovery at /.well-known/x402-info, MCP at https://mcp.bitplan.dev, agent guide at /llms.txt. This page is also served as Markdown to clients that send Accept: text/markdown.
Endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | /v1/models | optional | Models with prices |
| GET | /v1/rate | none | BSV/USD rate and minimum deposit |
| POST | /v1/chat/completions | optional | OpenAI chat completions |
| POST | /v1/messages | optional | Anthropic Messages API |
| POST | /v1/messages/count_tokens | none | Anthropic token count (estimate) |
| POST | /v1/responses | optional | OpenAI Responses API |
| POST | /v1/images/generations | optional | OpenAI image generation |
| GET, POST | /v1/batches | bearer | Your recent batches; Submit many requests to run within 24 hours at the batch price |
| GET | /v1/batches/{id} | bearer | A batch's status, and its results once it has finished |
| POST | /v1/evaluate | optional | Typed questions over a state (classify, score, yes/no) |
| GET | /v1/account | bearer | Credits, tier, paymail and BYOK status |
| GET | /v1/account/usage | bearer | Recent requests and ledger entries |
| POST | /v1/deposit | bearer | Add credits |
| PUT, DELETE | /v1/account/paymail | bearer | Claim a paymail handle at @bitplan.dev; Release the handle |
| PUT, DELETE | /v1/account/byok | bearer | Store your own provider key (wallet-encrypted); Forget a stored key |
| GET | /v1/account/dashboard | bearer | Usage dashboard data (the site's usage page) |
| GET | /v1/credits/packs | none | Card credit packs |
| POST | /v1/credits/checkout | bearer | Buy credits by card |
| GET | /v1/credits/checkout/{id} | bearer | Status of one card purchase |
| GET | /.well-known/x402-info | none | Discovery manifest for x402-aware agents |
Identity
There are no API keys. The bearer is a token your wallet signs, in the bitcoin-auth format pubkey|scheme|timestamp|requestPath|signature. A session token uses the request path https://gateway.bitplan.dev/v1 and lasts 24 hours; a per-request token uses the actual path, signs the SHA-256 of the body (an empty body signs as no body) and lasts five minutes. The HTTP method is not part of the signed message; a 402 challenge does bind the method, path and body it was issued for. Schemes: brc77 (raw key) or brc100 (wallet createSignature with protocolID [1, "bitcoin auth"], keyID = timestamp, counterparty anyone). Anonymous requests are accepted and receive an exact 402.
curl https://gateway.bitplan.dev/v1/chat/completions \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"model":"anthropic/claude-fable-5.1","messages":[{"role":"user","content":"hello"}]}'Payment over HTTP 402
A call without enough credits returns 402 in x402 protocol version 2: the PAYMENT-REQUIRED header (and the body) carry the requirements, scheme exact on BSV with amount in sats, payTo and extra.challengeId, plus fund.paymail for authenticated callers. Pay it from any BSV wallet with a P2PKH input and repeat the identical request with the PAYMENT-SIGNATURE header; the response carries PAYMENT-RESPONSE with the txid. The legacy X402-Proof header still works. A 402 asks for exactly the shortfall (minimum 2,000 sats); send x-gateway-deposit: minimum to be asked for a top-up of at least the minimum deposit (min_deposit_sats on GET /v1/rate) instead. Unused reserve stays as credits.
PAYMENT-SIGNATURE: base64({"x402Version":2,"accepted":<accepts[0]>,"payload":{"transaction":"<signed raw tx, base64>"}})Pricing
Holds cover the worst case: prompt bound, max_tokens, long-context tiers, peak windows and regional rates. Settlement uses the provider's reported cost. You pay provider cost plus 7% to start, 5% after $100 a month of provider cost and 3% after $1,000 a month, at least 2,000 sats a call, and nothing on your own key; on your own lab, Vercel AI Gateway or OpenCode key only the router, search and evaluate are billed, at your tier. GET /v1/models returns all of it per model, and these figures are the operator's live price list.
Batch
Work that can wait a day costs about half. POST /v1/batches takes an endpoint (/v1/chat/completions, /v1/responses or /v1/messages), a model and up to 500 requests inline, holds the batch's worst case once, caps every request at the output it was held for, runs it on OpenRouter's batch service and settles once on the usage it reports. This is OpenRouter's inline batch shape, not OpenAI's file-based batches. A 402 on a batch is paid like any other call. pricing.batch on GET /v1/models names the models and prices; GET /v1/batches lists your batches and GET /v1/batches/{id} returns the results. Text only.
Funding
Three ways in: the wallet pays each 402; anyone sends BSV to the account's paymail (word-word-word@bitplan.dev, or a claimed handle); or a person buys credits by card on the home page. Card credits are fuel for inference only: non-refundable, non-transferable, never paid out.
Tooling
- Skill: npx skills add opldotdev/bitplan.dev --skill gateway -g
- CLI: bitplan gateway token | credits | deposit | models (npm: bitplan)
- OpenCode plugin: opencode-plugin-bitplan, pays 402s from a BRC-100 wallet
- MCP tools: list_models, chat, evaluate, generate_image, credits, deposit