DeBank API integration

DeBank API Integration

DeBank aggregates DeFi portfolios from 100+ protocols and 30+ chains. Instead of independently indexing positions in Aave, Uniswap, Compound and two dozen other protocols on Ethereum, Arbitrum, Polygon and BNB Chain simultaneously—one API call suffices. This is DeBank's value: ready-made aggregated portfolio view without custom indexing infrastructure.

DeBank API structure

DeBank OpenAPI provides several endpoint groups:

Token balances—/v1/user/token_list: all ERC-20 tokens on all supported chains with current USD price and position value.

Protocol positions—/v1/user/protocol: specific protocol and its positions (LP, staking, lending). /v1/user/complex_protocol_list—all protocols at once.

Transaction history—/v1/user/history_list with pagination.

NFT—/v1/user/nft_list.

const headers = { AccessKey: process.env.DEBANK_API_KEY }

// All user tokens on all chains
const tokens = await axios.get(
  `https://pro-openapi.debank.com/v1/user/all_token_list?id=${userAddress}&is_all=true`,
  { headers }
)

// Positions in specific protocol
const aavePositions = await axios.get(
  `https://pro-openapi.debank.com/v1/user/protocol?id=${userAddress}&protocol_id=aave3`,
  { headers }
)

Data model: what API returns

Each token in response contains: chain (chain identifier), id (contract address), amount (quantity), price (current USD price), usd_value (sum). For LP positions and protocol positions structure is more complex—nested objects with detail_types describing position type (lending, staking, vesting, etc.).

Important nuance: DeBank returns price: 0 for tokens without liquidity or below price threshold. Don't interpret this as error—normal for tail tokens.

Rate limiting and caching

DeBank Pro API has request rate limits per second. For applications with many users—mandatory server-side caching. Balance data changes rarely relative to RPC request time. Cache with TTL 60-300 seconds suits most use-cases.

Pattern: when requesting user data—return cached data immediately, run background update. User sees fresh data on next request.

async function getUserPortfolio(address: string) {
  const cacheKey = `portfolio:${address}`
  const cached = await redis.get(cacheKey)
  
  if (cached) {
    // Run background update
    updateInBackground(address, cacheKey)
    return JSON.parse(cached)
  }
  
  const fresh = await fetchFromDeBank(address)
  await redis.setex(cacheKey, 120, JSON.stringify(fresh))
  return fresh
}

Error handling and fallback

DeBank API—external service, it becomes unavailable. Application must correctly handle 503, 429 (rate limit) and timeout. On timeout—return cached data with mark about last update time, not show empty screen.

For critical functions (e.g., calculating collateral ratio for credit product)—don't rely only on DeBank. Backup channel: direct RPC calls to contracts via wagmi/viem for most important positions.

Timeline estimates

Basic DeBank API integration (tokens + protocol positions + history)—1-2 days. With caching, error handling and portfolio UI components—up to 5 days.

Cost calculated individually.