{ "openapi": "3.1.0", "info": { "title": "BOB Gateway API", "description": "BOB Gateway API for Bitcoin swaps", "license": { "name": "" }, "version": "1.0.0" }, "servers": [ { "url": "https://gateway-api-mainnet.gobob.xyz", "description": "Production" }, { "url": "https://gateway-api-staging.gobob.xyz", "description": "Staging" } ], "paths": { "/v1/create-order": { "post": { "tags": [ "v1" ], "summary": "Create a new gateway order.", "description": "Creates a new request, reserves the required liquidity.", "operationId": "create_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayQuote" } } }, "required": true }, "responses": { "201": { "description": "Created order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCreateOrder" } } } }, "400": { "description": "Create order error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "deprecated": true, "security": [ { "api_key": [] } ] } }, "/v1/get-max-spendable/{address}": { "get": { "tags": [ "v1" ], "operationId": "get_max_spendable", "parameters": [ { "name": "address", "in": "path", "description": "Bitcoin address to calculate the maximum spendable amount for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the maximum spendable Bitcoin amount for the given address after accounting for estimated transaction fees", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMaxSpendable" } } } }, "400": { "description": "Get max spendable error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "deprecated": true, "security": [ { "api_key": [] } ] } }, "/v1/get-order/{id}": { "get": { "tags": [ "v1" ], "summary": "Get all orders for a specific ID.", "operationId": "get_order", "parameters": [ { "name": "id", "in": "path", "description": "Order identifier: either the order_id returned by create-order, the source Bitcoin transaction ID , or the source EVM transaction hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get order by either the order_id returned by create-order, the source Bitcoin transaction ID , or the source EVM transaction hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayOrderInfo" } } } }, "400": { "description": "Invalid order ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } }, "404": { "description": "Order not found" } }, "deprecated": true, "security": [ { "api_key": [] } ] } }, "/v1/get-orders/{user_address}": { "get": { "tags": [ "v1" ], "summary": "Get all user orders.", "operationId": "get_orders", "parameters": [ { "name": "user_address", "in": "path", "description": "User address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get all orders", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayOrderInfo" } } } } }, "400": { "description": "Invalid user address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "deprecated": true, "security": [ { "api_key": [] } ] } }, "/v1/get-quote": { "get": { "tags": [ "v1" ], "summary": "Get a gateway quote.", "description": "Checks the available liquidity and provides a quote.", "operationId": "get_quote", "parameters": [ { "name": "srcChain", "in": "query", "description": "Source chain", "required": true, "schema": { "type": "string" }, "style": "form", "example": "bitcoin" }, { "name": "dstChain", "in": "query", "description": "Destination chain", "required": true, "schema": { "type": "string" }, "style": "form", "example": "ethereum" }, { "name": "sender", "in": "query", "description": "Address sending the funds", "required": false, "schema": { "type": "string" }, "style": "form", "example": "bc1qyhc4uslh46axl553pq3mjclrt7dcgmlzxv0ktx" }, { "name": "recipient", "in": "query", "description": "Address receiving the funds", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, { "name": "srcToken", "in": "query", "description": "Source token address", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0x0000000000000000000000000000000000000000" }, { "name": "dstToken", "in": "query", "description": "Destination token address", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7" }, { "name": "amount", "in": "query", "description": "Amount to swap (in smallest unit, e.g., sats or wei)", "required": true, "schema": { "type": "string" }, "style": "form", "example": "100000" }, { "name": "gasRefill", "in": "query", "description": "Deprecated: gas refill is no longer supported. Supplying this field is\nrejected with an error. Removed in V3.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "slippage", "in": "query", "description": "Slippage tolerance (in basis points, e.g., 300 = 3%)", "required": true, "schema": { "type": "string" }, "style": "form", "example": "300" }, { "name": "strategyTarget", "in": "query", "description": "Deprecated: custom strategies are no longer supported. Supplying this\nfield is rejected with an error. Removed in V3.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "strategyMessage", "in": "query", "description": "Deprecated: custom strategies are no longer supported. Supplying this\nfield is rejected with an error. Removed in V3.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "affiliateId", "in": "query", "description": "Optional affiliate ID", "required": false, "schema": { "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "Get a quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayQuote" } } } }, "400": { "description": "Get a quote error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "deprecated": true, "security": [ { "api_key": [] } ] } }, "/v1/get-routes": { "get": { "tags": [ "v1" ], "summary": "Get all supported routes.", "operationId": "get_routes", "responses": { "200": { "description": "Get all supported routes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RouteInfo" } } } } } }, "deprecated": true, "security": [ { "api_key": [] } ] } }, "/v1/register-tx": { "patch": { "tags": [ "v1" ], "summary": "Register a tx for a request.", "description": "Required for the Solver to track and execute some requests.", "operationId": "register_tx", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTx" } } }, "required": true }, "responses": { "200": { "description": "Register successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTxSuccess" } } } }, "400": { "description": "Register error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "deprecated": true, "security": [ { "api_key": [] } ] } }, "/v2/create-order": { "post": { "tags": [ "v2" ], "summary": "Create a new gateway order.", "description": "Creates a new request, reserves the required liquidity.", "operationId": "create_order_v2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayQuoteV2" } } }, "required": true }, "responses": { "201": { "description": "Created order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCreateOrderV2" } } } }, "400": { "description": "Create order error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } } } } }, "/v2/get-max-spendable/{address}": { "get": { "tags": [ "v2" ], "summary": "Get the maximum spendable Bitcoin amount for the given address (v2).", "operationId": "get_max_spendable_v2", "parameters": [ { "name": "address", "in": "path", "description": "Bitcoin address to calculate the maximum spendable amount for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the maximum spendable Bitcoin amount for the given address after accounting for estimated transaction fees", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMaxSpendable" } } } }, "400": { "description": "Get max spendable error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } } }, "security": [ { "api_key": [] } ] } }, "/v2/get-order/{id}": { "get": { "tags": [ "v2" ], "summary": "Get an order by id (v2).", "operationId": "get_order_v2", "parameters": [ { "name": "id", "in": "path", "description": "Order identifier: either the order_id returned by create-order, the source Bitcoin transaction ID , or the source EVM transaction hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get order by either the order_id returned by create-order, the source Bitcoin transaction ID , or the source EVM transaction hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayOrderInfoV2" } } } }, "400": { "description": "Invalid order ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } }, "404": { "description": "Order not found" } }, "security": [ { "api_key": [] } ] } }, "/v2/get-orders/{user_address}": { "get": { "tags": [ "v2" ], "summary": "Get user orders (v2).", "operationId": "get_orders_v2", "parameters": [ { "name": "user_address", "in": "path", "description": "User address", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Cursor used to fetch the next page, obtained from the response's `next_cursor`.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "limit", "in": "query", "description": "Number of orders to request", "required": false, "schema": { "type": "integer", "minimum": 1 }, "style": "form" } ], "responses": { "200": { "description": "Get orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrdersResponse" } } } }, "400": { "description": "Invalid user address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } } }, "security": [ { "api_key": [] } ] } }, "/v2/get-quote": { "get": { "tags": [ "v2" ], "summary": "Get a gateway quote.", "description": "Checks the available liquidity and provides a quote.", "operationId": "get_quote_v2", "parameters": [ { "name": "srcChain", "in": "query", "description": "Source chain", "required": true, "schema": { "type": "string" }, "style": "form", "example": "bitcoin" }, { "name": "dstChain", "in": "query", "description": "Destination chain", "required": true, "schema": { "type": "string" }, "style": "form", "example": "ethereum" }, { "name": "sender", "in": "query", "description": "Address sending the funds", "required": false, "schema": { "type": "string" }, "style": "form", "example": "bc1qyhc4uslh46axl553pq3mjclrt7dcgmlzxv0ktx" }, { "name": "recipient", "in": "query", "description": "Address receiving the funds", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, { "name": "srcToken", "in": "query", "description": "Source token address", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0x0000000000000000000000000000000000000000" }, { "name": "dstToken", "in": "query", "description": "Destination token address", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0xdAC17F958D2ee523a2206206994597C13D831ec7" }, { "name": "amount", "in": "query", "description": "Amount to swap (in smallest unit, e.g., sats or wei)", "required": true, "schema": { "type": "string" }, "style": "form", "example": "100000" }, { "name": "gasRefill", "in": "query", "description": "Deprecated: gas refill is no longer supported. Supplying this field is\nrejected with an error. Removed in V3.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "slippage", "in": "query", "description": "Slippage tolerance (in basis points, e.g., 300 = 3%)", "required": true, "schema": { "type": "string" }, "style": "form", "example": "300" }, { "name": "strategyTarget", "in": "query", "description": "Deprecated: custom strategies are no longer supported. Supplying this\nfield is rejected with an error. Removed in V3.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "strategyMessage", "in": "query", "description": "Deprecated: custom strategies are no longer supported. Supplying this\nfield is rejected with an error. Removed in V3.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "affiliates", "in": "query", "description": "Comma-separated list of `
:` pairs, e.g.\n`0xf39F…:50,0x70997…:25`. Omit or send an empty string for no affiliate\nfees. Max [`intents::MAX_AFFILIATES`] entries; total bps MUST NOT exceed\n[`intents::MAX_AFFILIATE_TOTAL_BPS`]; each bps MUST be > 0.", "required": false, "schema": { "type": "string" }, "style": "form", "example": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266:50,0x70997970C51812dc3A010C7d01b50e0d17dc79C8:25" } ], "responses": { "200": { "description": "Get a quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayQuoteV2" } } } }, "400": { "description": "Get a quote error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } } } } }, "/v2/get-routes": { "get": { "tags": [ "v2" ], "summary": "Get all supported routes (v2).", "operationId": "get_routes_v2", "responses": { "200": { "description": "Get all supported routes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RouteInfo" } } } } } }, "security": [ { "api_key": [] } ] } }, "/v2/register-tx": { "patch": { "tags": [ "v2" ], "summary": "Register a tx for a request (V2 body includes token-swap route).", "operationId": "register_tx_v2", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTxV2" } } }, "required": true }, "responses": { "200": { "description": "Register successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTxSuccess" } } } }, "400": { "description": "Register error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayError" } } } } }, "security": [ { "api_key": [] } ] } }, "/v3/create-order": { "post": { "tags": [ "v3" ], "summary": "Create a new gateway order (V3).", "description": "Accepts a `GatewayQuoteV3` — the signed V3 quote with `ownerAddress` embedded in each variant.", "operationId": "create_order_v3", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayQuoteV3" } } }, "required": true }, "responses": { "201": { "description": "Created order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCreateOrderV3" } } } }, "400": { "description": "Create order error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV3" } } } } } } }, "/v3/get-max-spendable/{address}": { "get": { "tags": [ "v3" ], "summary": "Get the maximum spendable Bitcoin amount for the given address (v3).", "description": "Behaviourally identical to v2; exists so the v3 API surface has its own\n`operationId` (`get_max_spendable_v3`) rather than sharing v2's, which would\ntag the same operation under both v2 and v3 and break generated clients.", "operationId": "get_max_spendable_v3", "parameters": [ { "name": "address", "in": "path", "description": "Bitcoin address to calculate the maximum spendable amount for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the maximum spendable Bitcoin amount for the given address after accounting for estimated transaction fees", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayMaxSpendable" } } } }, "400": { "description": "Get max spendable error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } } }, "security": [ { "api_key": [] } ] } }, "/v3/get-order/{id}": { "get": { "tags": [ "v3" ], "summary": "Get an order by id (v3 — amounts carry USD).", "operationId": "get_order_v3", "parameters": [ { "name": "id", "in": "path", "description": "Order identifier: order_id, source Bitcoin txid, or source EVM tx hash", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get order by order_id, source Bitcoin txid, or source EVM tx hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayOrderInfoV3" } } } }, "400": { "description": "Invalid order ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } }, "404": { "description": "Order not found" } }, "security": [ { "api_key": [] } ] } }, "/v3/get-orders/{user_address}": { "get": { "tags": [ "v3" ], "summary": "Get user orders (v3 — amounts carry USD).", "operationId": "get_orders_v3", "parameters": [ { "name": "user_address", "in": "path", "description": "User address", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Cursor used to fetch the next page, obtained from the response's `next_cursor`.", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "limit", "in": "query", "description": "Number of orders to request", "required": false, "schema": { "type": "integer", "minimum": 1 }, "style": "form" } ], "responses": { "200": { "description": "Get orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrdersResponseV3" } } } }, "400": { "description": "Invalid user address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV2" } } } } }, "security": [ { "api_key": [] } ] } }, "/v3/get-quote": { "get": { "tags": [ "v3" ], "summary": "Get a gateway quote (v3 — requires `ownerAddress`).", "operationId": "get_quote_v3", "parameters": [ { "name": "srcChain", "in": "query", "description": "Source chain", "required": true, "schema": { "type": "string" }, "style": "form", "example": "bitcoin" }, { "name": "dstChain", "in": "query", "description": "Destination chain", "required": true, "schema": { "type": "string" }, "style": "form", "example": "bob" }, { "name": "sender", "in": "query", "description": "Address sending the funds\n(`0x…` on EVM chains, Base58 on Tron/Solana).", "required": false, "schema": { "type": "string" }, "style": "form", "example": "bc1qyhc4uslh46axl553pq3mjclrt7dcgmlzxv0ktx" }, { "name": "recipient", "in": "query", "description": "Address receiving the funds\n(`0x…` on EVM chains, Base58 on Tron/Solana).", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, { "name": "srcToken", "in": "query", "description": "Source token address\n(`0x…` on EVM chains, Base58 mint on Tron/Solana).", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0x0000000000000000000000000000000000000000" }, { "name": "dstToken", "in": "query", "description": "Destination token address\n(`0x…` on EVM chains, Base58 mint on Tron/Solana).", "required": true, "schema": { "type": "string" }, "style": "form", "example": "0x0555E30da8f98308EdB960aa94C0Db47230d2B9c" }, { "name": "amount", "in": "query", "description": "Amount to swap (in smallest unit, e.g., sats or wei)", "required": true, "schema": { "type": "string" }, "style": "form", "example": "100000" }, { "name": "slippage", "in": "query", "description": "Slippage tolerance (in basis points, e.g., 300 = 3%)", "required": true, "schema": { "type": "string" }, "style": "form", "example": "300" }, { "name": "affiliates", "in": "query", "description": "Comma-separated list of `
:` pairs, e.g.\n`0xf39F…:50,0x70997…:25`. Omit or send an empty string for no affiliate\nfees. Max [`intents::MAX_AFFILIATES`] entries; total bps MUST NOT exceed\n[`intents::MAX_AFFILIATE_TOTAL_BPS`]; each bps MUST be > 0.", "required": false, "schema": { "type": "string" }, "style": "form", "example": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266:50,0x70997970C51812dc3A010C7d01b50e0d17dc79C8:25" }, { "name": "ownerAddress", "in": "query", "description": "EVM owner / refund address (`0x…`). This address is used for order lookup,\nand may be used for refunds. The request may be rejected when it is not provided.", "required": false, "schema": { "type": "string" }, "style": "form", "example": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, { "name": "refundAddress", "in": "query", "description": "Optional refund bitcoin address to be used in a bitcoin onramp request.", "required": false, "schema": { "type": "string" }, "style": "form", "example": "bc1qyhc4uslh46axl553pq3mjclrt7dcgmlzxv0ktx" } ], "responses": { "200": { "description": "Get a quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayQuoteV3" } } } }, "400": { "description": "Get a quote error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV3" } } } } } } }, "/v3/get-routes": { "get": { "tags": [ "v3" ], "summary": "Get all supported routes (v3).", "operationId": "get_routes_v3", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RouteInfo" } } } } } } } }, "/v3/register-tx": { "patch": { "tags": [ "v3" ], "summary": "Register a tx for a request (V3 body).", "operationId": "register_tx_v3", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTxV3" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTxSuccess" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayErrorV3" } } } } } } } }, "components": { "schemas": { "ChainTxInfo": { "type": "object", "required": [ "chain", "token", "amount" ], "properties": { "amount": { "type": "string" }, "chain": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": [ "string", "null" ] } } }, "ChainTxInfoV3": { "type": "object", "description": "Source-chain tx info (v3) — adds `usd`.", "required": [ "chain", "token", "amount" ], "properties": { "amount": { "type": "string" }, "chain": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": [ "string", "null" ] }, "usd": { "type": [ "string", "null" ], "description": "USD value of `amount` at order time. Absent if no price feed was available." } } }, "GatewayCreateOrder": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "type": "object", "required": [ "order_id", "address" ], "properties": { "address": { "type": "string", "description": "Bitcoin address to pay to" }, "op_return_data": { "type": [ "string", "null" ], "description": "Optional OP_RETURN data" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "psbt_hex": { "type": [ "string", "null" ], "description": "Hex-encoded Bitcoin PSBT (only present when sender address was provided)" } } } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "type": "object", "required": [ "order_id", "tx" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "tx": { "$ref": "#/components/schemas/TxInfo", "description": "Tx info to execute the swap" } } } } }, { "type": "object", "required": [ "layerZero" ], "properties": { "layerZero": { "type": "object", "required": [ "order_id", "tx" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "tx": { "$ref": "#/components/schemas/TxInfo", "description": "Tx info to execute the swap" } } } } } ], "description": "Created new Gateway order" }, "GatewayCreateOrderV2": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "type": "object", "required": [ "order_id", "address" ], "properties": { "address": { "type": "string", "description": "Bitcoin address to pay to" }, "op_return_data": { "type": [ "string", "null" ], "description": "Optional OP_RETURN data" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "psbt_hex": { "type": [ "string", "null" ], "description": "Hex-encoded Bitcoin PSBT (only present when sender address was provided)" } } } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "type": "object", "required": [ "order_id", "tx" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "tx": { "$ref": "#/components/schemas/TxInfo", "description": "Tx info to execute the swap" } } } } }, { "type": "object", "required": [ "tokenSwap" ], "properties": { "tokenSwap": { "type": "object", "required": [ "order_id", "tx" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "tx": { "$ref": "#/components/schemas/TxInfo", "description": "Tx info to execute the swap" } } } } } ], "description": "V2 create-order response" }, "GatewayCreateOrderV3": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "type": "object", "required": [ "order_id", "address" ], "properties": { "address": { "type": "string", "description": "Bitcoin address to pay to" }, "op_return_data": { "type": [ "string", "null" ], "description": "Optional OP_RETURN data" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "psbt_hex": { "type": [ "string", "null" ], "description": "Hex-encoded Bitcoin PSBT (only present when sender address was provided)" } } } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "type": "object", "required": [ "order_id", "tx" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "tx": { "$ref": "#/components/schemas/GatewayTxData", "description": "Tx data to execute the swap (EVM or Solana)" } } } } }, { "type": "object", "required": [ "tokenSwap" ], "properties": { "tokenSwap": { "type": "object", "required": [ "order_id", "tx" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "tx": { "$ref": "#/components/schemas/GatewayTxData", "description": "Tx data to execute the swap (EVM or Solana)" } } } } } ], "description": "V3 create-order response; offramp and token-swap carry polymorphic `GatewayTxData`." }, "GatewayError": { "type": "object", "description": "Structured error response for V1 API.\nContains an error code, human-readable message, and optional structured details.", "required": [ "code", "error" ], "properties": { "code": { "$ref": "#/components/schemas/GatewayErrorCode", "description": "Stable error code for frontend parsing" }, "details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GatewayErrorDetails", "description": "Optional structured details specific to the error type" } ] }, "error": { "type": "string", "description": "Human-readable error message" } } }, "GatewayErrorCode": { "type": "string", "description": "Error codes for structured error responses that the frontend can parse.\nThese codes are stable and should not be changed without coordinating with the frontend.", "enum": [ "INSUFFICIENT_AMOUNT", "QUOTE_AMOUNT_TOO_LOW", "INSUFFICIENT_SWAP_AMOUNT", "INSUFFICIENT_SOLVER_BALANCE", "INSUFFICIENT_PAYMENT_AMOUNT", "UNABLE_TO_COVER_FEES", "INSUFFICIENT_CONFIRMED_FUNDS", "SIMULATION_FAILED", "GAS_ESTIMATE_FAILED", "PER_ACCOUNT_LIMIT_EXCEEDED", "GLOBAL_LIMIT_EXCEEDED", "EXCEEDED_LIMIT", "INVALID_REQUEST", "INVALID_ORDER_ARGS", "INVALID_AFFILIATE_FEE", "SLIPPAGE_TOO_LOW", "SLIPPAGE_TOO_HIGH", "NO_ROUTE", "DISABLED_CHAIN", "INVALID_DESTINATION_CHAIN_ID", "ORDER_NOT_FOUND", "ORDER_EXPIRED", "DUPLICATE_ORDER", "INTERNAL_ERROR" ] }, "GatewayErrorCodeV2": { "oneOf": [ { "$ref": "#/components/schemas/GatewayErrorCode" }, { "$ref": "#/components/schemas/GatewayErrorCodeV2Variants" } ], "description": "Error codes for V2 API - includes all V1 codes plus new ones." }, "GatewayErrorCodeV2Variants": { "type": "string", "description": "New error codes for V2.", "enum": [ "INVALID_CURSOR", "INSUFFICIENT_SOLVER_BALANCE", "AFFILIATE_FEES_NOT_SUPPORTED_FOR_ROUTE", "UNKNOWN" ] }, "GatewayErrorCodeV3": { "oneOf": [ { "$ref": "#/components/schemas/GatewayErrorCode" }, { "$ref": "#/components/schemas/GatewayErrorCodeV2Variants" }, { "$ref": "#/components/schemas/GatewayErrorCodeV3Variants" } ], "description": "Error codes for V3 API - includes all V1/V2 codes plus new ones." }, "GatewayErrorCodeV3Variants": { "type": "string", "description": "New error codes for V3.", "enum": [ "BUNGEE_NO_ROUTE", "MAX_SLIPPAGE_EXCEEDED", "MISSING_OWNER_ADDRESS", "NON_COMPLIANT_ADDRESSES", "SERVICE_UNAVAILABLE", "TOO_MANY_AFFILIATES" ] }, "GatewayErrorDetails": { "oneOf": [ { "type": "object", "required": [ "expected", "actual" ], "properties": { "actual": { "type": "string" }, "expected": { "type": "string" } } }, { "type": "object", "required": [ "required", "available" ], "properties": { "available": { "type": "string" }, "required": { "type": "string" } } }, { "type": "object", "required": [ "total_fees", "available_amount" ], "properties": { "available_amount": { "type": "string" }, "total_fees": { "type": "string" } } }, { "type": "object", "properties": { "tenderly_url": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "src_chain", "src_token", "dst_chain", "dst_token" ], "properties": { "dst_chain": { "type": "string" }, "dst_token": { "type": "string" }, "src_chain": { "type": "string" }, "src_token": { "type": "string" } } }, { "type": "object", "required": [ "limit" ], "properties": { "limit": { "type": "string" } } }, { "type": "null", "default": null }, { "type": "object", "required": [ "minimum", "actual" ], "properties": { "actual": { "type": "string" }, "minimum": { "type": "string" } } } ], "description": "Structured details for V1 error types." }, "GatewayErrorDetailsV2": { "oneOf": [ { "type": "object", "required": [ "expected", "actual" ], "properties": { "actual": { "type": "string" }, "expected": { "type": "string" } } }, { "type": "object", "required": [ "required", "available" ], "properties": { "available": { "type": "string" }, "required": { "type": "string" } } }, { "type": "object", "required": [ "total_fees", "available_amount" ], "properties": { "available_amount": { "type": "string" }, "total_fees": { "type": "string" } } }, { "type": "object", "properties": { "tenderly_url": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "src_chain", "src_token", "dst_chain", "dst_token" ], "properties": { "dst_chain": { "type": "string" }, "dst_token": { "type": "string" }, "src_chain": { "type": "string" }, "src_token": { "type": "string" } } }, { "type": "object", "required": [ "limit" ], "properties": { "limit": { "type": "string" } } }, { "type": "null", "default": null }, { "type": "object", "required": [ "minimum", "actual" ], "properties": { "actual": { "type": "string" }, "minimum": { "type": "string" } } }, { "type": "object", "required": [ "limit", "token", "chain_id" ], "properties": { "chain_id": { "type": "string" }, "limit": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "src_chain", "src_token", "dst_chain", "dst_token" ], "properties": { "dst_chain": { "type": "string" }, "dst_token": { "type": "string" }, "src_chain": { "type": "string" }, "src_token": { "type": "string" } } }, { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } ], "description": "Structured details for V2 error types - all V1 variants plus V2-only ones.\n\nKept as a single flat `oneOf` (not nested under V1/V2 wrappers) so OpenAPI clients\n(e.g. typescript-fetch) can generate type guards correctly." }, "GatewayErrorDetailsV3": { "oneOf": [ { "type": "object", "required": [ "suggested_bps", "max_bps" ], "properties": { "max_bps": { "type": "string" }, "suggested_bps": { "type": "string" } } }, { "type": "object", "required": [ "addresses" ], "properties": { "addresses": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "expected", "actual" ], "properties": { "actual": { "type": "string" }, "expected": { "type": "string" } } }, { "type": "object", "required": [ "required", "available" ], "properties": { "available": { "type": "string" }, "required": { "type": "string" } } }, { "type": "object", "required": [ "total_fees", "available_amount" ], "properties": { "available_amount": { "type": "string" }, "total_fees": { "type": "string" } } }, { "type": "object", "properties": { "tenderly_url": { "type": [ "string", "null" ] } } }, { "type": "object", "required": [ "src_chain", "src_token", "dst_chain", "dst_token" ], "properties": { "dst_chain": { "type": "string" }, "dst_token": { "type": "string" }, "src_chain": { "type": "string" }, "src_token": { "type": "string" } } }, { "type": "object", "required": [ "limit" ], "properties": { "limit": { "type": "string" } } }, { "type": "null", "default": null }, { "type": "object", "required": [ "minimum", "actual" ], "properties": { "actual": { "type": "string" }, "minimum": { "type": "string" } } }, { "type": "object", "required": [ "limit", "token", "chain_id" ], "properties": { "chain_id": { "type": "string" }, "limit": { "type": "string" }, "token": { "type": "string" } } }, { "type": "object", "required": [ "src_chain", "src_token", "dst_chain", "dst_token" ], "properties": { "dst_chain": { "type": "string" }, "dst_token": { "type": "string" }, "src_chain": { "type": "string" }, "src_token": { "type": "string" } } }, { "type": "object", "required": [ "max", "actual" ], "properties": { "actual": { "type": "string" }, "max": { "type": "string" } } }, { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } } ], "description": "Structured details for V3 error types - all V2 variants plus V3-only ones.\n\nKept as a single flat `oneOf` (not nested under V1/V2/V3 wrappers) so OpenAPI clients\n(e.g. typescript-fetch) can generate type guards correctly." }, "GatewayErrorV2": { "type": "object", "description": "Structured error response for V2 API.\nContains an error code, human-readable message, and optional structured details.", "required": [ "code", "error" ], "properties": { "code": { "$ref": "#/components/schemas/GatewayErrorCodeV2", "description": "Stable error code for frontend parsing" }, "details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GatewayErrorDetailsV2", "description": "Optional structured details specific to the error type" } ] }, "error": { "type": "string", "description": "Human-readable error message" } } }, "GatewayErrorV3": { "type": "object", "description": "Structured error response for V3 API.", "required": [ "code", "error" ], "properties": { "code": { "$ref": "#/components/schemas/GatewayErrorCodeV3", "description": "Stable error code for frontend parsing" }, "details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GatewayErrorDetailsV3", "description": "Optional structured details specific to the error type" } ] }, "error": { "type": "string", "description": "Human-readable error message" } } }, "GatewayLayerZeroQuote": { "type": "object", "required": [ "tx", "fees", "inputAmount", "outputAmount", "recipient" ], "properties": { "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "fees": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "recipient": { "type": "string" }, "sender": { "type": [ "string", "null" ] }, "tx": { "$ref": "#/components/schemas/TxInfo" } } }, "GatewayMaxSpendable": { "type": "object", "required": [ "userAddress", "amount" ], "properties": { "amount": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "userAddress": { "type": "string" } } }, "GatewayOfframpFeeBreakdown": { "type": "object", "required": [ "solverFee", "inclusionFee", "protocolFee", "affiliateFee", "fastestFeeRate" ], "properties": { "affiliateFee": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "fastestFeeRate": { "type": "string" }, "inclusionFee": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "protocolFee": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "solverFee": { "$ref": "#/components/schemas/GatewayTokenAmount" } } }, "GatewayOfframpFeeBreakdownV2": { "type": "object", "description": "V2 offramp fee breakdown. Same shape as V1 but each line carries USD.", "required": [ "solverFee", "inclusionFee", "protocolFee", "affiliateFee", "fastestFeeRate" ], "properties": { "affiliateFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "fastestFeeRate": { "type": "string" }, "inclusionFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "protocolFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "solverFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" } } }, "GatewayOfframpQuote": { "type": "object", "required": [ "srcChain", "tokenAddress", "inputAmount", "outputAmount", "fees", "feeBreakdown", "recipient", "slippage", "txTo" ], "properties": { "affiliateAddress": { "type": [ "string", "null" ] }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "feeBreakdown": { "$ref": "#/components/schemas/GatewayOfframpFeeBreakdown" }, "fees": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "recipient": { "type": "string" }, "sender": { "type": [ "string", "null" ] }, "slippage": { "type": "integer", "format": "int32", "minimum": 0 }, "srcChain": { "type": "string" }, "tokenAddress": { "type": "string" }, "txTo": { "type": "string" } } }, "GatewayOfframpQuoteV2": { "type": "object", "required": [ "srcChain", "tokenAddress", "inputAmount", "outputAmount", "totalFeeUsd", "feeBreakdown", "recipient", "slippage", "txTo" ], "properties": { "affiliateAddress": { "type": [ "string", "null" ], "description": "Affiliate address (V1-compatible field; first entry from `affiliates`)." }, "affiliates": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAffiliate" }, "description": "Resolved affiliate recipients and computed fees (V2)." }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "feeBreakdown": { "$ref": "#/components/schemas/GatewayOfframpFeeBreakdownV2" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "priceImpact": { "type": [ "string", "null" ], "description": "Price impact as a fraction, e.g. `\"-0.05\"` means 5% loss. Absent if no price feed is\navailable." }, "priceImpactUsd": { "type": [ "string", "null" ], "description": "Price impact in USD, excluding execution fee. E.g. `\"-1.00\"` means $1 loss. Absent if no\nprice feed is available." }, "recipient": { "type": "string" }, "sender": { "type": [ "string", "null" ] }, "slippage": { "type": "integer", "format": "int32", "minimum": 0 }, "srcChain": { "type": "string" }, "tokenAddress": { "type": "string" }, "totalFeeUsd": { "type": "string" }, "txTo": { "type": "string" } } }, "GatewayOfframpQuoteV3": { "type": "object", "description": "V3 offramp quote: identical to V2 plus `owner_address`.", "required": [ "srcChain", "tokenAddress", "inputAmount", "outputAmount", "totalFeeUsd", "feeBreakdown", "recipient", "slippage", "txTo", "ownerAddress" ], "properties": { "affiliateAddress": { "type": [ "string", "null" ], "description": "Affiliate address (V1-compatible field; first entry from `affiliates`)." }, "affiliates": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAffiliate" }, "description": "Resolved affiliate recipients and computed fees (V2)." }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "feeBreakdown": { "$ref": "#/components/schemas/GatewayOfframpFeeBreakdownV2" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "ownerAddress": { "type": "string", "description": "Resolved EVM owner / refund-claimant for the on-chain order." }, "priceImpact": { "type": [ "string", "null" ], "description": "Price impact as a fraction, e.g. `\"-0.05\"` means 5% loss. Absent if no price feed is\navailable." }, "priceImpactUsd": { "type": [ "string", "null" ], "description": "Price impact in USD, excluding execution fee. E.g. `\"-1.00\"` means $1 loss. Absent if no\nprice feed is available." }, "recipient": { "type": "string" }, "sender": { "type": [ "string", "null" ] }, "slippage": { "type": "integer", "format": "int32", "minimum": 0 }, "srcChain": { "type": "string" }, "tokenAddress": { "type": "string" }, "totalFeeUsd": { "type": "string" }, "txTo": { "type": "string" } } }, "GatewayOnrampFeeBreakdown": { "type": "object", "required": [ "solverFee", "protocolFee", "affiliateFee", "executionFee", "layerzeroFee" ], "properties": { "affiliateFee": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "executionFee": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "layerzeroFee": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "protocolFee": { "$ref": "#/components/schemas/GatewayTokenAmount" }, "solverFee": { "$ref": "#/components/schemas/GatewayTokenAmount" } } }, "GatewayOnrampFeeBreakdownV2": { "type": "object", "required": [ "solverFee", "protocolFee", "affiliateFee", "executionFee", "layerzeroFee" ], "properties": { "affiliateFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "executionFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "layerzeroFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "protocolFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "solverFee": { "$ref": "#/components/schemas/GatewayTokenAmountV2" } } }, "GatewayOnrampQuote": { "type": "object", "required": [ "inputAmount", "outputAmount", "fees", "executionFees", "recipient", "token", "slippage", "feeBreakdown", "dstChain", "dstToken", "signedQuoteData" ], "properties": { "affiliateAddress": { "type": [ "string", "null" ], "description": "Affiliate address" }, "dstChain": { "type": "string", "description": "Destination chain" }, "dstToken": { "type": "string", "description": "Destination token address" }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "executionFees": { "$ref": "#/components/schemas/GatewayTokenAmount", "description": "Cost to execute the onramp on-chain" }, "feeBreakdown": { "$ref": "#/components/schemas/GatewayOnrampFeeBreakdown", "description": "Detailed fee breakdown" }, "fees": { "$ref": "#/components/schemas/GatewayTokenAmount", "description": "Total fees for this swap" }, "gasRefill": { "type": [ "string", "null" ], "description": "Optional gas refill amount" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmount", "description": "Amount requested by the user" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmount", "description": "Final amount after fees" }, "recipient": { "type": "string", "description": "Recipient address" }, "sender": { "type": [ "string", "null" ], "description": "Sender address" }, "signedQuoteData": { "type": "string", "description": "The signed quote data to be used in create-order" }, "slippage": { "type": "string", "description": "Slippage tolerance" }, "strategyAddress": { "type": [ "string", "null" ] }, "strategyMessage": { "type": [ "string", "null" ] }, "token": { "type": "string", "description": "Token address" } } }, "GatewayOnrampQuoteV2": { "type": "object", "description": "V2 onramp quote: identical to V1 plus a resolved `affiliates` list. Kept as\na separate type so the V1 OpenAPI schema stays frozen.", "required": [ "inputAmount", "outputAmount", "fees", "executionFees", "recipient", "token", "slippage", "feeBreakdown", "dstChain", "dstToken", "signedQuoteData" ], "properties": { "affiliateAddress": { "type": [ "string", "null" ], "description": "Affiliate address (V1-compatible field; first entry from `affiliates`)." }, "affiliates": { "type": "array", "items": { "$ref": "#/components/schemas/ResolvedAffiliate" }, "description": "Resolved affiliate recipients and computed fees." }, "dstChain": { "type": "string", "description": "Destination chain" }, "dstToken": { "type": "string", "description": "Destination token address" }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "executionFees": { "$ref": "#/components/schemas/GatewayTokenAmountV2", "description": "Cost to execute the onramp on-chain" }, "feeBreakdown": { "$ref": "#/components/schemas/GatewayOnrampFeeBreakdownV2", "description": "Detailed fee breakdown" }, "fees": { "$ref": "#/components/schemas/GatewayTokenAmountV2", "description": "Total fees for this swap" }, "gasRefill": { "type": [ "string", "null" ], "description": "Optional gas refill amount" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2", "description": "Amount requested by the user" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2", "description": "Final amount after fees" }, "priceImpact": { "type": [ "string", "null" ], "description": "Price impact as a fraction, e.g. `\"-0.05\"` means 5% loss. Absent if no price feed is\navailable." }, "priceImpactUsd": { "type": [ "string", "null" ], "description": "Price impact in USD, excluding execution fee. E.g. `\"-1.00\"` means $1 loss. Absent if no\nprice feed is available." }, "recipient": { "type": "string", "description": "Recipient address" }, "sender": { "type": [ "string", "null" ], "description": "Sender address" }, "signedQuoteData": { "type": "string", "description": "The signed quote data to be used in create-order" }, "slippage": { "type": "string", "description": "Slippage tolerance" }, "strategyAddress": { "type": [ "string", "null" ] }, "strategyMessage": { "type": [ "string", "null" ] }, "token": { "type": "string", "description": "Token address" } } }, "GatewayOrderInfo": { "type": "object", "description": "Gateway order info", "required": [ "id", "timestamp", "srcInfo", "dstInfo", "status" ], "properties": { "depositAddress": { "type": [ "string", "null" ] }, "dstInfo": { "$ref": "#/components/schemas/ChainTxInfo" }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "id": { "type": "string" }, "srcInfo": { "$ref": "#/components/schemas/ChainTxInfo" }, "status": { "$ref": "#/components/schemas/GatewayOrderStatus" }, "timestamp": { "type": "integer", "format": "int64" } } }, "GatewayOrderInfoV2": { "type": "object", "description": "Gateway order info (v2)", "required": [ "id", "timestamp", "srcInfo", "dstInfo", "status" ], "properties": { "depositAddress": { "type": [ "string", "null" ] }, "dstInfo": { "$ref": "#/components/schemas/OrderDestinationInfo" }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "id": { "type": "string" }, "srcInfo": { "$ref": "#/components/schemas/ChainTxInfo" }, "status": { "$ref": "#/components/schemas/GatewayOrderStatusV2" }, "timestamp": { "type": "integer", "format": "int64" } } }, "GatewayOrderInfoV3": { "type": "object", "description": "Gateway order info (v3) — v2 shape plus USD on every amount field.", "required": [ "id", "timestamp", "srcInfo", "dstInfo", "status" ], "properties": { "depositAddress": { "type": [ "string", "null" ] }, "dstInfo": { "$ref": "#/components/schemas/OrderDestinationInfoV3" }, "estimatedTimeInSecs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "id": { "type": "string" }, "srcInfo": { "$ref": "#/components/schemas/ChainTxInfoV3" }, "status": { "$ref": "#/components/schemas/GatewayOrderStatusV3" }, "timestamp": { "type": "integer", "format": "int64" } } }, "GatewayOrderStatus": { "oneOf": [ { "type": "object", "required": [ "inProgress" ], "properties": { "inProgress": { "type": "object", "properties": { "bump_fee_tx": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TxInfo" } ] }, "refund_tx": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TxInfo" } ] } } } } }, { "type": "object", "required": [ "failed" ], "properties": { "failed": { "type": "object", "properties": { "refund_tx": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TxInfo" } ] } } } } }, { "type": "string", "enum": [ "success" ] }, { "type": "string", "enum": [ "refunded" ] } ] }, "GatewayOrderStatusV2": { "oneOf": [ { "type": "object", "required": [ "inProgress" ], "properties": { "inProgress": { "type": "object", "properties": { "pending_btc_payment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PendingBtcPayment" } ] }, "refund_tx": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TxInfo" } ] } } } } }, { "type": "object", "required": [ "failed" ], "properties": { "failed": { "type": "object", "properties": { "refund_tx": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TxInfo" } ] } } } } }, { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "object", "required": [ "received_tokens" ], "properties": { "received_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayUserTokenTransfer" } } } } } }, { "type": "object", "required": [ "refunded" ], "properties": { "refunded": { "type": "object", "required": [ "refunded_tokens" ], "properties": { "refunded_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayUserTokenTransfer" } } } } } } ] }, "GatewayOrderStatusV3": { "oneOf": [ { "type": "object", "required": [ "inProgress" ], "properties": { "inProgress": { "type": "object", "properties": { "pending_btc_payment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PendingBtcPaymentV3" } ] }, "refund_tx": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TxInfo" } ] } } } } }, { "type": "object", "required": [ "failed" ], "properties": { "failed": { "type": "object", "properties": { "refund_tx": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TxInfo" } ] } } } } }, { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "object", "required": [ "received_tokens" ], "properties": { "received_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayUserTokenTransferV3" } } } } } }, { "type": "object", "required": [ "refunded" ], "properties": { "refunded": { "type": "object", "required": [ "refunded_tokens" ], "properties": { "refunded_tokens": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayUserTokenTransferV3" } } } } } } ], "description": "Gateway order status (v3) — mirrors v2 with USD-carrying transfer types." }, "GatewayQuote": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "$ref": "#/components/schemas/GatewayOnrampQuote" } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "$ref": "#/components/schemas/GatewayOfframpQuote" } } }, { "type": "object", "required": [ "layerZero" ], "properties": { "layerZero": { "$ref": "#/components/schemas/GatewayLayerZeroQuote" } } } ], "description": "Gateway quote." }, "GatewayQuoteV2": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "$ref": "#/components/schemas/GatewayOnrampQuoteV2" } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "$ref": "#/components/schemas/GatewayOfframpQuoteV2" } } }, { "type": "object", "required": [ "tokenSwap" ], "properties": { "tokenSwap": { "$ref": "#/components/schemas/GatewayTokenSwapQuoteV2" } } } ], "description": "Gateway quote." }, "GatewayQuoteV3": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "$ref": "#/components/schemas/GatewayOnrampQuoteV2" } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "$ref": "#/components/schemas/GatewayOfframpQuoteV3" } } }, { "type": "object", "required": [ "tokenSwap" ], "properties": { "tokenSwap": { "$ref": "#/components/schemas/GatewayTokenSwapQuoteV3" } } } ], "description": "V3 gateway quote — used for both the get-quote response and the create-order body.\n`ownerAddress` is embedded in each variant that carries an owner concept." }, "GatewaySolanaTx": { "type": "object", "description": "Solana transaction returned on V3 create-order (offramp / token-swap).\n\n`transaction` is base64-encoded bincode serialization of an unsigned `VersionedTransaction`.\nClients must decode, sign, re-serialize, and broadcast — do not sign the base64 string directly.", "required": [ "chainId", "transaction" ], "properties": { "chainId": { "type": "integer", "format": "int64", "minimum": 0 }, "transaction": { "type": "string", "example": "AgAAA..." } } }, "GatewayTokenAmount": { "type": "object", "required": [ "amount", "address", "chain" ], "properties": { "address": { "type": "string" }, "amount": { "type": "string" }, "chain": { "type": "string" } } }, "GatewayTokenAmountV2": { "type": "object", "required": [ "amount", "address", "chain" ], "properties": { "address": { "type": "string" }, "amount": { "type": "string" }, "chain": { "type": "string" }, "usd": { "type": [ "string", "null" ], "description": "USD value of `amount`, absent if no price feed is available." } } }, "GatewayTokenSwapQuoteV2": { "type": "object", "required": [ "srcChain", "dstChain", "inputAmount", "outputAmount", "estimatedTimeInSecs", "recipient", "slippage", "fees", "txTo" ], "properties": { "dstChain": { "type": "string" }, "estimatedTimeInSecs": { "type": "integer", "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "fees": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "priceImpact": { "type": [ "string", "null" ], "description": "Price impact as a fraction, e.g. `\"-0.05\"` means 5% loss. Absent if no price feed is\navailable." }, "priceImpactUsd": { "type": [ "string", "null" ], "description": "Price impact in USD, excluding execution fee. E.g. `\"-1.00\"` means $1 loss. Absent if no\nprice feed is available." }, "recipient": { "type": "string" }, "sender": { "type": [ "string", "null" ] }, "slippage": { "type": "integer", "format": "int32", "minimum": 0 }, "srcChain": { "type": "string" }, "txTo": { "type": "string" } } }, "GatewayTokenSwapQuoteV3": { "type": "object", "description": "V3 token-swap quote: the V2 shape plus a resolved `affiliate`. The quote *is*\nthe create-order body, so carrying the affiliate here is what stops it being\ndropped on the round-trip — the aggregator (Bungee/Velora) charges it on the\nsource chain. Mirrors how onramp/offramp embed affiliates in their quotes.", "required": [ "srcChain", "dstChain", "inputAmount", "outputAmount", "estimatedTimeInSecs", "recipient", "slippage", "fees", "txTo" ], "properties": { "affiliate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TokenSwapAffiliateV3", "description": "Affiliate fee applied to this swap, if any. Absent for fee-free swaps." } ] }, "dstChain": { "type": "string" }, "estimatedTimeInSecs": { "type": "integer", "format": "int64", "description": "Estimated time in secs to complete the Order", "minimum": 0 }, "fees": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "inputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "outputAmount": { "$ref": "#/components/schemas/GatewayTokenAmountV2" }, "priceImpact": { "type": [ "string", "null" ], "description": "Price impact as a fraction, e.g. `\"-0.05\"` means 5% loss. Absent if no price feed is\navailable." }, "priceImpactUsd": { "type": [ "string", "null" ], "description": "Price impact in USD, excluding execution fee. E.g. `\"-1.00\"` means $1 loss. Absent if no\nprice feed is available." }, "recipient": { "type": "string" }, "sender": { "type": [ "string", "null" ] }, "slippage": { "type": "integer", "format": "int32", "minimum": 0 }, "srcChain": { "type": "string" }, "txTo": { "type": "string" } } }, "GatewayTxData": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/TxInfo" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "evm" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/TronTxData" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "tron" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GatewaySolanaTx" }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "solana" ] } } } ] } ], "description": "Tagged union of EVM, Tron and Solana transaction data for V3 create-order responses." }, "GatewayUserTokenTransfer": { "type": "object", "required": [ "token", "amount", "chain", "txHash" ], "properties": { "amount": { "type": "string" }, "chain": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": "string" } } }, "GatewayUserTokenTransferV3": { "type": "object", "description": "User token transfer (v3) — adds `usd`.", "required": [ "token", "amount", "chain", "txHash" ], "properties": { "amount": { "type": "string" }, "chain": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": "string" }, "usd": { "type": [ "string", "null" ], "description": "USD value of `amount` at the time the transfer settled." } } }, "OrderDestinationInfo": { "type": "object", "required": [ "chain", "token", "amount" ], "properties": { "amount": { "type": "string", "description": "The _estimated_ amount of the output token, as determined by initial create-order" }, "chain": { "type": "string" }, "token": { "type": "string" } } }, "OrderDestinationInfoV3": { "type": "object", "description": "Destination info (v3) — adds `usd`.", "required": [ "chain", "token", "amount" ], "properties": { "amount": { "type": "string", "description": "The _estimated_ amount of the output token, as determined by create-order." }, "chain": { "type": "string" }, "token": { "type": "string" }, "usd": { "type": [ "string", "null" ], "description": "USD value of the estimated output at order time." } } }, "PaginatedOrdersResponse": { "type": "object", "required": [ "orders" ], "properties": { "nextCursor": { "type": [ "string", "null" ] }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayOrderInfoV2" } } } }, "PaginatedOrdersResponseV3": { "type": "object", "description": "Paginated orders response (v3).", "required": [ "orders" ], "properties": { "nextCursor": { "type": [ "string", "null" ] }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayOrderInfoV3" } } } }, "PendingBtcPayment": { "type": "object", "required": [ "txid", "amount" ], "properties": { "amount": { "type": "string" }, "txid": { "type": "string" } } }, "PendingBtcPaymentV3": { "type": "object", "description": "Pending BTC payment (v3) — adds `usd`.", "required": [ "txid", "amount" ], "properties": { "amount": { "type": "string" }, "txid": { "type": "string" }, "usd": { "type": [ "string", "null" ], "description": "USD value of the pending BTC amount, derived from the order's input rate." } } }, "RegisterTx": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "type": "object", "required": [ "order_id" ], "properties": { "bitcoin_tx_hex": { "type": [ "string", "null" ], "description": "Hex-encoded full Bitcoin transaction" }, "bitcoin_txid": { "type": [ "string", "null" ], "description": "Bitcoin transaction ID (txid)" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" } } } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "type": "object", "required": [ "order_id", "evm_txhash" ], "properties": { "evm_txhash": { "type": "string", "description": "EVM txhash" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" } } } } }, { "type": "object", "required": [ "layerZero" ], "properties": { "layerZero": { "type": "object", "required": [ "order_id", "evm_txhash" ], "properties": { "evm_txhash": { "type": "string", "description": "EVM txhash" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" } } } } } ], "description": "Gateway order to execute" }, "RegisterTxSuccess": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "type": "object", "required": [ "txid" ], "properties": { "txid": { "type": "string" } } } } }, { "type": "string", "enum": [ "ok" ] } ] }, "RegisterTxV2": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "type": "object", "required": [ "order_id" ], "properties": { "bitcoin_tx_hex": { "type": [ "string", "null" ], "description": "Hex-encoded full Bitcoin transaction" }, "bitcoin_txid": { "type": [ "string", "null" ], "description": "Bitcoin transaction ID (txid)" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" } } } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "type": "object", "required": [ "order_id", "evm_txhash" ], "properties": { "evm_txhash": { "type": "string", "description": "EVM txhash" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" } } } } }, { "type": "object", "required": [ "tokenSwap" ], "properties": { "tokenSwap": { "type": "object", "required": [ "order_id", "evm_txhash" ], "properties": { "evm_txhash": { "type": "string", "description": "EVM txhash" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" } } } } } ], "description": "V2 register-tx body (onramp, offramp, and token swap)." }, "RegisterTxV3": { "oneOf": [ { "type": "object", "required": [ "onramp" ], "properties": { "onramp": { "type": "object", "required": [ "order_id" ], "properties": { "bitcoin_tx_hex": { "type": [ "string", "null" ], "description": "Hex-encoded full Bitcoin transaction" }, "bitcoin_txid": { "type": [ "string", "null" ], "description": "Bitcoin transaction ID (txid)" }, "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" } } } } }, { "type": "object", "required": [ "offramp" ], "properties": { "offramp": { "type": "object", "required": [ "order_id", "src_tx_hash", "src_chain" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "src_chain": { "type": "string", "description": "Source chain (e.g. `\"ethereum\"`, `\"solana\"`)" }, "src_tx_hash": { "type": "string", "description": "Source-chain transaction hash (`0x…` on EVM, Base58 signature on Solana)" } } } } }, { "type": "object", "required": [ "tokenSwap" ], "properties": { "tokenSwap": { "type": "object", "required": [ "order_id", "src_tx_hash", "src_chain" ], "properties": { "order_id": { "type": "string", "description": "Unique order id", "example": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" }, "src_chain": { "type": "string", "description": "Source chain (e.g. `\"ethereum\"`, `\"solana\"`)" }, "src_tx_hash": { "type": "string", "description": "Source-chain transaction hash (`0x…` on EVM, Base58 signature on Solana)" } } } } } ], "description": "V3 register-tx body. Offramp and token-swap use chain-aware `srcTxHash` + `srcChain`\n(EVM `0x…` on EVM chains, Base58 signature on Solana)." }, "ResolvedAffiliate": { "type": "object", "description": "Resolved affiliate returned in V2 responses. Includes the computed fee amount in\ninventory asset units (sats for wBTC, 6-decimal units for USDT).", "required": [ "address", "fee" ], "properties": { "address": { "type": "string", "description": "Affiliate recipient address." }, "fee": { "$ref": "#/components/schemas/GatewayTokenAmountV2", "description": "Computed affiliate fee in the inventory asset smallest unit." } } }, "RouteInfo": { "type": "object", "description": "API response type for route information.", "required": [ "srcChain", "dstChain", "srcToken", "dstToken" ], "properties": { "dstChain": { "type": "string" }, "dstToken": { "type": "string" }, "srcChain": { "type": "string" }, "srcToken": { "type": "string" } } }, "TokenSwapAffiliateV3": { "type": "object", "description": "A single affiliate fee on a token swap: `bps` of the swap input paid to\n`address` by the aggregator on the source chain. Aggregators charge one\npartner fee, so a swap carries at most one.", "required": [ "address", "bps" ], "properties": { "address": { "type": "string", "description": "Affiliate fee recipient, encoded for the source chain (`0x…` on EVM)." }, "bps": { "type": "integer", "format": "int32", "description": "Affiliate fee size in basis points of the swap input.", "minimum": 0 } } }, "TronTxData": { "type": "object", "description": "Tron transaction data: the EVM-style call fields plus `feeLimit`, the max TRX\n(in sun) a Tron wallet may burn on energy/bandwidth. EVM chains have no such\nconcept, so it lives on the dedicated Tron entry rather than every tx.", "required": [ "to", "data", "value", "chain", "feeLimit" ], "properties": { "chain": { "type": "string" }, "data": { "type": "string" }, "feeLimit": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string" } } }, "TxInfo": { "type": "object", "required": [ "to", "data", "value", "chain" ], "properties": { "chain": { "type": "string" }, "data": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string" } } } }, "securitySchemes": { "api_key": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "v1", "description": "BOB Gateway Core API (v1)" }, { "name": "v2", "description": "BOB Gateway Core API (v2)" }, { "name": "v3", "description": "BOB Gateway Core API (v3)" } ] }