Pools API

Endpoints for listing liquidity pools, viewing pool details, charting, retrieving user LP positions, and simulating impermanent loss.

List Pools

GET /api/pools

Returns a paginated list of liquidity pools.

Query Parameters:

Parameter	Type	Description
chain_id	integer	Target chain ID
sort_by	string	Sort field: tvl, volume, apr (default: tvl)
limit	integer	Number of results (default: 50)
offset	integer	Pagination offset (default: 0)

Response:

{
  "success": true,
  "data": [
    {
      "address": "0x...",
      "token0": { "address": "0x...", "symbol": "WETH" },
      "token1": { "address": "0x...", "symbol": "USDC" },
      "fee_tier": 3000,
      "tvl_usd": 2450000.00,
      "volume_24h": 890000.00,
      "apr": 18.45
    }
  ],
  "total": 64
}

Get Pool Detail

GET /api/pools/{address}

Returns detailed information for a single pool.

Path Parameters:

Parameter	Type	Description
address	string	Pool contract address

Response:

{
  "success": true,
  "data": {
    "address": "0x...",
    "token0": { "address": "0x...", "symbol": "WETH", "decimals": 18 },
    "token1": { "address": "0x...", "symbol": "USDC", "decimals": 6 },
    "fee_tier": 3000,
    "tvl_usd": 2450000.00,
    "volume_24h": 890000.00,
    "volume_7d": 5230000.00,
    "apr": 18.45,
    "reserve0": "750.234",
    "reserve1": "2430567.89",
    "total_supply": "1234567890000000000000"
  }
}

Pool Chart Data

GET /api/pools/{address}/chart

Returns time-series chart data for a pool (TVL, volume, or fees over time).

Path Parameters:

Parameter	Type	Description
address	string	Pool contract address

Query Parameters:

Parameter	Type	Description
metric	string	Data series: tvl, volume, fees
interval	string	Time interval: 1h, 1d, 1w
from	integer	Start timestamp (Unix seconds)
to	integer	End timestamp (Unix seconds)

Response:

{
  "success": true,
  "data": [
    { "timestamp": 1700000000, "value": 2430000.00 },
    { "timestamp": 1700003600, "value": 2445000.00 }
  ]
}

User LP Positions

GET /api/pools/user/{wallet}

Returns all LP positions held by a wallet address.

Path Parameters:

Parameter	Type	Description
wallet	string	User wallet address

Query Parameters:

Parameter	Type	Description
chain_id	integer	Target chain ID

Response:

{
  "success": true,
  "data": [
    {
      "pool_address": "0x...",
      "token0_symbol": "WETH",
      "token1_symbol": "USDC",
      "lp_balance": "1234567890000000000",
      "share_percent": 0.85,
      "value_usd": 21500.00,
      "token0_amount": "3.25",
      "token1_amount": "10540.00"
    }
  ]
}

Impermanent Loss Simulation

GET /api/il/simulate

Simulates impermanent loss for a given price change scenario.

Query Parameters:

Parameter	Type	Description
price_change_percent	float	Percentage price change of asset A relative to asset B
initial_value_usd	float	Initial position value in USD

Response:

{
  "success": true,
  "data": {
    "price_change_percent": 50.0,
    "il_percent": 2.02,
    "hold_value_usd": 12500.00,
    "lp_value_usd": 12247.45,
    "loss_usd": 252.55
  }
}