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

# Positions API

> Query user positions and balances

## Get User Positions

<span style={{color: '#3B82F6', fontWeight: 'bold'}}>POST</span> `/positions`

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

### Request

```bash theme={null}
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

```json theme={null}
{
  "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                                                                 |

<Note>
  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.
</Note>

***

## TypeScript Example

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Instruments API" icon="fingerprint" href="/api-reference/endpoints/instruments">
    Query DeFi instruments
  </Card>

  <Card title="Quotes API" icon="calculator" href="/api-reference/endpoints/quotes">
    Get swap quotes for deposits
  </Card>
</CardGroup>