{ "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": "bob" }, { "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": "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": "gasRefill", "in": "query", "description": "Optional gas refill amount (in smallest unit, e.g., wei)", "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", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "strategyMessage", "in": "query", "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": "bob" }, { "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": "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": "gasRefill", "in": "query", "description": "Optional gas refill amount (in smallest unit, e.g., wei)", "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", "required": false, "schema": { "type": "string" }, "style": "form" }, { "name": "strategyMessage", "in": "query", "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": [] } ] } } }, "components": { "schemas": { "ChainTxInfo": { "type": "object", "required": [ "chain", "token", "amount" ], "properties": { "amount": { "type": "string" }, "chain": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": [ "string", "null" ] } } }, "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" }, "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" ] }, "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." }, "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" } } }, "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" } } }, "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" } } }, "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" } } } } } } ] }, "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." }, "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" } } }, "GatewayUserTokenTransfer": { "type": "object", "required": [ "token", "amount", "chain", "txHash" ], "properties": { "amount": { "type": "string" }, "chain": { "type": "string" }, "token": { "type": "string" }, "txHash": { "type": "string" } } }, "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" } } }, "PaginatedOrdersResponse": { "type": "object", "required": [ "orders" ], "properties": { "nextCursor": { "type": [ "string", "null" ] }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayOrderInfoV2" } } } }, "PendingBtcPayment": { "type": "object", "required": [ "txid", "amount" ], "properties": { "amount": { "type": "string" }, "txid": { "type": "string" } } }, "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)." }, "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" } } }, "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)" } ] }