Skip to main content

Get User Positions

POST /positions Retrieve all DeFi positions for a wallet address, including vault balances and USDC balance.

Request

curl -X POST "https://api.darex.com/api/v1/positions" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "chainId": 8453
  }'

Request Body

ParameterTypeRequiredDescription
addressstringYesThe wallet address to query positions for
chainIdnumberNoFilter by chain ID. If not provided, returns positions from the default chain

Response

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "chainId": 8453,
  "usdcBalance": "1000.00",
  "usdcBalanceRaw": "1000000000",
  "positions": [
    {
      "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
      "protocol": "Aave",
      "symbol": "USDC",
      "yieldTokenSymbol": "aUSDC",
      "balance": "500.00",
      "balanceRaw": "500000000",
      "decimals": 6,
      "currentApy": 5.2,
      "tvl": 1250000000,
      "yieldTokenAddress": "0x...",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    },
    {
      "instrumentId": "0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc",
      "protocol": "Compound",
      "symbol": "USDC",
      "yieldTokenSymbol": "cUSDC",
      "balance": "250.00",
      "balanceRaw": "250000000",
      "decimals": 6,
      "currentApy": 4.8,
      "tvl": 980000000,
      "yieldTokenAddress": "0x...",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  ]
}

Response Fields

FieldTypeDescription
addressstringThe queried wallet address
chainIdnumberThe chain ID
usdcBalancestringFormatted USDC balance
usdcBalanceRawstringRaw USDC balance in smallest units
positionsarrayArray of vault positions

Position Object

FieldTypeDescription
instrumentIdstringThe instrument identifier
protocolstringProtocol name (Aave, Compound, Morpho, Moonwell)
symbolstringUnderlying token symbol
yieldTokenSymbolstringYield-bearing token symbol (aUSDC, cUSDC, etc.)
balancestringFormatted balance
balanceRawstringRaw balance in smallest units
decimalsnumberToken decimals
currentApynumberCurrent APY percentage
tvlnumberTotal value locked in USD
yieldTokenAddressstringYield token contract address
tokenAddressstringUnderlying token contract address

TypeScript Example

const BASE_URL = 'https://api.darex.com/api/v1';

interface Position {
  instrumentId: string;
  protocol: string;
  symbol: string;
  yieldTokenSymbol?: string;
  balance: string;
  balanceRaw: string;
  decimals: number;
  currentApy?: number;
  tvl?: number;
  yieldTokenAddress: string;
  tokenAddress: string;
}

interface PositionsResponse {
  address: string;
  chainId: number;
  usdcBalance: string;
  usdcBalanceRaw: string;
  positions: Position[];
}

async function getPositions(
  address: string,
  chainId?: number
): Promise<PositionsResponse> {
  const response = await fetch(`${BASE_URL}/positions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ address, chainId }),
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch positions: ${response.status}`);
  }

  return response.json();
}

// Usage
const positions = await getPositions(
  '0x1234567890abcdef1234567890abcdef12345678',
  8453
);

console.log(`USDC Balance: ${positions.usdcBalance}`);
console.log(`Active positions: ${positions.positions.length}`);

positions.positions.forEach((pos) => {
  console.log(`${pos.protocol} ${pos.symbol}: ${pos.balance} (${pos.currentApy}% APY)`);
});

Next Steps