兑换 API

交易接入完整流程

Copy page

一次完整的代币兑换接入会使用三类 Binance Web3 API：

• 兑换 API（Trading API）：选择兑换路径、构造 swap 交易，并在需要时提供 ERC-20 授权交易数据。
• 链上交易 API（Transaction API）：广播钱包签名后的交易。
• 钱包 API（Wallet API）：查询交易上链后的详情和状态。

Trading API 和 Transaction API 不会托管你的私钥。它们只返回未签名的交易数据，或中继你已经签名的交易。请始终在自己的钱包或签名器中完成签名。

这些 API 的每个请求都需要使用 API Key 和 Secret Key 进行鉴权，详见鉴权说明。

“授权”的两层含义

本流程中的“授权”有两种不同含义：

1. API 请求鉴权：每个 Binance Web3 API 请求都必须携带 X-OC-APIKEY、X-OC-TIMESTAMP 和 X-OC-SIGN。请求签名方法见鉴权说明。
2. ERC-20 代币授权：EVM 兑换 ERC-20 代币前，代币合约必须授权选定的 DEX spender。它是一笔由用户钱包签名的链上交易，只有在当前 allowance 不足时才需要；原生币、Solana 和 Tron 不使用这种模式。

端到端流程（SWAP 模式）

以下是普通代币的标准流程。ERC-20 授权是条件步骤，必须先在链上确认授权成功，再提交 swap 交易。

Code
0. 每个 API 请求使用 API Key + Secret Key 鉴权
1. GET  /approve-transaction（按需）     → 请求 ERC-20 授权交易数据
   签名并广播授权交易，等待链上确认
2. GET  /quote                          → 选择路径并获取 quoteId
3. GET  /swap                           → 获取未签名的 swap 交易
4. 在本地使用用户钱包签名 swap 交易
5. POST /broadcast-transaction           → 广播签名后的 swap 交易
6. GET  /transaction-detail-by-txhash    → 轮询最终链上状态

对于延迟敏感的接入，可用 GET /quote-and-swap 合并第 2 步和第 3 步，但不能因此跳过按需进行的 ERC-20 授权步骤。

第 0 步 —— 对 API 请求进行鉴权

本页所有接口都需要鉴权。计算 X-OC-SIGN 时，必须使用包含 /build 的完整 URL path；API 请求签名与钱包对链上交易的签名是两件不同的事。请求头、HMAC-SHA256 原文、时间窗口和频率限制见鉴权说明。

第 1 步 —— 按需请求并提交 ERC-20 授权

只有同时满足以下条件时才需要授权：

• 当前链为 EVM 链；
• 卖出币种是 ERC-20 代币；
• 用户对标准 DEX spender 的当前 allowance 小于本次兑换数量。

对于普通 SWAP 流程，先检查 allowance；如果 allowance 不足，在获取报价之前调用授权接口 GET /api/v1/dex/aggregator/approve-transaction。该接口才是授权交易数据的来源，此时尚未获取 approveTarget，调用授权接口也不需要它。

参数	取值
binanceChainId	计划执行兑换的链 ID
tokenContractAddress	卖出代币合约地址
approveAmount	授权数量，使用代币最小单位
vendor	普通 SWAP 流程省略；RFQ 流程使用 /quote 返回的 vendorName

响应中的 data[].data 是 ERC-20 approve() calldata，dexContractAddress 是 spender，另有 gas 相关字段。构造一笔 to 为代币合约地址、data 为返回 calldata、from 为用户钱包的 EVM 交易，在本地签名后，通过 POST /api/v1/dex/pre-transaction/broadcast-transaction 广播。

继续调用 /quote 前，必须等待授权交易在链上确认。授权交易和 swap 交易是两笔不同的交易，各自拥有独立的 nonce、签名、txHash 和状态。/swap 传 approveTransaction=true 只是返回授权数据的便捷方式；需要授权时不能用它替代调用 /approve-transaction，客户端仍需签名、广播并确认授权交易。

RFQ 例外： RFQ/RWA 路由在部分场景需要 vendor 专属授权，vendor 参数必须使用 /quote 返回的 vendorName。RFQ 场景应先调用 /quote 获取 vendor，再调用带该 vendor 的 /approve-transaction，然后继续 /swap。详见 RFQ 模式。

第 2 步 —— 获取报价

普通授权已确认，或无需授权时，调用 GET /api/v1/dex/aggregator/quote，传入链、交易对、数量，以及需要时的用户钱包地址。从响应中选择一条路由并保存其 quoteId。

报价响应还会告诉你：

• executionMode：普通代币按 SWAP 流程执行；权益 / RWA 代币按 RFQ 流程执行。
• approveTarget：该路由可能需要授权时的辅助 spender 地址。它不会执行授权，也不能替代 /approve-transaction。普通 SWAP 流程中，它仅用于在集成方需要时辅助核对授权接口返回的 spender。
• quoteId：/swap 使用的路由标识，有效期约 30 秒。

如果报价过期，应重新询价，不要重复使用相同的 quoteId。

第 3 步 —— 构造 Swap 交易

调用 GET /api/v1/dex/aggregator/swap，传入第 2 步得到的 quoteId 及相同的路由参数：binanceChainId、fromTokenAddress、toTokenAddress、amount，以及必填的 userWalletAddress（负责签名的钱包，即交易发送方）。滑点通过 slippagePercent 或 autoSlippage=true 设置，两者必须提供其一。请求参数必须与缓存中的报价一致。响应会在 data.tx 下返回未签名的交易数据。

如果不需要先选择路由，也可以调用 GET /api/v1/dex/aggregator/quote-and-swap 并传入完整询价参数。当前该接口的 vendor 快捷参数支持 LiquidMesh。

链类型	未签名数据内容
EVM	from、to、data、value、gas、gasPrice，以及可选的 maxPriorityFeePerGas
Solana（CT_501）	版本化交易数据，以及 computeUnitPrice、computeUnitLimit
Tron（CT_195）	路由合约 to、合约 calldata data 和调用值 value

第 4 步 —— 在本地签名

使用拥有 data.tx.from（或请求中用户钱包地址）的钱包签名。Binance Web3 API 不应接收私钥或助记词。

EVM 链（BSC、Ethereum、Base 等）

将返回字段映射为 EIP-1559 或 legacy 交易后签名，得到以 0x 开头的十六进制原始签名交易。

data.tx 字段	签名交易字段
from	签名方 / 发送方
to	交易接收方（DEX Router）
data	ABI 编码的 calldata
value	原生币金额（wei）
gas	Gas Limit
gasPrice	Legacy Gas Price（wei）
maxPriorityFeePerGas	EIP-1559 优先费（wei）

Python 示例：签名授权交易和 Swap 交易

安装签名和 RPC 库：

Code
pip install eth-account web3

下面示例使用 eth-account 的私钥签名器，并仅通过 JSON-RPC 获取下一个 nonce。 approve_response 是 /approve-transaction 的 JSON 响应，swap_response 是 /swap 的 JSON 响应。私钥始终保留在本地，不会发送给 Binance Web3 API。

Code
import os

from eth_account import Account
from web3 import Web3

CHAIN_ID = 56  # BSC；请替换为请求中使用的链 ID
RPC_URL = os.environ["EVM_RPC_URL"]
PRIVATE_KEY = os.environ["WALLET_PRIVATE_KEY"]
TOKEN_CONTRACT_ADDRESS = os.environ["FROM_TOKEN_ADDRESS"]

w3 = Web3(Web3.HTTPProvider(RPC_URL))
account = Account.from_key(PRIVATE_KEY)


def as_int(value):
    """将 API 返回的十进制或 0x 前缀字符串转换为整数。"""
    if value is None:
        return 0
    return int(value, 0) if isinstance(value, str) else int(value)


def sign_evm_transaction(*, to, data, value, gas, gas_price, max_priority_fee_per_gas=None):
    nonce = w3.eth.get_transaction_count(account.address, "pending")
    transaction = {
        "chainId": CHAIN_ID,
        "nonce": nonce,
        "to": Web3.to_checksum_address(to),
        "data": data or "0x",
        "value": as_int(value),
        "gas": as_int(gas),
    }
    if max_priority_fee_per_gas:
        transaction["maxFeePerGas"] = as_int(gas_price)
        transaction["maxPriorityFeePerGas"] = as_int(max_priority_fee_per_gas)
    else:
        transaction["gasPrice"] = as_int(gas_price)

    signed = account.sign_transaction(transaction)
    raw_transaction = signed.raw_transaction.hex()
    return raw_transaction if raw_transaction.startswith("0x") else "0x" + raw_transaction


# 1）普通 SWAP 流程中，当 allowance 不足时，先调用 GET /approve-transaction，
#    再调用 GET /quote。
approve_item = approve_response["data"][0]
signed_approval_tx = sign_evm_transaction(
    to=TOKEN_CONTRACT_ADDRESS,  # approve() 在代币合约上执行
    data=approve_item["data"],
    value=0,
    gas=approve_item["gasLimit"],
    gas_price=approve_item["gasPrice"],
)

# 将 signed_approval_tx 作为 signedTransaction 发送到广播接口，
# 等待授权确认后，再调用 GET /quote。

# 2）选择报价后调用 GET /swap。
swap_tx = swap_response["data"]["tx"]
if swap_tx["from"].lower() != account.address.lower():
    raise ValueError("Swap 交易发送方与签名钱包不一致")

signed_swap_tx = sign_evm_transaction(
    to=swap_tx["to"],
    data=swap_tx["data"],
    value=swap_tx.get("value", "0"),
    gas=swap_tx["gas"],
    gas_price=swap_tx["gasPrice"],
    max_priority_fee_per_gas=swap_tx.get("maxPriorityFeePerGas"),
)

broadcast_payload = {
    "binanceChainId": str(CHAIN_ID),
    "address": account.address,
    "signedTransaction": signed_swap_tx,
    "enableMevProtection": False,
}
# 使用 API HMAC 请求头，将 broadcast_payload POST 到 /broadcast-transaction。

当 /swap 未返回 maxPriorityFeePerGas 时，helper 使用接口返回的 gasPrice 作为 legacy 交易的 gasPrice；如果返回了 maxPriorityFeePerGas，则使用返回的 gasPrice 作为 maxFeePerGas，并构造 EIP-1559 type-2 交易。原始签名交易会先规范化为 0x... 字符串，再作为 signedTransaction 发送。API 请求的 HMAC 签名和上面展示的链上钱包签名是相互独立的。

Solana（CT_501）

使用用户的 Solana 钱包对版本化交易签名，并将签名后的交易序列化为 base64。若需在签名前加入指令，使用 /swap-instruction，在本地编译 v0 交易后再签名。

Tron（CT_195）

根据返回字段构造 TRIGGER_SMART_CONTRACT 交易，使用 Tron 签名器签名，并将签名器返回的 JSON 对象序列化为 signedTransaction。该 JSON 必须包含 raw_data 和 signature 数组。不要把原始 calldata hex 作为 signedTransaction 传入，否则广播接口无法识别签名方并会拒绝请求。

第 5 步 —— 广播签名后的 Swap 交易

调用 POST /api/v1/dex/pre-transaction/broadcast-transaction：

字段	取值
binanceChainId	与 /quote、/swap 使用相同的链 ID
signedTransaction	EVM 原始签名 hex、Solana base64 或 Tron 签名 JSON 字符串
address	用户钱包地址；EVM 通常为 data.tx.from
enableMevProtection	可选，仅 EVM 生效；为 true 时使用私有 mempool

成功响应会返回 data.txHash 和内部 data.orderId。请保存 txHash，后续 Wallet API 使用它查询交易详情。

广播调用示例（EVM）

Code
curl -X POST 'https://web3.binance.com/build/api/v1/dex/pre-transaction/broadcast-transaction' \\
  -H 'X-OC-APIKEY: your-api-key' \\
  -H 'X-OC-TIMESTAMP: 2026-08-04T00:00:00.000Z' \\
  -H 'X-OC-SIGN: <request-signature>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "binanceChainId": "56",
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "signedTransaction": "0xf86c808504a817c80082520894d8da6bf26964af9d7eed9e03e53415d37aa96045880de0b6b3a76400008025a0...",
    "enableMevProtection": false
  }'

上面的 X-OC-SIGN 是 Binance Web3 API 请求签名，与 signedTransaction 中编码的链上钱包签名无关。

第 6 步 —— 查询交易详情并轮询状态

将广播响应中的 txHash 传给 Wallet API 接口 GET /api/v1/dex/post-transaction/transaction-detail-by-txhash：

Code
curl -G 'https://web3.binance.com/build/api/v1/dex/post-transaction/transaction-detail-by-txhash' \\
  -H 'X-OC-APIKEY: your-api-key' \\
  -H 'X-OC-TIMESTAMP: 2026-08-04T00:00:01.000Z' \\
  -H 'X-OC-SIGN: <request-signature>' \\
  --data-urlencode 'binanceChainId=56' \\
  --data-urlencode 'txHash=0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890'

响应的 data 数组包含交易详情，检查 data[].txStatus：

txStatus	含义	客户端处理
pending	交易已广播但尚未最终确认	使用退避策略继续轮询
success	交易已在链上成功执行	展示已确认的兑换和代币转账
fail	交易已上链但执行失败	展示失败状态，并检查 gas、method 和转账详情

广播后立即查询时，索引服务可能尚未同步，接口可能返回空的 data 数组。此时应视为“尚未索引”，等待后使用相同的链 ID 和 txHash 重试。授权交易和 swap 交易的 txHash 不同，不能混用。

详情还会返回区块高度、Gas 消耗、交易手续费、输入输出地址、内部调用和代币转账。建议使用 tokenTransferDetails 核对卖出币种和买入币种是否按预期变化，不要仅凭广播成功响应判断兑换成功。

完整流程中的字段传递

来源	下一步
/approve-transaction → data[].data	构造授权交易，本地签名、广播并等待确认
/quote → quoteId	传给 /swap
/quote → approveTarget	仅用于辅助核对 spender，不执行授权
/swap → data.tx	映射为本地钱包交易并签名
/broadcast-transaction → data.txHash	传给 Wallet API transaction-detail-by-txhash
Wallet API → data[].txStatus	驱动前端 pending/success/fail 状态

RFQ 模式（权益代币）

Ondo、BStock 等权益 / RWA 代币可能返回 executionMode=RFQ。这不是普通的原始交易流程：需先获取 vendorName，在需要时请求 vendor 专属授权，然后签名 EIP-712 订单并提交到 RFQ 服务，而不是广播 data.tx。

Code
1. GET  /quote                          → executionMode = RFQ，获取 vendorName 和 typed-data 参数
2. GET  /approve-transaction（按需）     → ERC-20 授权时传入 vendorName
   签名并广播授权交易，等待链上确认
3. GET  /swap                           → 返回 rfq.typedDataToSign
4. 使用用户钱包签名 rfq.typedDataToSign（eth_signTypedData_v4）
5. POST /order/submit                   → 提交 userSignature + vendor + quoteId + requestId
6. GET  /order/{orderId}                → 轮询直到 FILLED / FAILED

签名钱包必须与 /quote 时的 userWalletAddress 一致。POST /order/submit 必填 userSignature（EIP-712 签名）、vendor 和 quoteId——后两者取自 /swap 响应中的 rfq 对象，且此处的 quoteId 是 rfq.orderId 的值，并非 /quote 返回的路由标识。还需传入 requestId（每次新订单生成新 UUID）；重试时复用同一个 requestId 以保证幂等。signingScheme 可选，省略时按 vendor 推断默认值。RFQ 应以订单状态接口作为主要状态来源；Wallet API 交易详情接口针对链上交易 Hash，不能替代 RFQ 订单状态查询。

常见问题

问题	解决办法
40102 Invalid signature	签名路径必须包含 /build，并使用请求实际发送的原始 query string；见鉴权说明。
/swap 返回 QUOTE_EXPIRED（40401）	在 /quote 后约 30 秒内调用 /swap，或改用 /quote-and-swap。
SWAP_QUOTE_MISMATCH（40462）	/swap 的数量、交易对、fee 方向等报价绑定参数必须保持不变。
ERC-20 兑换 revert	调用 approve-transaction，签名并广播返回的授权 calldata，确认授权后再提交 swap。
Wallet API 返回空 data	交易可能尚未被索引；使用相同链 ID 和 txHash 退避重试。
Tron invalid signedTransaction	传入签名后的 {raw_data, signature} JSON，不要传 calldata hex。
Solana 交易被拒绝	检查 computeUnitLimit 和 computeUnitPrice，并使用 /swap-instruction 检查指令。

相关接口

API	接口	用途
Trading API	GET /api/v1/dex/aggregator/quote	选择路由并获取 quoteId
Trading API	GET /api/v1/dex/aggregator/quote-and-swap	单次调用完成询价和构造交易
Trading API	GET /api/v1/dex/aggregator/swap	构造未签名的 swap 交易
Trading API	GET /api/v1/dex/aggregator/approve-transaction	请求 ERC-20 授权交易数据
Transaction API	POST /api/v1/dex/pre-transaction/broadcast-transaction	广播授权或 swap 交易
Wallet API	GET /api/v1/dex/post-transaction/transaction-detail-by-txhash	查询区块、转账以及 pending/success/fail 状态
Trading API	POST /api/v1/dex/aggregator/order/submit	提交签名后的 RFQ 订单
Trading API	GET /api/v1/dex/aggregator/order/{orderId}	轮询 RFQ 结算状态