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
| 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 |
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 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