Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.1tx.fi/llms.txt

Use this file to discover all available pages before exploring further.

​
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.1tx.fi/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, positions are aggregated across all supported chains and the response uses chainId: 0

​
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, Euler, Fluid)
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
chainIdnumberChain ID for this position
descriptionstringOptional instrument description

​
TypeScript Example

const BASE_URL = 'https://api.1tx.fi/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

Instruments API

Query DeFi instruments

Quotes API

Get swap quotes for deposits