docs

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

MethodPathAuthPurpose
GET/v1/modelsoptionalModels with prices in BSV, sats and USD per million tokens, tiers, peak windows
GET/v1/ratenoneBSV/USD rate and the minimum deposit
POST/v1/chat/completionsoptionalOpenAI chat completions, JSON or stream: true
POST/v1/images/generationsoptionalOpenAI images, priced per image
GET/v1/accountbearerCredits, tier, paymail, BYOK status
GET/v1/account/usagebearerLast 50 requests and ledger entries
POST/v1/depositbearerAdd credits; always 402 until paid
PUT, DELETE/v1/account/paymailbearerClaim or release a handle at @bitplan.dev
PUT, DELETE/v1/account/byokbearerStore or forget your own provider key, encrypted by your wallet
GET/v1/credits/packsnoneCard packs and what they buy
POST/v1/credits/checkoutbearerBuy credits by card (Stripe Checkout URL)

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 and lasts five minutes. 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
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 with a bsv-tx-v1 challenge: amount_sats, payee_address, payee_locking_script_hex, expires_at, and fund.paymail for authenticated callers. Pay it from any BSV wallet with a P2PKH input and repeat the identical request with the proof header. Send x-gateway-deposit: exact to be asked only for the shortfall (minimum 2,000 sats); otherwise a top-up of at least 0.25 BSV is requested. Unused reserve stays as credits.

retry header
X402-Proof: base64url({"version":"bsv-tx-v1","challenge_id":"…","rawtx_base64":"…","txid":"…"})

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, a model and a list of requests, holds the batch's worst case once, runs it on OpenRouter's batch service and settles once on the usage it reports. pricing.batch on GET /v1/models names the models and prices; 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