Skip to main content

​
Welcome

The BOB Gateway API enables seamless cross-chain interactions for Bitcoin-powered applications. Build bridges, swaps, and DeFi integrations with Bitcoin liquidity.

OpenAPI Specification

View the complete API specification

​
What’s new in V2

This reference targets the V2 API. V1 endpoints remain reachable but are deprecated.
V2 adds:
  • tokenSwap route — EVM-to-EVM token swaps, alongside onramp (Bitcoin → chain) and offramp (chain → Bitcoin).
  • Multi-affiliate fees — the affiliates query parameter on GET /v2/get-quote accepts a comma-separated list of <address>:<bps> pairs. See the Monetization section in the integration guide.
  • USD values — token amounts and fee-breakdown lines carry an optional usd field.
  • priceImpact / priceImpactUsd — exposed on all V2 quote variants.
  • Paginated GET /v2/get-orders — accepts cursor and limit query parameters and returns { orders: GatewayOrderInfoV2[], nextCursor: string | null } instead of a bare array. Pass back nextCursor to fetch the next page; a null/missing value means there are no more orders.
  • Settlement details in order status — success and refunded statuses are now objects ({ success: { received_tokens: [...] } }, { refunded: { refunded_tokens: [...] } }) where each token entry carries chain, token, amount, and the settlement txHash. In V1 these statuses were bare string enums and the destination txHash lived on dstInfo; V2 dstInfo no longer carries a txHash.
  • pending_btc_payment on offramp in-progress orders — status.inProgress.pending_btc_payment exposes the gateway’s outgoing Bitcoin { txid, amount } while it’s still pending. The V1 bump_fee_tx field is no longer returned (the gateway manages BTC fee bumps internally).

​
Authentication

API keys are optional. All V2 endpoints are reachable without authentication; a key unlocks higher rate limits and access to partner features. To request one, contact the BOB team. When you have a key, send it as a Bearer token on every V2 request: 
Authorization: Bearer <api-key>
Keys are exactly 32 characters long. The SDK takes the same key via new GatewaySDK({ apiKey }) and sets the header for you.

​
How It Works

Gateway transactions follow a 7-step flow to execute Bitcoin↔chain swaps and EVM token swaps:
1

Get Available Routes

Call GET /v2/get-routes to fetch all supported routes, chains, and tokens. This helps you understand what swaps are available and present options to your users.
GET /v2/get-routes
Returns information about supported chains, tokens, bridges, and fee structures.
2

Get a Quote

Call GET /v2/get-quote with your swap parameters (amount, source/destination chains, tokens, etc.). The API returns a discriminated quote (onramp, offramp, or tokenSwap) with routing information, fees, and expected outputs.
GET /v2/get-quote?srcChain=bitcoin&dstChain=bob&amount=10000000...
Pass affiliates=0xAddr1:50,0xAddr2:25 to route a basis-point cut to one or more recipients on settlement.
3

Create an Order

Pass the quote to POST /v2/create-order to lock in the quote and create an order. This reserves liquidity with the market maker and returns transaction details including:
  • For onramp (Bitcoin → chain): A Bitcoin address to send to, or a PSBT to sign.
  • For offramp (chain → Bitcoin): EVM transaction data to execute.
  • For tokenSwap (EVM → EVM): EVM transaction data to execute.
POST /v2/create-order
{ "onramp": { ...quote data } }
4

Sign and Send Transaction

Execute the transaction:
  • For onramp: Create and sign a Bitcoin transaction to the provided address, or use the provided PSBT.
  • For offramp or tokenSwap: Sign and broadcast the EVM transaction using the provided transaction data.
5

Register Transaction

Call PATCH /v2/register-tx with the signed transaction hash/hex. This allows Gateway to track your order and provide status updates.
PATCH /v2/register-tx
{ "onramp":    { "order_id": "...", "bitcoin_tx_hex": "..." } }
{ "offramp":   { "order_id": "...", "evm_txhash": "0x..." } }
{ "tokenSwap": { "order_id": "...", "evm_txhash": "0x..." } }
The body shape varies by route: onramp carries bitcoin_tx_hex (and/or bitcoin_txid); offramp and tokenSwap both carry evm_txhash.
6

Monitor Single Order

Track the status of a specific order using GET /v2/get-order/{id}. Returns the status and details for a single order by its order ID.
GET /v2/get-order/0x1234abcd...
Use this endpoint to monitor the progress of an individual order, including its current state and any updates.
7

Monitor All User Orders

Track the progress of all orders for a user using GET /v2/get-orders/{user_address}. Returns every order (pending and completed) associated with the specified user address.
GET /v2/get-orders/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
Poll this endpoint to update your UI as orders progress through states: pending → confirmed → completed.
The SDK handles all these steps automatically via executeQuote(). Use the SDK for easier integration, or call the API directly for custom implementations.