Positions API - 1tx Documentation

Get User Positions

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

Request

curl "https://api.1tx.fi/api/v1/positions?address=0x1234567890abcdef1234567890abcdef12345678&chainId=8453"

Query Parameters

Parameter	Type	Required	Description
`address`	string	Yes	The wallet address to query positions for
`chainId`	number	No	Filter by chain ID. If not provided, positions are aggregated across all supported chains and the response uses `chainId: 0`

The legacy POST /positions form with the same fields in a JSON body remains available for backward compatibility. New integrations should use GET.

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,
      "shareBalance": "500.00",
      "shareBalanceRaw": "500000000",
      "shareDecimals": 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,
      "shareBalance": "250.00",
      "shareBalanceRaw": "250000000",
      "shareDecimals": 6,
      "currentApy": 4.8,
      "tvl": 980000000,
      "yieldTokenAddress": "0x...",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    }
  ]
}

Response Fields

Field	Type	Description
`address`	string	The queried wallet address
`chainId`	number	The chain ID
`usdcBalance`	string	Formatted USDC balance
`usdcBalanceRaw`	string	Raw USDC balance in smallest units
`positions`	array	Array of vault positions

Position Object

Field	Type	Description
`instrumentId`	string	The instrument identifier
`protocol`	string	Protocol name (Aave, Compound, Morpho, Euler, Fluid)
`symbol`	string	Underlying token symbol
`yieldTokenSymbol`	string	Yield-bearing token symbol (aUSDC, cUSDC, etc.)
`balance`	string	Formatted underlying asset value
`balanceRaw`	string	Raw underlying asset value in smallest units
`decimals`	number	Underlying asset decimals
`shareBalance`	string	Optional formatted yield-token balance. Pass this as `yieldTokenAmount` to `/transactions/sell`
`shareBalanceRaw`	string	Optional raw yield-token balance in the yield token’s smallest units
`shareDecimals`	number	Optional yield-token decimals
`currentApy`	number	Current APY percentage
`tvl`	number	Total value locked in USD
`yieldTokenAddress`	string	Yield token contract address
`tokenAddress`	string	Underlying token contract address
`chainId`	number	Chain ID for this position
`description`	string	Optional instrument description

For ERC-4626 vaults such as Morpho, Euler, and Fluid, balance is the underlying asset value while shareBalance is the vault-share amount. Use shareBalance when building sell transactions.

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;
  shareBalance?: string;
  shareBalanceRaw?: string;
  shareDecimals?: 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 query = new URLSearchParams({ address });
  if (chainId !== undefined) query.set('chainId', String(chainId));
  const response = await fetch(`${BASE_URL}/positions?${query}`);

  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