Migration Guide

Overview

V4 is the current BOB Gateway API. It requires a source-chain refund address before order creation, makes register-tx an onramp-only Bitcoin submission endpoint, and supports optional slippage with a recommendation per route. V3 remains available for existing integrations.

V1 and V2 removal

V1 and V2 have been removed. Their endpoints and generated API clients are no longer available. The earlier deprecation schedule is complete; migrate directly to V4 using the notes below.

Upgrade from V3

1. Change the endpoint version

The base URL is unchanged: https://gateway-api-mainnet.gobob.xyz. Update all seven endpoints:

2. Replace ownerAddress with a source-chain refund address

Remove ownerAddress from quote requests. V4 accepts refundAddress for every route, encoded for the source chain:

A price-only get-quote request may omit refundAddress. create-order rejects a quote without it with MISSING_REFUND_ADDRESS. Request a fresh quote with the address before execution and pass the returned quote to create-order.

- GET /v3/get-quote?...&ownerAddress=0xOwner
+ GET /v4/get-quote?...&refundAddress=bc1q...

The example above is for an onramp. Use a source-chain address for other routes; the Bitcoin destination of an offramp is not its refund address. Keep sender and recipient encoded for their respective chains.

3. Choose explicit or automatic slippage

GET /v4/get-quote now accepts requests without slippage. Gateway chooses a suitable tolerance for the route and returns it in the quote's slippage field. V3 still requires this parameter.

This is a backward-compatible addition alongside the breaking changes above: existing explicit values remain supported. To request a recommendation, remove the parameter entirely:

- GET /v4/get-quote?...&slippage=300
+ GET /v4/get-quote?...

Slippage is expressed in basis points (100 = 1%, 300 = 3%). Read the resolved value from onramp.slippage, offramp.slippage, or tokenSwap.slippage and show it before execution. Pass the returned quote unchanged to create-order; to use a different tolerance, request a new quote with an explicit slippage value. See the recommendation example.

4. Submit only signed Bitcoin transactions to register-tx

V4 register-tx delegates onramp broadcasting to Gateway. It validates the signed transaction against the order, screens it, and broadcasts it.

PATCH /v4/register-tx
Content-Type: application/json

{
  "onramp": {
    "order_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "bitcoin_tx_hex": "<signed raw Bitcoin transaction hex>"
  }
}

• Finalize the signed PSBT and extract raw transaction hex before submission. A PSBT or bitcoin_txid alone is not accepted.
• Remove offramp and tokenSwap registration calls. Broadcast their source transactions with the user's wallet; Gateway indexes them from the chain.
• Do not send the old src_tx_hash / src_chain registration bodies to V4.
• The submission response remains a string or { "onramp": { "txid": "..." } }. Continue polling the order for settlement.

5. Keep shared response handling

V4 retains these V3 response models:

• GatewayCreateOrderV3: onramp, offramp, or tokenSwap. For the latter two, dispatch on the transaction's type: evm, tron, or solana.
• GatewayOrderInfoV3 and PaginatedOrdersResponseV3: order status, settled transfers, pagination, and optional USD amounts.
• GatewayTokenAmountV2: quote amounts and fee lines with optional USD values.

A model's suffix identifies the schema version, not the endpoint you should call. Use /v4 even when its response model ends in V2 or V3.

V4 upgrade checklist

• Move endpoint calls to /v4.
• Remove ownerAddress from quote requests.
• Include a source-chain refundAddress before creating any order and handle MISSING_REFUND_ADDRESS.
• Keep an explicit slippage limit, or omit it to use Gateway's recommendation; display the resolved value from the quote.
• Submit finalized Bitcoin transaction hex for onramps; remove registration calls for other routes.
• Preserve tagged transaction handling, pagination, affiliate fees, and settlement-status parsing.

Upgrade from V1 or V2

Apply the V4 upgrade checklist, plus these changes from the intervening releases. You do not need to call an intermediate API version.

Upgrade from V2

• Multi-chain transaction data: offramp.tx and tokenSwap.tx are tagged unions. EVM data has to, data, and value; Tron adds feeLimit; Solana contains a base64 unsigned transaction and chainId. Decode, sign, re-serialize, and broadcast Solana transactions with a Solana signer.
• Quote parameters: remove gasRefill, strategyTarget, and strategyMessage. Supply refundAddress as described above.
• Affiliate fees: onramps and offramps accept multiple recipients. Token swaps accept at most one affiliate and expose it as affiliate: { address, bps }, charged on the source chain. More than one returns TOO_MANY_AFFILIATES; omit affiliates for fee-free swaps.
• Order amounts: srcInfo, dstInfo, settled transfers, and pending Bitcoin payments carry optional usd values. The destination amount in dstInfo is an estimate; read settled amounts and transaction hashes from the status payload.
• Refunds and fee bumps: Gateway manages them. refundTx remains null, and there is no user-submitted bumpFeeTx. Track pending_btc_payment and refunded_tokens instead.

Upgrade from V1

Also apply the V2 notes:

• Replace affiliateId with affiliates, a comma-separated list of <address>:<bps> pairs in the API or an array of { address, bps } in the SDK.
• Replace the layerZero quote and create-order variant with tokenSwap. Remove its registration call entirely.
• Replace the bare order array with a paginated response. Both the raw API and SDK return { orders, nextCursor }. Pass the cursor back until it is null or absent.
• Handle the inProgress, success, failed, and refunded status objects instead of bare strings. Raw settled transfers use received_tokens / refunded_tokens; the SDK uses receivedTokens / refundedTokens.
• Quote amounts and fee lines include optional USD values, priceImpact is a fraction, and priceImpactUsd is optional.

Migrating the SDK

The SDK source in this release uses V4 through V4Api. Upgrade @gobob/bob-sdk and use an options object to configure it:

import { GatewaySDK, parseBtc } from '@gobob/bob-sdk';

const gateway = new GatewaySDK(); // Mainnet
// Staging: new GatewaySDK({ basePath: 'https://gateway-api-staging.gobob.xyz' })
// Authenticated: new GatewaySDK({ apiKey: '<32-character key>' })

const quote = await gateway.getQuote({
  fromChain: 'bitcoin',
  fromToken: '0x0000000000000000000000000000000000000000',
  fromUserAddress: 'bc1q...',
  toChain: 'bob',
  toToken: '0x0555E30da8f98308EdB960aa94C0Db47230d2B9c',
  toUserAddress: '0x...',
  refundAddress: 'bc1q...', // Required to execute; use a source-chain address
  amount: parseBtc('0.1'),
});

getQuote forwards refundAddress as supplied; it does not fill it from fromUserAddress. Remove ownerAddress from your SDK parameters too.

Slippage default changed: the SDK no longer sends slippage=300 (3%) when maxSlippage is omitted. The example above now lets Gateway recommend a tolerance per route. To preserve the previous behavior, set it explicitly:

 const quote = await gateway.getQuote({
   // ... other quote parameters
+  maxSlippage: 300, // Preserve the previous 3% tolerance
 });

Omit maxSlippage to use the recommendation and read the resolved slippage from the returned quote. Explicit values, including 0, are forwarded unchanged. The exported DEFAULT_MAX_SLIPPAGE_BPS constant has been removed; replace any direct imports with your application's chosen tolerance. Older generated clients also require slippage; regenerate them from the updated OpenAPI spec to make that request parameter optional.

Generated types

Regenerating from the released spec removes V1Api, V2Api, and schemas used only by those APIs. Code importing generated types directly must update its imports:

Prefer narrowing quotes with 'onramp' in quote, 'offramp' in quote, and 'tokenSwap' in quote, or use getInnerQuote(quote) for common fields. Anonymous generated OneOf names can change when schemas are removed. The SDK's GatewayError class and named error-detail aliases remain the application-facing error interface; handle GatewayErrorCodeV4Variants.MissingRefundAddress for missing refund addresses.

Signing and execution

executeQuote returns { order, tx }, not a transaction ID alone. Without btcSigner, it returns an onramp order with no tx for external Bitcoin payment. Keep the order ID and poll for settlement.

Both BitcoinSigner methods (sendBitcoin and signAllInputs) must resolve to signed raw transaction hex, not a txid or PSBT. Prefer signing without broadcasting so Gateway can validate and broadcast the transaction. An adapter whose wallet broadcasts itself must retrieve the raw transaction hex before returning; the built-in OKX adapter does this.

For EVM sources, inject viem wallet and public clients. Tron requires compatible adapters. Solana source transactions require the API and a Solana signer; executeQuote does not sign Solana transactions.

Next Steps