Skip to Content
EnDocs
Trading API

Order Mode API

Overview

Order Mode Introduction

This API uses the Order-based Model for cross-chain swaps and asset transfers. The order model breaks the entire transaction process into multiple steps, providing better traceability and user experience.

Same-chain & Cross-chain: The order model supports both same-chain swaps and cross-chain exchanges. When fromChain == toChain, it is a same-chain swap (token exchange on the same chain); when fromChain != toChain, it is a cross-chain exchange or asset transfer. The request parameters and flow are identical — the business type is distinguished solely by whether the chains are the same.

Request Flow

  1. Get Quote: Call /bgw-pro/swapx/order/getSwapPrice to get the estimated output amount and fees
  2. Create Order: Call /bgw-pro/swapx/order/makeSwapOrder to create an order and receive transaction data
  3. Sign Transaction: Have the user sign the transaction with their wallet
  4. Submit Order: Call /bgw-pro/swapx/order/submitSwapOrder with the signed transaction
  5. Monitor Status: Poll /bgw-pro/swapx/order/getSwapOrder to track order completion

API List

API_HOST: https://bopenapi.bgwapi.io


1. Get Swap Price

Endpoint: POST /bgw-pro/swapx/order/getSwapPrice

Request Headers

HeaderDescription
Content-Typeapplication/json
Partner-Code<Your partner code> (required)

Request Body Parameters

ParameterTypeRequiredDescription
fromChainstringYesSource chain identifier (e.g., “base”, “bnb”, “eth”)
fromContractstringYesToken contract address on the source chain. Leave empty for native coins.
fromAmountstringYesInput token amount in token units (e.g., “2.0” means 2 tokens)
toChainstringYesDestination chain identifier
toContractstringYesToken contract address on the destination chain. Leave empty for native coins.
fromAddressstringYesAddress of the user initiating the swap
toAddressstringNoRecipient address. Defaults to fromAddress if not set.
feeRatestringNoFee percentage. No fee if omitted (e.g., “0.05” means 5% fee)

Request Example

curl --location '{API_HOST}/bgw-pro/swapx/order/getSwapPrice' \ --header 'Content-Type: application/json' \ --header 'Partner-Code: your_partner_code' \ --data '{ "fromChain": "base", "fromContract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "fromAmount": "2.0", "toChain": "bnb", "toContract": "0x55d398326f99059ff775485246999027b3197955", "fromAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5", "feeRate": "0.05" }'

Response Example

{ "status": 0, "error_code": 0, "data": { "toAmount": "1.885815", "market": "bkbridgev3.liqbridge", "slippage": "0", "priceImpact": "0.0571", "fee": { "totalAmountInUsd": "0.114185", "appFee": { "amountInUsd": "0.1" }, "platformFee": { "amountInUsd": "0.002" } }, "features": [] }, "msg": "success", "title": "", "timestamp": 1769944578163, "trace": "Root=1-697f3600-388d2064762bf6e27f653b29" }

Response Fields

FieldTypeDescription
toAmountstringEstimated amount to be received
marketstringRecommended market / bridge
slippagestringRecommended slippage (decimal format, e.g., “0.03” means 3%)
priceImpactstringPrice impact (decimal format)
feeobjectFee details (optional)
fee.totalAmountInUsdstringTotal fees in USD
fee.appFeeobjectPartner fee details
fee.platformFeeobjectPlatform fee
fee.gasFeeobjectGas fee
features[]stringSupported Gas features. Currently only “no_gas” is supported, meaning the input token can be used to pay Gas fees
eip7702BindendboolWhether an EIP-7702 contract is bound
eip7702ContractstringAddress of the bound contract
eip7702IsBgwboolWhether the bound contract is a BGW EIP-7702 contract

2. Create Swap Order

Endpoint: POST /bgw-pro/swapx/order/makeSwapOrder

Request Headers

HeaderDescription
Content-Typeapplication/json
Partner-Code<Your partner code> (required)

Request Body Parameters

ParameterTypeRequiredDescription
fromChainstringYesSource chain identifier (e.g., “base”, “bnb”, “eth”)
fromContractstringYesToken contract address on the source chain. Leave empty for native coins.
fromAmountstringYesInput token amount in token units
toChainstringYesDestination chain identifier
toContractstringYesToken contract address on the destination chain. Leave empty for native coins.
fromAddressstringYesAddress of the user initiating the swap
toAddressstringYesAddress to receive tokens on the destination chain
marketstringYesSpecified market / bridge to use (e.g., “bkbridgev3.liqbridge”)
slippagestringNoSlippage tolerance (decimal format, e.g., “0.03” means 3%)
feeRatestringNoPartner fee percentage (e.g., “0.05” means 5% fee)
featurestringNoGas feature. By default the user’s wallet native coin is used to pay Gas. Pass “no_gas” to use the input token for Gas. Note: requires getSwapPrice to return the corresponding feature.

Note: The client is responsible for checking whether the initiating wallet has sufficient native coin balance. When insufficient, use the “no_gas” feature by setting the feature parameter to "no_gas".

Request Examples

# Standard transaction request curl --location '{API_HOST}/bgw-pro/swapx/order/makeSwapOrder' \ --header 'Content-Type: application/json' \ --header 'Partner-Code: your_partner_code' \ --data '{ "fromChain": "base", "fromContract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "fromAmount": "2", "toChain": "bnb", "toContract": "0x55d398326f99059ff775485246999027b3197955", "fromAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5", "toAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5", "market": "bkbridgev3.liqbridge", "slippage": "0.03", "feeRate": "0.05" }' # no_gas (EIP-7702) transaction request curl --location '{API_HOST}/bgw-pro/swapx/order/makeSwapOrder' \ --header 'Content-Type: application/json' \ --header 'Partner-Code: your_partner_code' \ --data '{ "fromChain": "base", "fromContract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "fromAmount": "2", "toChain": "bnb", "toContract": "0x55d398326f99059ff775485246999027b3197955", "fromAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5", "toAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5", "market": "bkbridgev3.liqbridge", "slippage": "0.03", "feeRate": "0.05", "feature": "no_gas" }'

Response Examples

Standard Transaction

{ "status": 0, "error_code": 0, "data": { "orderId": "34b34a3391da45928f6c9673fba1a4e8", "txs": [ { "kind": "transaction", "chainName": "base", "chainId": "8453", "data": { "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "calldata": "0xa9059cbb000000000000000000000000803f5ebe49485745a94205b1f129f63326d5383600000000000000000000000000000000000000000000000000000000001e8480", "gasLimit": "54526", "gasPrice": "9000000", "nonce": 308, "value": "0", "baseFee": "5820569", "maxFeePerGas": "11139700", "maxPriorityFeePerGas": "2408846", "supportEIP1559": true } } ] }, "msg": "success", "title": "", "timestamp": 1772619146682, "trace": "Root=1-69a80589-5a8c90f163bf21d31317a994" }

no_gas (EIP-7702) Transaction

{ "status": 0, "error_code": 0, "data": { "orderId": "ccb8d3f244d64e928ea32f1f8127a7b7", "signatures": [ { "kind": "signature", "chainName": "bnb", "chainId": "56", "hash": "0xdbcc895aa03a4c3a286d66fdf6a811884b1d1338f2bef8de7855aa9cb301ff32", "data": { "signType": "eip712", "types": { "Aggregator": [ { "name": "chainId", "type": "uint256" }, { "name": "msgSender", "type": "address" }, { "name": "deadline", "type": "uint256" }, { "name": "nonce", "type": "uint256" }, { "name": "adminContract", "type": "address" }, { "name": "calls", "type": "Call[]" } ], "Call": [ { "name": "target", "type": "address" }, { "name": "value", "type": "uint256" }, { "name": "callData", "type": "bytes" } ], "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ] }, "primaryType": "Aggregator", "domain": { "chainId": "56", "name": "BW7702Admin", "verifyingContract": "0x8C80e4d123e1A9E787B74a150D3220Dabf327707", "version": "1" }, "message": { "adminContract": "0x8C80e4d123e1A9E787B74a150D3220Dabf327707", "calls": [ { "callData": "0xa9059cbb000000000000000000000000b317d9b4b00c7664381db8f3132c774c3c99398c0000000000000000000000000000000000000000000000000087f027d26b47a8", "target": "0x55d398326f99059fF775485246999027B3197955", "value": "0" }, { "callData": "0xa9059cbb000000000000000000000000e84e684c634f2d9de3b5ea471c092f998f7d8b6e0000000000000000000000000000000000000000000000001b397d3f7c5cb858", "target": "0x55d398326f99059fF775485246999027B3197955", "value": "0" } ], "chainId": "56", "deadline": "1770969477", "msgSender": "0x0c1A29c1827cf064e7DB0256625a1b5cc16b246A", "nonce": "5770969357001941564" } } } ] }, "msg": "success", "title": "", "timestamp": 1770969357741, "trace": "Root=1-698ed90c-0a99621e16d55da149bc0c0c" }

Approve + Swap Transaction

{ "status": 0, "error_code": 0, "data": { "orderId": "11221652138b4ff095871ae267bded4d", "txs": [ { "kind": "transaction", "chainName": "base", "chainId": "8453", "data": { "to": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "calldata": "0x095ea7b30000000000000000000000006d0034c7da87e8f0526b21aa890d40a77c755b68ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "gasLimit": "100000", "gasPrice": "8121700", "nonce": 13, "value": "0", "baseFee": "5002444", "maxFeePerGas": "10003666", "maxPriorityFeePerGas": "2500000", "supportEIP1559": true } }, { "kind": "transaction", "chainName": "base", "chainId": "8453", "data": { "to": "0x6D0034c7DA87e8f0526b21aa890d40A77C755B68", "calldata": "0xd984396a000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000002e00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000833589fcd6edb6e08f4c7c32d4f71b54bda029130000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a793219b9b9219303e718124e1f09f3feca8220a00000000000000000000000000000000000000000000000000000000001e84800000000000000000000000000000000000000000000000000003561a39eca340000000000000000000000000000000000000000000000000000370849ab9e5000000000000000000000000000000000000000000000000000000000069a83aef0000000000000000000000000000000011221652138b4ff095871ae267bded4d0000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001e0bd56bf09cda7260baa5dfdffcfd844d0bc366c9de2091c6aa06c7eb09de449f600000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000041e6fa26b66652b4ff1dcd34be62e9612406c3ea47788d33879223f1ba278ca05b11e491a846dfe03e49a9243dc230ea1d62c8cbf4bf176a319243d82ef3cf444f1b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001e000000000000000000000000000000000000000000000000000000000000003600000000000000000000000000000000000000000000000000000000000002710000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000000000000000000000000006d0034c7da87e8f0526b21aa890d40a77c755b68000000000000000000000000be96d4964d89c17c2c8c4d230313b8b6f7f6507a000000000000000000000000e846373c1a92b167b4e9cd5d8e4d6b1db9e90ec7000000000000000000000000833589fcd6edb6e08f4c7c32d4f71b54bda0291300000000000000000000000060a3e35cc302bfa44cb288bc5a4f316fdb1adb420000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000001000000000000000000000000de956dc64264bb60b6abef225432b8a6b68c81ad0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a07e22067f556af6cb7d6118adaf94647269a14100000000000000000000000060a3e35cc302bfa44cb288bc5a4f316fdb1adb42000000000000000000000000c1cba3fcea344f92d9239c08c0568f6f2f0ee4520000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000027100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000002000000000000000000000000a793219b9b9219303e718124e1f09f3feca8220a000000000000000000000000de956dc64264bb60b6abef225432b8a6b68c81ad000000000000000000000000667701e51b4d1ca244f17c78f7ab8744b4c99f9b000000000000000000000000c1cba3fcea344f92d9239c08c0568f6f2f0ee452000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000000", "gasLimit": "932679", "gasPrice": "8121700", "nonce": 14, "value": "0", "baseFee": "5002444", "maxFeePerGas": "10003666", "maxPriorityFeePerGas": "2500000", "supportEIP1559": true } } ] }, "msg": "success", "title": "", "timestamp": 1772632695884, "trace": "Root=1-69a83a77-59bfd5dd5a523e1f1c962760" }

Response Fields

FieldTypeDescription
orderIdstringOrder ID, used for subsequent submission and queries
txs/signaturesarrayArray of transactions to sign / EIP-7702 authorization message signatures. Only one of txs or signatures will appear — see the “txs and signatures Field Description” below.

txs and signatures Field Description

All operations follow this base structure:

{ "kind": "transaction | signature", "chainName": "chain name", "chainId": "chain identifier", "data": { /* business data fields */ } }
FieldTypeRequiredDescription
kindstringOperation type: transaction or signature. When signature, implement the corresponding signing based on data.signType
chainNamestringChain name: ethereum, bsc, base, arbitrum, solana, etc.
chainIdstringChain identifier
dataobjectDetailed operation data, varies by chain and operation type

3. Submit Swap Order

Endpoint: POST /bgw-pro/swapx/order/submitSwapOrder

Request Headers

HeaderDescription
Content-Typeapplication/json
Partner-Code<Your partner code> (required)

Request Body Parameters

ParameterTypeRequiredDescription
orderIdstringYesOrder ID returned from the makeSwapOrder endpoint
signedTxsstring[]YesArray of signed transaction hex strings (with “0x” prefix)

Request Examples

curl --location '{API_HOST}/bgw-pro/swapx/order/submitSwapOrder' \ --header 'Content-Type: application/json' \ --header 'Partner-Code: your_partner_code' \ --data '{ "orderId": "8d07e1afe0b44485a225f9c0c1afb7a4", "signedTxs": [ "0x02f8b282210581f1843b9aca00847735940082d4fe94833589fcd6edb6e08f4c7c32d4f71b54bda0291380b844a9059cbb000000000000000000000000803f5ebe49485745a94205b1f129f63326d5383600000000000000000000000000000000000000000000000000000000001e8480c001a02af477359b2a527b16068e47be735a78da9f99f44188c17f987734ba0d5d750da00326f823a5665e57871935df89b52ad670c4a4108ee27016c8bb1b4580e1b1c4" ] }' # Submit approve + swap transaction signatures curl --location '{API_HOST}/bgw-pro/swapx/order/submitSwapOrder' \ --header 'Content-Type: application/json' \ --header 'Partner-Code: your_partner_code' \ --data '{ "orderId": "8d07e1afe0b44485a225f9c0c1afb7a4", "signedTxs": [ "0xd4dcc6161a285b3e9cf1ba2ac67e18050b12d5a80584d945c334884a8a904ed171aae6a714c0312151e582818fbece79bf4d0c0f2f641b3b8eb8b956796058441b", "0xac47da5accbdaf8c792bae19ac6d8a4d298adc9c1d89403a13fd1160193a1f4b3c55ba9d49875bfae0bbdb6135f63d59165cff274e530320d0add90546cb2cc801" ] }'

Response Example

{ "status": 0, "data": { "orderId": "8d07e1afe0b44485a225f9c0c1afb7a4" }, "msg": "success" }

Response Fields

FieldTypeDescription
orderIdstringOrder ID

4. Get Swap Order

Endpoint: POST /bgw-pro/swapx/order/getSwapOrder

Request Headers

HeaderDescription
Content-Typeapplication/json
Partner-Code<Your partner code> (required)

Request Body Parameters

ParameterTypeRequiredDescription
orderIdstringYesOrder ID to query

Request Example

curl --location '{API_HOST}/bgw-pro/swapx/order/getSwapOrder' \ --header 'Content-Type: application/json' \ --header 'Partner-Code: your_partner_code' \ --data '{ "orderId": "8d07e1afe0b44485a225f9c0c1afb7a4" }'

Response Example

{ "status": 0, "error_code": 0, "data": { "orderId": "deb5e4a45b464d5591bda501c45de854", "status": "refunded", "fromChain": "base", "fromContract": "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb", "fromAmount": "1.8", "toChain": "eth", "toContract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "toAmount": "1.454534", "receiveAmount": "0", "txs": [ { "chain": "base", "txId": "0x9b1bdf8472f34cbc633eed10e0b6a289fcfded46121fc9fa0283a10d914efabb", "stage": "source", "tokens": [] }, { "chain": "base", "txId": "0xab7dded740a02c0a9d287ccd89dd092a12f729e7ca782bf962b6ec06b0301052", "stage": "refund", "tokens": [ { "symbol": "USDC", "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1.790298", "type": "receive", "decimals": 6 } ] } ], "createTime": 1769440411, "updateTime": 1769440424 }, "msg": "success", "title": "", "timestamp": 1772547586003, "trace": "Root=1-69a6ee01-47b275fc4a709e6e349fd7f4" }

Response Fields

FieldTypeDescription
orderIdstringOrder ID
statusstringOrder status — see “Order Status” below
fromChainstringSource chain identifier
fromContractstringSource chain token contract address
fromAmountstringAmount of tokens sent
toChainstringDestination chain identifier
toContractstringDestination chain token contract address
toAmountstringExpected amount to be received
receiveAmountstringActual amount received (shown after order succeeds)
txsarrayTransaction list
messagestringError message (shown on failure)
createTimeint64Order creation time (Unix timestamp, seconds)
updateTimeint64Order last update time (Unix timestamp, seconds)

Transaction Object (txs[]) Fields

FieldTypeDescription
chainstringChain where the transaction occurred
txIdstringTransaction hash
stagestringTransaction stage: source = source chain transaction, target = destination chain transaction, swap = same-chain swap, refund = refund transaction
tokensarrayTokens involved in the transaction. Currently used mainly for displaying refund tokens.

Order Status

statusDescription
initOrder created, but signature has not yet been submitted via submitSwapOrder
processingIn progress
successOrder completed successfully
failedOrder failed
refundingRefund in progress
refundedRefunded

Resources

Supported Chains

  • chainID is used as the fromChain and toChain request parameters
ChainchainIDSame-chain SwapCross-chainnoGas Min. Order (USD)
Ethereumeth5
Solanasol5
BSCbnb5
Basebase5
Arbitrumarbitrum5
Polygonmatic5
Morphmorph1

When order value (USD) ≥ this value, the no_gas feature (pay gas with input token) is supported.

Cross-chain Limits

From ChainliqBridge LimitCCTP Limit
Ethereum1U–200,000U0.1U–500,000U
Solana10U–200,000U
BSC1U–200,000U
Base1U–200,000U0.1U–500,000U
Arbitrum1U–200,000U0.1U–500,000U
Polygon1U–50,000U0.1U–500,000U
Morph5U–50,000U

Fees

Fee Types

The system includes the following fee types:

1. Platform Fee

  • Description: Platform service fee to support platform operations and maintenance.
  • Calculation: Charged as a percentage of the transaction amount.
  • Deduction timing: Deducted during the bridge transaction or swap process.
  • Includes: Platform service fee.

2. Partner Fee (App Fee)

  • Description: A custom fee that partners can configure.
  • Calculation:
    • Percentage: Set via the feeRate parameter (e.g., “0.05” means 5%).
    • Fixed amount: A fixed fee amount is also supported.
  • Settlement: Held by the platform first and settled periodically.
  • Configuration: Set via the feeRate parameter in getSwapPrice and makeSwapOrder requests.

Fee Structure

Fee information is returned as a fee object in the response:

{ "fee": { "totalAmountInUsd": "0.15", "appFee": { "amountInUsd": "0.10" }, "platformFee": { "amountInUsd": "0.03" } } }

Error Codes

  • All endpoints follow the same error code format. Errors differ only in the error_code and message returned.
  • Implement error handling in the following order:
    1. Check if the HTTP statusCode equals 200. If not, display an error immediately.
    2. Check if status in the response equals 0. If 0, parse data. If 1, the request failed — proceed to the next step.
    3. Match error_code against the list below and handle accordingly. Fall back to 80000 for any unrecognized error_code.

Error Code List

Error CodeDescription
80000Internal error; contact us for troubleshooting or retry.
80001Insufficient token balance.
80002Transaction amount below minimum.
80003Transaction amount above maximum.
80004Order expired.
80005Insufficient liquidity; transaction cannot be completed at this time.
80006Illegal request (invalid format, missing required fields, or value out of range).
80007Partner not found or invalid.
80008Reverse quote calculation did not converge (PayFi Swap minAmountOut mode only).
80009Failed to get token info (token does not exist or service error).
80010Failed to get token price or gas price.
80011Failed to generate transaction calldata (PayFi Swap only).
80012Quote failed (no quote available, all markets failed, etc.).
80013Unsupported chain (chain config missing or no available market).
80014Order not found (Order mode only).
80015Order already submitted; do not resubmit (Order mode only).

Error Response Example

{ "status": 1, "error_code": 80000, "data": null, "msg": "system err", "title": "", "timestamp": 1769580545990, "trace": "Root=1-6979a801-6ba8a7696bc0d4256c5b603c" }

Advanced Mode

For advanced trading mode, please refer to the Advanced Mode documentation.

Last updated on