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

<Info>
  This reference targets the V2 API. V1 endpoints remain reachable but are deprecated.
</Info>

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](/gateway/integration#monetization-affiliate-fees).
* **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 in-progress X-to-BTC 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:

```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 EVM token swaps:

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

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

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

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

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

  <Step title="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 **BTC to X** (`onramp`, Bitcoin → chain): A Bitcoin address to send to, or a PSBT to sign.
    * For **X to BTC** (`offramp`, chain → Bitcoin): EVM transaction data to execute.
    * For **tokenSwap** (EVM → EVM): EVM transaction data to execute.

    ```bash theme={null}
    POST /v2/create-order
    { "onramp": { ...quote data } }
    ```
  </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 EVM transaction using the provided transaction data.
  </Step>

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

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

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

    ```bash theme={null}
    GET /v2/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 /v2/get-orders/{user_address}`. Returns every order (pending and completed) associated with the specified user address.

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