DeFi API

Integration Flow

Copy page

A complete DeFi transaction integration spans three Binance Web3 APIs:

• DeFi API discovers the investment and builds the unsigned transaction calldata.
• Transaction API broadcasts the transaction after your wallet signs it.
• Wallet API reads the resulting on-chain transaction and its status.

The DeFi API and Transaction API never hold your private key. They only return unsigned transaction data or relay a transaction that you have already signed. Keep signing operations in your own wallet or signer.

Every request to these APIs is authenticated with your API Key and Secret Key. See Authentication for the required headers and HMAC signing details.

End-to-End Flow

Code
0. Authenticate every API request with API Key + Secret Key
1. (Data)   POST /api/v1/defi/data/investment/list  → pick investmentId (and defiProtocolId)
2. (Build)  POST /api/v1/defi/transaction/deposit   → receive dataList (APPROVE first, then the main tx)
                                                    + optional preview (simulate=true)
3. (Preview) Optionally set simulate=true to read balanceChange / healthFactor before signing
4. Sign each dataList item locally with the user's wallet (APPROVE first if present, then the main tx)
5. (Broadcast) POST /api/v1/dex/pre-transaction/broadcast-transaction per signed tx (Transaction API)
6. (Status)  GET /api/v1/dex/post-transaction/transaction-detail-by-txhash → poll txStatus

Steps 1, 2, 3 use the DeFi API; steps 5 and 6 use the Transaction API and Wallet API respectively. The build endpoint you call in step 2 depends on the action: /deposit, /redeem, /lp-add, /lp-remove, or /claim (plus the pure-computation /lp-add/calculate before an LP add).

Step 0 — Authenticate API Requests

All requests in this guide are authenticated. Use the exact URL path, including /build, when calculating X-OC-SIGN; the API request signature is separate from the on-chain wallet signature. See Authentication for the required headers, HMAC-SHA256 pre-hash, timestamp window, and rate limits.

Step 1 — Discover the Investment

Every build request is keyed by investmentId, which is chain-agnostic (the service resolves the chain from it — you do not pass binanceChainId, except for one claim case noted below).

• Use POST /api/v1/defi/data/investment/list or /investment/detail to find the investmentId for the pool / vault / strategy the user wants.
• For claim with claimType=REWARD_PROTOCOL, use POST /api/v1/defi/data/protocol/list to find the defiProtocolId (e.g. pancakeswap3).
• For claim with claimType=REDEMPTION, the redemptionId comes from the user's position/list response (redemptionId field on pending-redemption positions).

Step 2 — Build the Transaction

Call the build endpoint with address, investmentId, the action-specific fields, and optionally simulate=true. The response data is a DefiTxResponse: an ordered dataList of DefiCallDataItem (APPROVE first when needed, then the main action) and, when simulate=true, a preview object.

Sample build call — 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
}

Sign and broadcast every dataList item, in order. If callDataType=APPROVE is present, it must be signed, broadcast, and confirmed on-chain before the main action — otherwise the main transaction reverts for lack of allowance.

Step 3 — Preview Before Signing (optional)

Set simulate=true on any build request to receive data.preview without changing on-chain state. The preview tells you whether the action is expected to succeed, the projected balanceChange (positive = received, negative = spent), the estimated network fee (feeAndContract), and — for lending protocols — the healthFactor change. Use it to confirm slippage, gas, and health-factor impact before proceeding with signing.

preview shape:

Field	Meaning
success	Whether the simulated tx is expected to land. false means the action would revert on-chain — do not proceed with signing. When success=false carries a non-blank errorMessage (a revert), the request returns the revert error code 40484 / 40485 instead of the preview body (see Error Codes).
balanceChange	Signed token deltas (amount positive = received, negative = spent). Empty array when the simulation produces no deltas (e.g. nothing to claim).
feeAndContract.estimatedNetworkFee	Estimated gas cost — amount / tokenSymbol (the fee-paying native coin) / valueUsd, plus optional rentFeeAmount / rentFeeValueUsd / priorityFeeAmount. Fields are null when the simulation failed before fee estimation.
feeAndContract.interactWith.address	The contract the action interacts with.
healthFactor	Lending health-factor before / after. null for non-lending protocols or when unavailable.
warnings	Non-blocking risk warnings; empty when none.
errorMessage	When success=false and non-blank, the simulated tx would revert — the service maps it to a revert error code (40485 for "exceeds your current position", 40484 otherwise) and the request returns that code instead of this preview body.

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
  }'

A successful simulation returns success: true with the projected deltas, the estimated fee, and — for lending protocols — the health-factor change:

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 entries are signed (amount positive = received, negative = spent). healthFactor and warnings are populated only for lending protocols; non-lending actions return healthFactor: null and an empty warnings array.

When the simulated tx would revert, the request returns an error code (HTTP 200, non-zero code) instead of a 200 with preview.success=false. 40485 means the redeem amount exceeds the current position; 40484 covers any other revert — read msg for the original revert reason (e.g. the amount is below the protocol minimum) and do not prompt the user to sign:

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

Revert codes (40484 / 40485) are returned only when simulate=true. The mapping from a revert message to a code is substring containment and is server-side configurable; an unmapped revert falls back to 40484. See Error Codes.

Redeem waiting period

A /transaction/redeem response also carries data.redeemDelayDays — the redeem waiting period as a [min, max] day pair of decimal strings:

redeemDelayDays	Meaning
[] (empty)	Instant, no waiting period
["7","7"]	Fixed 7 days
["7","10"]	7–10 days

The wait starts after the redeem transaction is confirmed on-chain. redeemDelayDays is null on the other build endpoints. Protocols with a waiting period in this release include Lista (helio) and Aster (astherus).

Step 4 — Sign Locally

Use the wallet that owns each dataList[i].from. The Binance Web3 API must never receive a private key or seed phrase.

EVM chain (BSC)

Map each DefiCallDataItem to an EIP-1559 or legacy transaction and sign it. The resulting raw signed transaction is a hex string beginning with 0x.

This release is BSC only, and BSC is an EIP-1559 chain, so build responses populate maxFeePerGas + maxPriorityFeePerGas and leave gasPrice null. Use the 1559 fields when present; fall back to gasPrice only for legacy (non-1559) chains in later releases. value is a hex string; all gas fields are decimal strings.

DefiCallDataItem field	Signed transaction field
from	Signer / sender
to	Transaction recipient
data	ABI-encoded calldata
value	Native-token value in wei (hex)
gasLimit	Gas limit
gasPrice	Legacy gas price in wei (null on BSC)
maxPriorityFeePerGas	EIP-1559 priority fee in wei
maxFeePerGas	EIP-1559 max fee per gas

Python example: sign every dataList item

Install the signing and RPC libraries:

Code
pip install eth-account web3

The private key stays local and is never sent to Binance Web3 API. build_response is the JSON response from a build endpoint. Sign each dataList item in order; broadcast and confirm the APPROVE item before broadcasting the main action.

Code
import os

from eth_account import Account
from web3 import Web3

CHAIN_ID = 56  # BSC; use the chain ID matching the investment
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):
    """Convert decimal or 0x-prefixed API values to integers; fall back on None."""
    if value is None:
        return default
    return int(value, 0) if isinstance(value, str) else int(value)


def raw_hex(signed):
    """Return the signed transaction as a 0x-prefixed hex string across 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). The build response returns maxFeePerGas alongside
        # maxPriorityFeePerGas; use it directly instead of falling back to gasPrice.
        transaction["maxFeePerGas"] = as_int(gas_price)
        transaction["maxPriorityFeePerGas"] = as_int(max_priority_fee_per_gas)
    else:
        # Legacy. gasPrice must not be 0 — if the API omitted it, estimate from the node.
        transaction["gasPrice"] = as_int(gas_price, default=None) or w3.eth.gas_price

    return raw_hex(account.sign_transaction(transaction))


# Sign and broadcast ONE item at a time, in order. Do NOT sign the whole list
# up front: every item needs a fresh nonce, and an APPROVE must be confirmed
# on-chain before the main action is submitted (otherwise it reverts for lack
# of allowance). `broadcast_and_wait` is your wrapper that POSTs signedTransaction
# to /broadcast-transaction and polls the Wallet API until the tx is finalized.
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("A dataList item sender does not match the signing wallet")

    signed_tx = sign_evm_transaction(
        nonce=base_nonce + i,  # +i so APPROVE and the main action do not collide
        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)  # raises on broadcast/finalization failure
    # Only after tx_hash is confirmed does the loop sign the next item.

The helper builds an EIP-1559 (type-2) transaction when maxPriorityFeePerGas is present, using the build response's maxFeePerGas as the fee cap; otherwise it falls back to a legacy transaction and estimates gasPrice from the node when the API omitted it. Nonces are base_nonce + i so the APPROVE and the main action get distinct nonces — but you still must wait for each broadcast to confirm before signing the next item, since the main action requires the APPROVE to be mined first. The API request HMAC signature and the on-chain wallet signature are independent.

Step 5 — Broadcast the Signed Transaction

Call the Transaction API POST /api/v1/dex/pre-transaction/broadcast-transaction for each signed dataList item:

Field	Value
binanceChainId	The chain matching the investmentId
signedTransaction	EVM raw signed hex
address	The user's wallet address (the from of the item)

Broadcast the APPROVE item first and wait for its confirmation before broadcasting the main action. A successful response returns data.txHash — keep it for the next step.

Sample Broadcast Call (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
  }'

The X-OC-SIGN value above is the Binance Web3 API request signature. It is unrelated to the on-chain wallet signature encoded in signedTransaction.

Step 6 — Query Transaction Details and Poll Status

Use the txHash returned by the broadcast response with the Wallet API endpoint 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'

The response's data array contains the transaction detail. Inspect data[].txStatus:

txStatus	Meaning	Client action
pending	The transaction has been broadcast but is not finalized	Poll again with backoff
success	The transaction succeeded on-chain	Mark as confirmed
fail	The transaction was mined but failed	Mark as failed; inspect gas, method, and transfer details

Immediately after broadcast, the endpoint may return an empty data array while indexing catches up — retry with backoff. Always pass both binanceChainId and the exact txHash; the APPROVE and the main action have different hashes.

Calldata Validity & Approvals

• Calldata has no server-side expiry — the returned dataList items are static on-chain transaction data, not server-issued quotes; the build endpoint does not assign a TTL and the same dataList can be re-signed and re-broadcast until it lands on-chain. There is one exception: liquidity-management actions (lp-add, lp-add/calculate, lp-remove) carry a 20-minute server-side timeout — the underlying position/range snapshot is stale after 20 minutes, so rebuild the calldata if more than 20 minutes have elapsed before signing.
• Re-build rather than cache — gas price and the position state move between build and sign, so call the build endpoint again if significant time has elapsed since the build response (especially before LP actions). The build is cheap relative to a reverted on-chain tx.
• APPROVE is an unlimited allowance — when an APPROVE item is present, it approves the maximum amount (type(uint256).max) to the spender contract returned in that item's to. This is a one-time, per-token, per-spender approval; subsequent actions on the same token/spender reuse it (the build returns [DEPOSIT] only, no APPROVE, when the allowance is already sufficient). If your compliance posture forbids unlimited approvals, ensure the signer is aware before signing the APPROVE item, or revoke the allowance after the main action lands.

LP Add / Remove Specifics

• Tick range — pick exactly one source:

  • nftId: append to an existing position, reusing its range
  • priceRange: percentage band
  • tickLower + tickUpper: explicit raw int24 pair

  Rules:

  • If more than one is supplied, only the highest-priority source is used and the others are silently ignored (priority: nftId > priceRange > explicit tick pair)
  • If none is supplied, the request is rejected
  • tickLower / tickUpper must be aligned to the pool's tickSpacing, otherwise the request is rejected

• Size the paired token first — when you only have one side, call POST /transaction/lp-add/calculate to get the paired token amount before /lp-add. This endpoint is pure computation — it does not touch the chain and does not deduct a fee.

• LP remove — keyed by nftId + ratio (range (0, 1]); no tokenList is needed, the per-token amounts are derived from the on-chain position.

Claim Specifics

claimType determines which companion fields are required:

claimType	Required fields
REWARD_PROTOCOL	defiProtocolId + binanceChainId
REWARD_INVESTMENT	investmentId
LP_FEE	investmentId + nftId
REDEMPTION	investmentId + redemptionId

binanceChainId is normally resolved from investmentId and any client value is ignored — except for REWARD_PROTOCOL with no investmentId, where the client must pass binanceChainId because it is the only chain signal. tokenAddressList optionally narrows the claim scope.

Field Mapping Across the Flow

Source	Next step
/data/investment/* → investmentId	Pass to the build endpoint
/data/protocol/list → defiProtocolId	Pass to /claim with claimType=REWARD_PROTOCOL
/data/position/list → redemptionId	Pass to /claim with claimType=REDEMPTION
/transaction/* → dataList[i]	Map each item to a local wallet transaction and sign it (in order)
/transaction/* (simulate=true) → preview	Inspect balanceChange / healthFactor before signing
signed dataList[i] → signedTransaction	POST to /broadcast-transaction
/broadcast-transaction → data.txHash	Pass to Wallet API transaction-detail-by-txhash
Wallet API → data[].txStatus	Determine the final transaction outcome (pending / success / fail)

Common Pitfalls

Pitfall	Fix
40102 Signature error	Include /build in the signed request path and sign the exact raw body; see Authentication.
DeFi build rejected (40450–40460, 40480–40485)	The code identifies the failure phase — branch on it, not on msg. 40480 insufficient balance → top up; 40457 no liquidity to remove; 40460 simulation failed; 40482 RPC error → retry; 40485 redeem amount exceeds position; 40484 other preview revert (read msg). 40459 is the catch-all — read msg. See Error Codes.
Main transaction reverts on broadcast	The APPROVE item must be broadcast and confirmed on-chain before the main action; do not skip or reorder it.
LP add rejected over ticks	tickLower / tickUpper must be raw int24 aligned to the pool's tickSpacing, or use priceRange instead.
Claim 40454 on field mismatch	Provide the fields required by the claimType (see the table above); REWARD_PROTOCOL needs binanceChainId.

Related Endpoints

API	Endpoint	Purpose
DeFi API	POST /api/v1/defi/data/investment/list	Discover investmentId
DeFi API	POST /api/v1/defi/data/investment/detail	Inspect an investment product
DeFi API	POST /api/v1/defi/data/protocol/list	Discover defiProtocolId for REWARD_PROTOCOL
DeFi API	POST /api/v1/defi/data/position/list	Find redemptionId for REDEMPTION
DeFi API	POST /api/v1/defi/transaction/deposit	Build a deposit / stake transaction
DeFi API	POST /api/v1/defi/transaction/redeem	Build a redeem / unstake transaction
DeFi API	POST /api/v1/defi/transaction/lp-add	Build an add-liquidity transaction
DeFi API	POST /api/v1/defi/transaction/lp-add/calculate	Size the paired token before an LP add
DeFi API	POST /api/v1/defi/transaction/lp-remove	Build a remove-liquidity transaction
DeFi API	POST /api/v1/defi/transaction/claim	Build a claim / redemption transaction
Transaction API	POST /api/v1/dex/pre-transaction/broadcast-transaction	Broadcast a signed approval or main transaction
Wallet API	GET /api/v1/dex/post-transaction/transaction-detail-by-txhash	Query pending / success / fail status