> ## Documentation Index
> Fetch the complete documentation index at: https://distributedcrafts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Card title="OpenAPI Specification" icon="file-code" href="/api-reference/openapi.json">
  View the complete API specification
</Card>

## What's new in V3

<Info>
  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](/gateway/migration).
</Info>

<Warning>
  **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](/gateway/migration). V2 remains supported.
</Warning>

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](/gateway/integration#monetization-affiliate-fees).)
* **`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

<Card title="Partner Onboarding" icon="rocket" href="/gateway/onboarding">
  Get an API key and go live — full flow and contact details
</Card>

When you have a key, send it as a Bearer token on every V3 request:

```http theme={null}
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:

<Steps>
  <Step title="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.

    ```bash theme={null}
    GET /v3/get-routes
    ```

    Returns information about supported chains, tokens, bridges, and fee structures.
  </Step>

  <Step title="Get a Quote">
    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.

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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"`).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Register Transaction">
    Call `PATCH /v3/register-tx` with the signed transaction hash/hex. This allows Gateway to track your order and provide status updates.

    ```bash theme={null}
    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).
  </Step>

  <Step title="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.

    ```bash theme={null}
    GET /v3/get-order/0x1234abcd...
    ```

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

  <Step title="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.

    ```bash theme={null}
    GET /v3/get-orders/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
    ```

    Poll this endpoint to update your UI as orders progress through states: pending → confirmed → completed.
  </Step>
</Steps>

<Note>
  The SDK handles all these steps automatically via `executeQuote()`. Use the SDK for easier integration, or call the API directly for custom implementations.
</Note>