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. The rent / priority-fee fields are null on EVM chains and only populated on Solana. 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.

Solana preview notes

A Solana-specific point to surface to the user before signing:

• Rent — receiving a token on Solana for the first time opens an associated token account (ATA), which charges a rent deposit (the most common rent source — not just new stake accounts or LP positions). The rent is paid in SOL from the payer's balance, roughly 0.002 SOL per account, and is unrelated to the received token amount. The preview surfaces it as estimatedNetworkFee.rentFeeAmount (in SOL) / rentFeeValueUsd, alongside priorityFeeAmount. Closing the account later refunds the rent — except for some accounts created when opening an LP position, whose rent is non-refundable. Show this fee to the user before signing.

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. Delays are configured in seconds server-side and rounded up to whole days when surfaced, so a 2d4h cooldown returns 3.

Protocols with a waiting period in this release:

• EVM: Lista (helio), Aster (astherus), and others.
• Solana: every protocol below redeems in two steps (/redeem → cooldown → /claim REDEMPTION). Typical waits — order of magnitude only; always use the returned redeemDelayDays:

Protocol	Typical redeemDelayDays
sol_staking (native staking)	2–3 days
marinadefinance liquid / native	2–4 days / 2–3 days
renzo (Solana)	3–5 days
solayer	2–3 days
jupiter jupSOL / Stake JUP	2 days / 7 days
fragmetric	2–30 days, by fund
jito	2–3 days

The per-protocol redeem/claim handle differs — see Solana async redemption.

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 chains

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. EVM is one of two supported chain families in this release — see Solana chains below for the other.

BNB Smart Chain is an EIP-1559 chain, so build responses populate maxFeePerGas + maxPriorityFeePerGas and leave gasPrice null on BSC. Other EVM chains may populate either set — use the 1559 fields when present; fall back to gasPrice when it carries a value. 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 EIP-1559 chains)
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  # BNB Smart Chain; 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.

Solana chains

For Solana (binanceChainId = "CT_501"), a build response's dataList is always exactly one item — there is no APPROVE (Solana has no ERC-20 allowance concept). That item carries a base64-serialized wire transaction in data; the compute-budget fee is injected server-side for every action (do not add ComputeBudget / priority-fee yourself). to and value are null. Deserialize data, sign your fee-payer slot, re-serialize to base64, and broadcast. The fee-payer is account_keys[0] — the only slot you sign.

DefiCallDataItem field	Solana signing interpretation
from	base58 fee-payer public key (the user's signer)
to / value	null — Solana encodes the target program inside the wire tx
data	base64-serialized wire transaction (fee injected for all)
gasLimit	estimated compute-unit consumption (on-chain limit ~1.2×)
gasPrice	per-compute-unit fee in micro-lamports (already set)
maxPriorityFeePerGas / maxFeePerGas	null — Solana uses the Solana fee model, not EIP-1559

Solana transactions reference a recent blockhash that expires in roughly 30 seconds. Sign and broadcast the transaction as soon as it is built. If the blockhash expires before broadcast, rebuild the calldata and try again.

Python example: sign the Solana dataList item

Install a Solana signing library (the example uses solders, the Rust-backed types used by solana-py):

Code
pip install solders

The private key stays local and is never sent to Binance Web3 API. build_response is the JSON response from a build endpoint. The Solana dataList has one item; deserialize it, sign your fee-payer slot (account_keys[0]), and re-serialize.

Code
import base64
import os

from solders.keypair import Keypair
from solders.signature import Signature
from solders.transaction import VersionedTransaction

# The Solana private key must be base58. If it is hex, use Keypair.from_bytes(bytes.fromhex(...))
# instead; if it is a 32-byte seed, use Keypair.from_seed(...).
keypair = Keypair.from_base58_string(os.environ["WALLET_PRIVATE_KEY_B58"])

item = build_response["data"]["dataList"][0]  # Solana: always exactly one item, never APPROVE

# 1. Deserialize the base64 wire transaction from `data`. VersionedTransaction.from_bytes accepts
#    both legacy and v0 wire formats.
wire_tx = VersionedTransaction.from_bytes(base64.b64decode(item["data"]))

# 2. Confirm the fee-payer is account_keys[0] and matches your wallet.
fee_payer_pubkey = wire_tx.message.account_keys[0]
if str(fee_payer_pubkey) != str(keypair.pubkey()):
    raise ValueError("The wire transaction fee-payer does not match the signing wallet")

# 3. Get the message bytes to sign. `to_bytes_versioned` works for both legacy and v0 wire
#    formats (it includes the version prefix byte that `bytes(message)` omits for v0 — using
#    `bytes(message)` on a v0 transaction like kamino produces an invalid signature).
from solders.message import to_bytes_versioned
message_bytes = to_bytes_versioned(wire_tx.message)

# 4. Sign the message and fill the fee-payer slot (index 0). Populate keeps every other signature
#    slot as-is, so any non-fee-payer slot the service already filled is preserved.
signatures = list(wire_tx.signatures)
signatures[0] = Signature.from_bytes(bytes(keypair.sign_message(message_bytes)))
signed_tx = VersionedTransaction.populate(wire_tx.message, signatures)

# 5. Re-serialize to base64 and broadcast via the Transaction API.
signed_b64 = base64.b64encode(bytes(signed_tx)).decode()
broadcast_and_wait_sol(signed_b64)  # POST /broadcast-transaction with binanceChainId="CT_501"

The example signs only the fee-payer slot. 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 chains: raw signed transaction, 0x-prefixed hex. Solana: base64.
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 (EVM only — Solana dataList has a single item and no APPROVE). 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
  }'

Sample Broadcast Call (Solana)

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": "CT_501",
    "address": "5vUt9pxBK9KaaHm19okrwSuP2vUU71Nm7ScsBiSqsW1s",
    "signedTransaction": "AhYKAA1n...base64-wire-transaction...=="
  }'

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. For Solana, pass binanceChainId=CT_501 and the base58 transaction signature as txHash.

Calldata Validity & Approvals

• Calldata has no server-side expiry on EVM chains — 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 are two exceptions: liquidity-management transactions (lp-add, lp-remove) embed a deadline parameter in the calldata — build time + 20 minutes — enforced on-chain: past that timestamp the transaction is not rejected at the API layer but reverts after broadcast (e.g. ExpiredDeadline), surfacing as txStatus=fail when polling; so if more than 20 minutes have elapsed before signing, rebuild the calldata. lp-add/calculate builds no calldata and has no on-chain timeout, but its pool/tick snapshot ages just as fast — recalculate before building; and on Solana, the wire transaction references a recent blockhash that expires in roughly 30 seconds, so sign and broadcast it as soon as it is built; if it expires before broadcast, rebuild the calldata.
• 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, and always for Solana given the blockhash window).
• APPROVE is an EVM-only, 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. Solana has no ERC-20 allowance concept, so its dataList is always a single item with no APPROVE.

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 — EVM (Lista/Aster/Solv) and Solana ticket protocols (renzo, marinadefinance liquid, jito, solayer, fragmetric, jupiter Stake JUP); investmentId + stakeAccounts — Solana native staking (sol_staking) and Jupiter jupSOL (claimed under sol_staking, see the table below)

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.

Solana async redemption (two-step)

Several Solana protocols redeem asynchronously: the /redeem call deactivates / enqueues a withdrawal, and the funds become claimable via /claim REDEMPTION after a cooldown. The cooldown varies by protocol (2 to 30 days — see redeem waiting period); always take it from the redeemDelayDays returned by the redeem response. The field you pass to identify the position differs by protocol:

Protocol (redeem → claim)	redeem identifies the position with	claim REDEMPTION identifies with	Where the claim handle comes from
sol_staking (native staking)	stakeAccounts (deactivates the whole stake account; token/ratio ignored)	stakeAccounts (same address)	the stake account address you passed to redeem
jupiter jupSOL (stake_sol)	token / ratio (SOL amount; minimum 1 SOL; redeem mints + deactivates a new stake account)	stakeAccounts (the stake account the redeem created)	position/list positionDetail.userStakeAccount under sol_staking (the stake account also equals redemptionId); claim works with either the sol_staking or the jupSOL investmentId + stakeAccounts
jupiter Stake JUP (stake_jup)	token / ratio	redemptionId	position/list positionDetail.redemptionId (only after unlockTimeReached = true)
renzo	token / ratio (burns VRT)	redemptionId	position/list positionDetail.redemptionId (only after unlockTimeReached = true)
marinadefinance (liquid)	token / ratio	redemptionId	position/list positionDetail.redemptionId (the delayed-unstake ticket)
jito	token / ratio	redemptionId	position/list positionDetail.redemptionId (the stake account the redeem created)
solayer (sSOL)	token / ratio	redemptionId	position/list positionDetail.redemptionId (the stake account the redeem created; same mechanism as jito)
fragmetric	token / ratio (locks the fragAsset in a withdrawal request)	redemptionId	position/list positionDetail.redemptionId (the withdrawal request_id; claimable once its batch is processed)

Notes:

• For sol_staking and jupiter jupSOL, stakeAccounts makes redemptionId optional (no redemption record). This release supports one stake account per call (stakeAccounts length at most 1).
• jupiter jupSOL is a cross-protocol flow: the redeem burns jupSOL and creates a native stake account; the subsequent claim is a native Stake.Withdraw. The claim handle (userStakeAccount / redemptionId) appears under sol_staking in the position list (not under jupiter); claim with either the sol_staking or the jupSOL investmentId, together with stakeAccounts.
• After redeem, poll position/list with forceRefresh=true until the claim handle (userStakeAccount / redemptionId) appears and unlockTimeReached = true; then call /claim.
• marinadefinance native redeem has no claim request field — the withdrawable exit account is discovered on-chain by the service at claim time.
• Instant-redeem protocols (kamino, jupiter lend_borrow_supply / jlp) have no REDEMPTION claim step — funds settle in the same transaction.
• A sol_staking position entry may also carry a redemptionId equal to the stake account address, but claim REDEMPTION for native staking takes it in stakeAccounts — passing it as redemptionId is rejected with 40453.
• Do not modify the wire transaction after signing the fee-payer slot. The compute-budget fee is already injected server-side for every action, so adding ComputeBudget / priority-fee instructions yourself is unnecessary and will break the transaction. Re-signing a slot the service already filled invalidates the pre-signed signature and the transaction fails on-chain. Some builds carry two signature slots: renzo redeem (base slot pre-signed server-side) and Raydium / Orca CLMM new-position lp-add (the position-NFT mint slot pre-signed). For these you still sign only your fee-payer slot; the pre-signed slot is preserved by populate.

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–40488)	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); 40488 Solana SPL stake pool redeem failed (jito / jupSOL). 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.
Solana tx expired before broadcast	Solana wire tx blockhash expires in ~30s. If broadcast fails after the blockhash expired, re-build the calldata — do not retry the old dataList. See Solana chains.
Address / chain format mismatch (40001)	An EVM 0x-hex address passed for a Solana (CT_501) investment, or a base58 Solana address passed for an EVM investment, is rejected with 40001. Match the address format to the chain.

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