集成流程

Copy page

完整的 DeFi 交易集成跨三个 Binance Web3 API：

• DeFi API 发现投资品并构建未签名交易 calldata。
• Transaction API 在你的钱包签名后广播交易。
• Wallet API 读取链上交易及其状态。

DeFi API 与 Transaction API 绝不持有你的私钥。它们只返回未签名交易数据或转发你已签名的交易。签名操作请始终在自己的钱包或签名器中完成。

所有请求均使用 API Key 与 Secret Key 鉴权。所需请求头与 HMAC 签名细节见 鉴权。

端到端流程

Code
0. 用 API Key + Secret Key 为每个请求鉴权
1. (数据)   POST /api/v1/defi/data/investment/list  → 选定 investmentId（及 defiProtocolId）
2. (构建)   POST /api/v1/defi/transaction/deposit   → 得到 dataList（APPROVE 在前、主交易在后）
                                                  + 可选 preview（simulate=true）
3. (预览)   可选设 simulate=true，签名前读 balanceChange / healthFactor
4. 用用户钱包本地签名每个 dataList 项（若有 APPROVE 先签，再签主交易）
5. (广播)   POST /api/v1/dex/pre-transaction/broadcast-transaction（Transaction API，逐条签名后广播）
6. (状态)   GET /api/v1/dex/post-transaction/transaction-detail-by-txhash → 轮询 txStatus

步骤 1/2/3 用 DeFi API；步骤 5/6 分别用 Transaction API 与 Wallet API。步骤 2 调用的构建接口取决于操作：/deposit、/redeem、/lp-add、/lp-remove 或 /claim（外加 LP 添加前的纯计算接口 /lp-add/calculate）。

步骤 0 — 为 API 请求鉴权

本指南所有请求均需鉴权。计算 X-OC-SIGN 时使用精确的 URL 路径（含 /build）；API 请求签名与链上钱包签名相互独立。所需请求头、HMAC-SHA256 pre-hash、时间窗与频率限制见 鉴权。

步骤 1 — 发现投资品

每个构建请求以 investmentId 为键，它是跨链通用标识（服务据此反查链——你无需传 binanceChainId，下文 claim 的一种例外情形另作说明）。

• 用 POST /api/v1/defi/data/investment/list 或 /investment/detail 找到用户目标池 / 金库 / 策略的 investmentId。
• claim 且 claimType=REWARD_PROTOCOL 时，用 POST /api/v1/defi/data/protocol/list 找到 defiProtocolId（如 pancakeswap3）。
• claim 且 claimType=REDEMPTION 时，redemptionId 取自用户的 position/list 响应（待赎回仓位上的 redemptionId 字段）。

步骤 2 — 构建交易

用 address、investmentId、操作相关字段调用构建接口，可选 simulate=true。响应 data 为 DefiTxResponse：有序的 dataList（DefiCallDataItem，需要时 APPROVE 在前、其后为主操作）；当 simulate=true 时附 preview 对象。

构建示例 — deposit

Code
curl -X POST 'https://web3.binance.com/build/api/v1/defi/transaction/deposit' \
  -H 'X-OC-APIKEY: your-api-key' \
  -H 'X-OC-TIMESTAMP: 2026-08-15T10:00:00.000Z' \
  -H 'X-OC-SIGN: <request-signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "0x1234567890123456789012345678901234567890",
    "investmentId": "10ab3e25d9f0b72f1f912b5d611f825bec495a74f2e1b25d8bba5fd2e56fb283",
    "token": {
      "tokenAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "amount": "10"
    },
    "simulate": false
  }'

Code
{
  "code": 0,
  "msg": "success",
  "data": {
    "dataList": [
      {
        "callDataType": "APPROVE",
        "from": "0x1234567890123456789012345678901234567890",
        "to": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "value": "0x0",
        "data": "0x095ea7b3...",
        "gasLimit": "50000",
        "gasPrice": null,
        "maxPriorityFeePerGas": "1000000000",
        "maxFeePerGas": "3000000000"
      },
      {
        "callDataType": "DEPOSIT",
        "from": "0x1234567890123456789012345678901234567890",
        "to": "0x87870Bca3F3fF67225794148012b73643B78Ed36",
        "value": "0x0",
        "data": "0xa9059cbb...",
        "gasLimit": "200000",
        "gasPrice": null,
        "maxPriorityFeePerGas": "1000000000",
        "maxFeePerGas": "3000000000"
      }
    ],
    "preview": null
  },
  "timestamp": 1748601600000
}

按序签名广播 dataList 的每一项。若存在 callDataType=APPROVE，必须先签名、广播并等其链上确认，再提交主交易——否则主交易会因授权不足而 revert。

步骤 3 — 签名前预览（可选）

任一构建请求设 simulate=true 可在不改变链上状态的前提下获得 data.preview。预览告诉你操作是否预期成功、预估 balanceChange（正=收到，负=支出）、预估网络费用（feeAndContract），以及借贷协议的 healthFactor 变化。可在签名前用它确认滑点、gas 与健康率影响。

preview 结构：

字段	含义
success	模拟交易是否预期上链成功。false 表示该操作链上会 revert——不应继续签名。当 success=false 且 errorMessage 非空（即 revert）时，请求返回 revert 错误码 40484 / 40485，而非 preview 响应体（见错误码）。
balanceChange	有符号代币变动（amount 正=收到，负=支出）。无变动时为空数组（如无可领取奖励）。
feeAndContract.estimatedNetworkFee	预估 gas 费——amount / tokenSymbol（支付 gas 的主链币）/ valueUsd，另可选 rentFeeAmount / rentFeeValueUsd / priorityFeeAmount。模拟在费用估算前失败时各字段为 null。
feeAndContract.interactWith.address	该操作交互的对手合约。
healthFactor	借贷健康因子 before / after。非借贷协议或健康因子不可用时为 null。
warnings	非阻断式风险提示，无风险时为空数组。
errorMessage	当 success=false 且非空时，模拟交易会 revert——服务将其映射为 revert 错误码（"超过当前持仓" → 40485，其它 → 40484），请求返回该错误码而非此 preview 响应体。

Code
curl -X POST 'https://web3.binance.com/build/api/v1/defi/transaction/redeem' \
  -H 'X-OC-APIKEY: your-api-key' \
  -H 'X-OC-TIMESTAMP: 2026-08-15T10:00:01.000Z' \
  -H 'X-OC-SIGN: <request-signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "0x1234567890123456789012345678901234567890",
    "investmentId": "10ab3e25d9f0b72f1f912b5d611f825bec495a74f2e1b25d8bba5fd2e56fb283",
    "ratio": "1",
    "slippageBps": "300",
    "simulate": true
  }'

模拟成功返回 success: true，带预估变动、预估费用，以及借贷协议的 health factor 变化：

Code
{
  "success": true,
  "balanceChange": [
    {
      "tokenType": "TOKEN",
      "tokenSymbol": "aBUSD",
      "tokenAddress": "0x6d8981847eb3cc2234179d0f0e72f6be6e0950a4",
      "tokenDecimals": "18",
      "amount": "-1000",
      "valueUsd": "1000.00"
    },
    {
      "tokenType": "TOKEN",
      "tokenSymbol": "USDT",
      "tokenAddress": "0x55d398326f99059fF775485246999027B3197955",
      "tokenDecimals": "18",
      "amount": "999.99",
      "valueUsd": "999.99"
    }
  ],
  "feeAndContract": {
    "estimatedNetworkFee": {
      "amount": "0.000003056787",
      "tokenSymbol": "BNB",
      "valueUsd": "0.002002",
      "rentFeeAmount": null,
      "rentFeeValueUsd": null,
      "priorityFeeAmount": null
    },
    "interactWith": { "address": "0x0667eed0a0aab930af74a3dfedd263a73994f216" }
  },
  "healthFactor": {
    "before": "1.85",
    "after": "1.35"
  },
  "warnings": [
    {
      "code": "HEALTH_FACTOR_WARNING",
      "level": "WARN",
      "message": "Health factor will drop from 1.85 to 1.35 after this transaction."
    }
  ]
}

balanceChange 各项为有符号变动（amount 正=收到，负=支出）。healthFactor 与 warnings 仅借贷协议填充；非借贷操作返回 healthFactor: null 与空数组 warnings。

模拟交易 revert 时，请求返回错误码（HTTP 200、code 非零），而非 preview.success=false 的 200。40485 表示赎回金额超过当前持仓；40484 覆盖其它 revert——看 msg 取原始 revert 原因（如金额低于协议最低值），此时不要让用户签名：

Code
{
  "code": 40484,
  "msg": "The amount is below the minimum required by the protocol. Please enter a larger amount.",
  "data": null,
  "success": false
}

revert 错误码（40484 / 40485）仅在 simulate=true 时返回。revert 文案到码的映射为子串包含匹配，由服务端配置；未命中的 revert 回落 40484。见错误码。

赎回等待期

/transaction/redeem 的响应还会携带 data.redeemDelayDays——赎回等待天数，[min, max] 十进制字符串对：

redeemDelayDays	含义
[]（空数组）	即时到账，无等待期
["7","7"]	固定 7 天
["7","10"]	7–10 天

等待期自赎回交易链上确认后起算。redeemDelayDays 在其余构建接口为 null。本期有等待期的协议包括 Lista（helio）与 Aster（astherus）。

步骤 4 — 本地签名

用拥有每个 dataList[i].from 的钱包签名。Binance Web3 API 绝不会接收私钥或助记词。

EVM 链

把每个 DefiCallDataItem 映射为 EIP-1559 或 legacy 交易并签名，得到以 0x 开头的 hex 原始签名交易。当前支持的全部链均为 EVM 链。

BNB Smart Chain 为 EIP-1559 链，故 BSC 上构建响应会填充 maxFeePerGas + maxPriorityFeePerGas，gasPrice 为 null。其他 EVM 链可能填充其中任一组——存在 1559 字段时优先用它们；gasPrice 有值时再回退使用。value 为 hex 字符串；所有 gas 字段均为十进制字符串。

DefiCallDataItem 字段	签名交易字段
from	签名 / 发送方
to	交易接收方
data	ABI 编码 calldata
value	原生币金额（wei，hex）
gasLimit	Gas limit
gasPrice	Legacy gas price（wei，EIP-1559 链上为 null）
maxPriorityFeePerGas	EIP-1559 优先费（wei）
maxFeePerGas	EIP-1559 单笔最大 gas 费

Python 示例：签名每个 dataList 项

安装签名与 RPC 库：

Code
pip install eth-account web3

私钥始终留在本地，绝不发送给 Binance Web3 API。build_response 是某个构建接口的 JSON 响应。按序签名 dataList 每一项；广播 APPROVE 项并确认后再广播主交易。

Code
import os

from eth_account import Account
from web3 import Web3

CHAIN_ID = 56  # 示例：BSC；用与 investment 匹配的链 ID
RPC_URL = os.environ["EVM_RPC_URL"]
PRIVATE_KEY = os.environ["WALLET_PRIVATE_KEY"]

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


def as_int(value, default=0):
    """将十进制或 0x 前缀的 API 值转为整数；None 时回退 default。"""
    if value is None:
        return default
    return int(value, 0) if isinstance(value, str) else int(value)


def raw_hex(signed):
    """返回签名的 0x 前缀 hex 交易，兼容 web3.py v6/v7。"""
    raw = getattr(signed, "raw_transaction", None) or signed.rawTransaction
    raw_hex_str = raw.hex()
    return raw_hex_str if raw_hex_str.startswith("0x") else "0x" + raw_hex_str


def sign_evm_transaction(*, nonce, to, data, value, gas, gas_price, max_priority_fee_per_gas=None):
    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:
        # EIP-1559（type-2）。构建响应会同时返回 maxFeePerGas 与 maxPriorityFeePerGas，
        # 直接使用 maxFeePerGas，不要回退用 gasPrice。
        transaction["maxFeePerGas"] = as_int(gas_price)
        transaction["maxPriorityFeePerGas"] = as_int(max_priority_fee_per_gas)
    else:
        # legacy。gasPrice 不能为 0——若 API 未返回，则从节点估算。
        transaction["gasPrice"] = as_int(gas_price, default=None) or w3.eth.gas_price

    return raw_hex(account.sign_transaction(transaction))


# 按序逐条签名广播，不要预先一次签完所有项：每条都需要新 nonce，且 APPROVE 必须
# 链上确认后再提交主交易（否则主交易因授权不足 revert）。`broadcast_and_wait` 是你
# 自己的封装：把 signedTransaction POST 到 /broadcast-transaction，并轮询 Wallet API
# 直到交易最终确认。
base_nonce = w3.eth.get_transaction_count(account.address, "pending")

for i, item in enumerate(build_response["data"]["dataList"]):
    if item["from"].lower() != account.address.lower():
        raise ValueError("某个 dataList 项的发送方与签名钱包不一致")

    signed_tx = sign_evm_transaction(
        nonce=base_nonce + i,  # +i，使 APPROVE 与主交易不共用 nonce
        to=item["to"],
        data=item["data"],
        value=item.get("value", "0"),
        gas=item["gasLimit"],
        gas_price=item.get("maxFeePerGas") or item.get("gasPrice"),
        max_priority_fee_per_gas=item.get("maxPriorityFeePerGas"),
    )

    tx_hash = broadcast_and_wait(signed_tx)  # 广播或最终确认失败会抛异常
    # 仅在 tx_hash 确认后，循环才签下一条。

helper 在存在 maxPriorityFeePerGas 时构造 EIP-1559（type-2）交易，以构建响应的 maxFeePerGas 作为费用上限；否则回退 legacy 交易，且当 API 未返回 gasPrice 时从节点估算。nonce 取 base_nonce + i，保证 APPROVE 与主交易拿不同 nonce——但仍需等每笔广播确认后再签下一条，因为主交易要求 APPROVE 先上链。API 请求 HMAC 签名与链上钱包签名相互独立。

步骤 5 — 广播签名交易

对每个已签名的 dataList 项，调用 Transaction API POST /api/v1/dex/pre-transaction/broadcast-transaction：

字段	值
binanceChainId	与 investmentId 匹配的链
signedTransaction	原始签名交易——EVM 链为 0x 前缀 hex
address	用户钱包地址（该项的 from）

先广播 APPROVE 项并等其确认，再广播主交易。成功响应返回 data.txHash，留待下一步使用。

广播示例（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-15T10:00:02.000Z' \
  -H 'X-OC-SIGN: <request-signature>' \
  -H 'Content-Type: application/json' \
  -d '{
    "binanceChainId": "56",
    "address": "0x1234567890123456789012345678901234567890",
    "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-15T10:00:03.000Z' \
  -H 'X-OC-SIGN: <request-signature>' \
  --data-urlencode 'binanceChainId=56' \
  --data-urlencode 'txHash=0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890'

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

txStatus	含义	客户端动作
pending	已广播但未最终确认	退避后再次轮询
success	链上执行成功	标记为已确认
fail	已上链但执行失败	标记为失败；检查 gas、method 与 transfer 详情

广播后可能立即返回空 data 数组（索引尚未追上）——退避重试。务必同时传 binanceChainId 与精确 txHash；APPROVE 与主交易 hash 不同。

calldata 有效期与授权（APPROVE）

• EVM 链上 calldata 无服务端有效期——返回的 dataList 各项是静态的链上交易数据，不是服务端下发的报价；构建接口不设 TTL，同一份 dataList 在落地链上之前可反复重新签名、重新广播。唯一例外：流动性管理类操作（lp-add、lp-add/calculate、lp-remove）携带 20 分钟的服务端超时——其底层仓位 / 区间快照在 20 分钟后失效，若签名前已超过该时长，需重新构建 calldata。
• 宁可重新构建，不要缓存——签名前的 gas 价与仓位状态都会变动，若构建后间隔较久才签名（尤其 LP 操作），应再次调用构建接口。相比链上交易 revert，重新构建成本极低。
• APPROVE 为无限额度（仅 EVM 链）——当存在 APPROVE 项时，它向该项目的 to（spender 合约）授权最大额度（type(uint256).max）。这是针对单个 token、单个 spender 的一次性授权；后续对同一 token/spender 的操作会复用该授权（额度充足时构建直接返回 [DEPOSIT]、不含 APPROVE）。若合规要求禁止无限授权，需确保签名方知晓后再签名 APPROVE 项，或在主交易上链后撤销该授权。

LP 添加 / 移除要点

• tick 区间——三选一：

  • nftId：追加已有仓位，沿用原范围
  • priceRange：百分比区间
  • tickLower + tickUpper：显式原始 int24 对

  规则：

  • 同时传入多组时，仅取优先级最高的一组，其余被静默忽略（优先级：nftId > priceRange > 显式 tick 对）
  • 一组都不传，请求被拒
  • tickLower / tickUpper 为原始 int24，必须对齐池子的 tickSpacing，否则请求被拒

• 先算配对额——只有单边 token 时，先调 POST /transaction/lp-add/calculate 得到配对 token 数量，再调 /lp-add。此接口纯计算，不上链、不扣费。

• LP 移除——以 nftId + ratio（范围 (0, 1]）为键；无需 tokenList，各 token 数量按链上仓位算出。

领取（claim）要点

claimType 决定必填字段：

claimType	必填字段
REWARD_PROTOCOL	defiProtocolId + binanceChainId
REWARD_INVESTMENT	investmentId
LP_FEE	investmentId + nftId
REDEMPTION	investmentId + redemptionId

binanceChainId 通常由 investmentId 反查，客户端传入会被忽略——除 REWARD_PROTOCOL 且无 investmentId 时，客户端必须传 binanceChainId（它是唯一的链信号）。tokenAddressList 可选，缩小领取目标范围。

全流程字段映射

来源	下一步
/data/investment/* → investmentId	传给构建接口
/data/protocol/list → defiProtocolId	传给 claimType=REWARD_PROTOCOL 的 /claim
/data/position/list → redemptionId	传给 claimType=REDEMPTION 的 /claim
/transaction/* → dataList[i]	把每项映射为本地钱包交易并按序签名
/transaction/*（simulate=true）→ preview	签名前检查 balanceChange / healthFactor
已签名 dataList[i] → signedTransaction	POST 到 /broadcast-transaction
/broadcast-transaction → data.txHash	传给 Wallet API transaction-detail-by-txhash
Wallet API → data[].txStatus	确定交易最终结果（pending / success / fail）

常见问题

问题	解决
40102 Signature error	签名路径须含 /build，并对精确原始 body 签名；见 鉴权。
DeFi 构建被拒（40450–40460, 40480–40485）	code 标识失败阶段——按 code 分支，勿按 msg。40480 余额不足→补足；40457 无流动性可移除；40460 模拟失败；40482 RPC 异常→重试；40485 赎回金额超过持仓；40484 其它 preview revert（看 msg）。40459 为兜底码——看 msg。见错误码。
主交易广播 revert	APPROVE 项须先广播并等链上确认后再提交主交易，不能跳过或乱序。
LP 添加因 tick 被拒	tickLower / tickUpper 须为对齐池子 tickSpacing 的原始 int24，或改用 priceRange。
claim 因字段不匹配返回 40454	按 claimType 提供所需字段（见上表）；REWARD_PROTOCOL 需要 binanceChainId。

相关接口

API	接口	用途
DeFi API	POST /api/v1/defi/data/investment/list	发现 investmentId
DeFi API	POST /api/v1/defi/data/investment/detail	查看投资品详情
DeFi API	POST /api/v1/defi/data/protocol/list	为 REWARD_PROTOCOL 发现 defiProtocolId
DeFi API	POST /api/v1/defi/data/position/list	为 REDEMPTION 找 redemptionId
DeFi API	POST /api/v1/defi/transaction/deposit	构建存入 / 质押交易
DeFi API	POST /api/v1/defi/transaction/redeem	构建赎回 / 解质押交易
DeFi API	POST /api/v1/defi/transaction/lp-add	构建添加流动性交易
DeFi API	POST /api/v1/defi/transaction/lp-add/calculate	LP 添加前算配对额
DeFi API	POST /api/v1/defi/transaction/lp-remove	构建移除流动性交易
DeFi API	POST /api/v1/defi/transaction/claim	构建领取 / 赎回交易
Transaction API	POST /api/v1/dex/pre-transaction/broadcast-transaction	广播已签名的授权或主交易
Wallet API	GET /api/v1/dex/post-transaction/transaction-detail-by-txhash	查询 pending / success / fail 状态