Migration Guide

Overview

The V3 API is the current version of BOB Gateway. It adds non-EVM chains (Tron & Solana), richer settlement data, and cross-chain token swaps with affiliate fees. V1 and V2 endpoints remain reachable, but they are superseded and receive no new features — new integrations should target /v3, and existing ones should migrate.

Pick your starting point:

What changed at a glance

Upgrade from V2

1. Change the base path

Every endpoint moves from /v2/... to /v3/.... The route names are unchanged.

- GET  /v2/get-routes
- GET  /v2/get-quote
- POST /v2/create-order
- PATCH /v2/register-tx
- GET  /v2/get-order/{id}
- GET  /v2/get-orders/{user_address}
+ GET  /v3/get-routes
+ GET  /v3/get-quote
+ POST /v3/create-order
+ PATCH /v3/register-tx
+ GET  /v3/get-order/{id}
+ GET  /v3/get-orders/{user_address}

2. Update get-quote parameters

Three parameters were removed and two were added. Supplying a removed parameter is rejected by the gateway.

  GET /v3/get-quote
    ?srcChain=bitcoin
    &dstChain=bob
    &srcToken=0x0000000000000000000000000000000000000000
    &dstToken=0x0555E30da8f98308EdB960aa94C0Db47230d2B9c
    &recipient=0x2D2E86236a5bC1c8a5e5499C517E17Fb88Dbc18c
    &amount=10000000
    &slippage=50
    &affiliates=0xPartnerA:50,0xPartnerB:25
-   &gasRefill=...
-   &strategyTarget=...
-   &strategyMessage=...
+   &ownerAddress=0x2D2E86236a5bC1c8a5e5499C517E17Fb88Dbc18c   # EVM owner / refund-claimant, also used for order lookup
+   &refundAddress=bc1q...                                     # optional Bitcoin refund address for onramps

3. Update register-tx bodies

The onramp body is unchanged. For offramp and tokenSwap, evm_txhash is replaced by src_tx_hash + src_chain — the source-chain transaction identifier and the chain it was broadcast on.

// offramp / tokenSwap
{
  "offramp": {
    "order_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "evm_txhash": "0xabc..."
  }
}

4. Handle the tagged transaction union from create-order

Because orders can now settle on EVM, Tron, or Solana, POST /v3/create-order returns a tagged GatewayTxData union for offramp/tokenSwap. Dispatch on type:

const tx = order.tx; // from create-order response
switch (tx.type) {
  case 'evm':
    // { to, data, value } — send with your EVM wallet
    break;
  case 'tron':
    // adds `feeLimit` (max TRX in sun the wallet may burn)
    break;
  case 'solana':
    // base64-encoded, unsigned VersionedTransaction:
    // decode → sign → re-serialize → broadcast (don't sign the base64 string directly)
    break;
}

5. Read USD values from order info

srcInfo, dstInfo, settled transfers (received_tokens / refunded_tokens), and pending_btc_payment now each carry an optional usd field, valued at order time. In V2, usd appeared only on quote amounts and fee-breakdown lines. Existing code keeps working; opt in by reading the new field where you display fiat estimates.

6. Affiliate fees on tokenSwap

onramp and offramp keep the V2 multi-recipient affiliates list. tokenSwap is different: the fee is charged by the aggregator (Bungee/Velora) on the source chain, and aggregators allow only one partner fee per swap. A tokenSwap quote embeds a single resolved affiliate ({ address, bps }); passing more than one affiliate returns the new TOO_MANY_AFFILIATES error. See the Monetization section for details.

7. New error codes

Handle these V3 additions alongside your existing error handling:

V2 upgrade checklist

• Repoint all endpoints from /v2 to /v3.
• Add ownerAddress to get-quote; add refundAddress for onramps where desired.
• Remove gasRefill, strategyTarget, and strategyMessage from get-quote.
• Swap evm_txhash for src_tx_hash + src_chain in offramp/tokenSwap register-tx bodies.
• Dispatch on the create-order transaction type (evm / tron / solana).
• Send exactly one affiliate on tokenSwap quotes.
• Handle MISSING_OWNER_ADDRESS, TOO_MANY_AFFILIATES, AFFILIATE_FEES_NOT_SUPPORTED_FOR_ROUTE.

Upgrade from V1

V1 → V3 is V1 → V2 followed by V2 → V3. Apply the V1 → V2 changes below, then work through everything in Upgrade from V2.

V1 → V2 changes

- GET /v1/get-quote?...&affiliateId=your-affiliate-id
+ GET /v2/get-quote?...&affiliates=0xPartnerA:50,0xPartnerB:25

  // create-order body
- { "layerZero": { ...quote data } }
+ { "tokenSwap": { ...quote data } }

  // register-tx body (V2 still uses evm_txhash — see V2 → V3 for the src_tx_hash change)
- { "layerZero": { "order_id": "...", "evm_txhash": "0x..." } }
+ { "tokenSwap":  { "order_id": "...", "evm_txhash": "0x..." } }

- GET /v1/get-orders/0x742d...       → [ order, order, ... ]
+ GET /v2/get-orders/0x742d...?limit=20
+                                    → { "orders": [ ... ], "nextCursor": "..." }

V1 → V3 checklist

• Replace affiliateId with the affiliates list.
• Rename the layerZero variant to tokenSwap in create-order and register-tx.
• Switch get-orders parsing to the paginated { orders, nextCursor } shape.
• Then apply the full V2 upgrade checklist.

Migrating the SDK

The @gobob/bob-sdk SDK hides the API version — upgrading the package moves you to /v3. Two breaking changes at the SDK surface matter when you upgrade:

- const gatewaySDK = new GatewaySDK('https://gateway-api-staging.gobob.xyz');
+ const gatewaySDK = new GatewaySDK({ basePath: STAGING_GATEWAY_BASE_URL });
+ // with a key:
+ const gatewaySDK = new GatewaySDK({ apiKey: '<32-char key>' });

  const quote = await gatewaySDK.getQuote({
    fromChain: 'bitcoin',
    fromToken: '0x0000000000000000000000000000000000000000',
    toChain: 'bob',
    toToken: '0x0555E30da8f98308EdB960aa94C0Db47230d2B9c',
    toUserAddress: '0x2D2E...',
    amount: parseBtc('0.1'),
-   affiliateId: 'your-affiliate-id',
+   affiliates: [{ address: '0xYourAddress', bps: 50 }],
+   ownerAddress: '0x2D2E...', // now required — EVM owner / refund-claimant
  });

Next Steps