Introduction

Copy page

The DeFi API provides on-chain DeFi data services and transaction building capabilities, including user position queries, protocol and investment discovery with pagination, and calldata construction for deposit, redeem, liquidity, and claim operations. This release supports BNB Smart Chain (BSC); more chains and protocols will be added in upcoming releases.

Feature Overview

DeFi Data

Feature	Endpoint	Method	Description
Query Positions	/api/v1/defi/data/position/list	POST	Get DeFi positions for one or more wallet addresses on BSC
Protocol List	/api/v1/defi/data/protocol/list	POST	List supported DeFi protocols with pagination and filtering
Protocol Detail	/api/v1/defi/data/protocol/detail	POST	Get detailed information for a specific DeFi protocol
Investment List	/api/v1/defi/data/investment/list	POST	List available DeFi investment products
Investment Detail	/api/v1/defi/data/investment/detail	POST	Get detailed information for a specific investment product

DeFi Transaction

The transaction endpoints build unsigned DeFi calldata — they never hold your private key. Each response returns an ordered dataList (an ERC-20 APPROVE item first when needed, then the main action) for your wallet to sign and broadcast. Set simulate=true on any of the five transaction build endpoints (/deposit, /redeem, /lp-add, /lp-remove, /claim) to also receive a preview (projected balance change, estimated gas, and lending health-factor change) before broadcasting. See the Integration Flow for the end-to-end build → sign → broadcast → poll sequence.

Feature	Endpoint	Method	Description
Build Deposit	/api/v1/defi/transaction/deposit	POST	Build deposit / stake transaction calldata
Build Redeem	/api/v1/defi/transaction/redeem	POST	Build redeem / unstake transaction calldata
Add Liquidity	/api/v1/defi/transaction/lp-add	POST	Build add-liquidity transaction calldata
Calculate LP Amounts	/api/v1/defi/transaction/lp-add/calculate	POST	Calculate paired token amounts before adding liquidity
Remove Liquidity	/api/v1/defi/transaction/lp-remove	POST	Build remove-liquidity transaction calldata
Claim Rewards	/api/v1/defi/transaction/claim	POST	Build claim reward or redemption principal calldata

Path Layout

Data-query endpoints sit under /api/v1/defi/data/*; transaction-build endpoints sit under /api/v1/defi/transaction/*.

Coverage Scope

Support scope differs by endpoint group:

• Position queries cover a wider set of protocols (15 on BSC). Positions in protocols outside the transaction/investment list are display-only (no investmentIds, no transaction building).
• Protocol / investment data queries and transaction building are available only for the 10 protocols in the transaction/investment list.

See Supported Chains & Protocols for both lists and the difference.

Position Data Structure

POST /api/v1/defi/data/position/list returns positions in five nested layers:

Code
totalValue                        — total across ALL queried addresses
└─ addressList[]                  — one entry per queried address
   ├─ address, addressTotalValue  — the address and its total position value
   └─ protocolList[]              — per-protocol positions of this address
      ├─ binanceChainId, defiProtocolId, protocolTotalValue
      └─ poolList[]               — pools of this protocol the address holds
         ├─ bnPoolId, poolCa, poolType
         └─ positionCollectionList[]  — position groups under the pool
            ├─ positionCollectionId, positionCollectionTotalValue
            └─ positionList[]     — individual positions
               ├─ positionId, underlyingAssetName, investmentIds
               └─ tokenList       — token breakdown by role (supply/borrow/reward/farming_reward)

What a position collection is: a pool groups positions by their underlying asset. A single-asset pool (e.g. a Venus USDT supply) usually has one collection per asset; a multi-asset pool (e.g. a Uniswap V3 pool) can hold several collections. When in doubt, aggregate at the collection layer — positionCollectionTotalValue is the pre-computed total of everything under it.

Data Format Conventions

Unless noted otherwise, the DeFi Data endpoints follow these formatting rules:

Field type	Convention
APY	Two derived fields: apyBps (integer, basis points — 1 bps = 0.01%, e.g. 9963 = 99.63%) for sorting / comparing / filtering, and apyDisplay (pre-formatted string, e.g. "99.63%") for display — quote as-is, do not re-compute. The raw decimal apy is not returned.
TVL	Decimal strings, USD, raw precision from the data source (e.g. "1250000.5")
Value	Position values (totalValue, addressTotalValue, protocolTotalValue) are decimal strings, USD, raw precision from the data source
Amounts	Human-readable decimal strings (e.g. "1000.5"), not the token's smallest unit
Timestamps	Unix time in seconds across all endpoints (e.g. pool expiry, position unlockTime)
Native asset	Address 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee (40 es) represents the chain's native coin

Rate Limits

All DeFi API endpoints share a default rate limit of 5 QPS. When the limit is exceeded the gateway returns HTTP 429; reduce the request frequency and retry.