API Overview

Complete reference for the BOB Gateway API - cross-chain Bitcoin transactions and integrations

Welcome

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

What's new in V3

This reference targets the V3 API. V1 and V2 endpoints remain reachable but are superseded — new integrations should use /v3. Upgrading from V1 or V2? See the Migration Guide.

The V1 API will be deprecated at the end of July 2026 and shut down afterwards. Migrate any V1 integration to V3 before that date — see the Migration Guide. V2 remains supported.

V3 builds on V2 with multi-chain support and richer settlement data:

Non-EVM chains (Tron & Solana) — srcChain/dstChain and the address/token parameters now accept 0x… on EVM chains and Base58 on Tron/Solana. POST /v3/create-order returns a tagged GatewayTxData union — { "type": "evm" | "tron" | "solana", ... } — so a client dispatches on type. The Solana entry returns a base64-encoded, unsigned VersionedTransaction: decode, sign, re-serialize, and broadcast it (don't sign the base64 string directly). The Tron entry adds feeLimit (max TRX, in sun, the wallet may burn).
Chain-aware PATCH /v3/register-tx — for offramp and tokenSwap, the body now carries src_tx_hash + src_chain (EVM 0x… hash or Base58 Solana signature) instead of V2's evm_txhash. onramp is unchanged (bitcoin_tx_hex / bitcoin_txid).
USD on order info — srcInfo, dstInfo, settled token transfers (received_tokens / refunded_tokens), and pending_btc_payment now each carry an optional usd field, valued at order time. In V2, usd was only on quote amounts and fee-breakdown lines.
Affiliate fees on tokenSwap — tokenSwap quotes now embed a single resolved affiliate ({ address, bps }), charged by the aggregator (Bungee/Velora) on the source chain. Because the quote is the create-order body, embedding the affiliate is what stops it being dropped on the round-trip. Aggregators allow only one partner fee per swap, so passing more than one affiliate returns the new TOO_MANY_AFFILIATES error code. (onramp/offramp keep V2's multi-recipient affiliates list — see the Monetization section in the integration guide.)
ownerAddress & refundAddress — GET /v3/get-quote accepts an optional ownerAddress (EVM owner / refund-claimant, also used for order lookup) that is resolved onto each quote variant, and an optional refundAddress (Bitcoin refund address for onramps). Routes that need an owner but don't get one return the new MISSING_OWNER_ADDRESS error code.
Removed parameters — gasRefill, strategyTarget, and strategyMessage are no longer supported; supplying any of them is rejected with an error.

Authentication

API keys are optional — the API is reachable without authentication. A key unlocks:

Analytics dashboard — your orders, volume, and affiliate earnings
Higher rate limits than keyless usage

Partner Onboarding

Get an API key and go live — full flow and contact details

When you have a key, send it as a Bearer token on every V3 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 cross-chain token swaps:

Get Available Routes

Call GET /v3/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 /v3/get-routes

Returns information about supported chains, tokens, bridges, and fee structures.

Call GET /v3/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 /v3/get-quote?srcChain=bitcoin&dstChain=bob&amount=10000000...

Addresses and token identifiers are 0x… on EVM chains and Base58 on Tron/Solana. Pass affiliates=0xAddr1:50,0xAddr2:25 to route a basis-point cut to one or more recipients on settlement, and ownerAddress/refundAddress where the route requires them.

Create an Order

Pass the quote to POST /v3/create-order to lock in the quote and create an order. This reserves liquidity with the market maker and returns transaction details including:

For BTC to X (onramp, Bitcoin → chain): A Bitcoin address to send to, or a PSBT to sign.
For X to BTC (offramp, chain → Bitcoin): chain transaction data to execute.
For tokenSwap (chain → chain): chain transaction data to execute.

POST /v3/create-order
{ "onramp": { ...quote data } }

For offramp and tokenSwap, the returned transaction data is a tagged GatewayTxData union — dispatch on type ("evm", "tron", or "solana").

Sign and Send Transaction

Execute the transaction:

For BTC to X (onramp): Create and sign a Bitcoin transaction to the provided address, or use the provided PSBT.
For X to BTC (offramp) or tokenSwap: Sign and broadcast the chain transaction using the provided transaction data. On EVM/Tron use the call fields (to, data, value); on Solana, decode the base64 unsigned VersionedTransaction, sign it, re-serialize, and broadcast.

Register Transaction

Call PATCH /v3/register-tx with the signed transaction hash/hex. This allows Gateway to track your order and provide status updates.

PATCH /v3/register-tx
{ "onramp":    { "order_id": "...", "bitcoin_tx_hex": "..." } }
{ "offramp":   { "order_id": "...", "src_tx_hash": "0x...", "src_chain": "ethereum" } }
{ "tokenSwap": { "order_id": "...", "src_tx_hash": "0x...", "src_chain": "ethereum" } }

The body shape varies by route: onramp carries bitcoin_tx_hex (and/or bitcoin_txid); offramp and tokenSwap carry src_tx_hash + src_chain (a 0x… hash on EVM, a Base58 signature on Solana).

Monitor Single Order

Track the status of a specific order using GET /v3/get-order/{id}. Returns the status and details for a single order by its order ID.

GET /v3/get-order/0x1234abcd...

Use this endpoint to monitor the progress of an individual order, including its current state and any updates.

Monitor All User Orders

Track the progress of all orders for a user using GET /v3/get-orders/{user_address}. Returns every order (pending and completed) associated with the specified user address.

GET /v3/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.