Liquidity Pools

The liquidity pool system allows you to provide liquidity to Uniswap V3 pools and earn trading fees. You can create new positions, add or remove liquidity, and collect fees. This guide covers all pool management operations.

Overview

The liquidity pool system provides:

Pool Discovery - View available liquidity pools
Create Positions - Create new liquidity positions
Manage Liquidity - Add or remove liquidity from positions
Collect Fees - Collect earned trading fees
Historical Data - View pool performance and price history

Prerequisites

Before managing liquidity pools, ensure you have:

Completed authentication and have a valid access token
Created a wallet
Have tokens to provide as liquidity

Get All Pools

Retrieve a list of all available liquidity pools.

Get all pools

curl -X GET https://api.example.com/api/pools \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Pools retrieved successfully",
  "data": [
    {
      "poolId": "137-0x...",
      "address": "0x...",
      "token0": {
        "symbol": "USDC",
        "address": "0x...",
        "decimals": 6
      },
      "token1": {
        "symbol": "ETH",
        "address": "0x...",
        "decimals": 18
      },
      "fee": 3000,
      "chain": {
        "id": 137,
        "name": "Polygon"
      }
    }
  ]
}

Get Pool by ID

Retrieve detailed information about a specific pool.

Get pool details

curl -X GET https://api.example.com/api/pools/chain/{chainId}/pool/{poolAddress} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Path Parameters:

chainId - Chain ID (e.g., 137 for Polygon)
poolAddress - Pool contract address

Response:

{
  "status": 200,
  "message": "Pool retrieved successfully",
  "data": {
    "pool": {
      "address": "0x...",
      "token0": {...},
      "token1": {...},
      "fee": 3000,
      "liquidity": "1000000000000000000",
      "sqrtPriceX96": "1000000000000000000",
      "tick": 0,
      "tokens": [...]
    }
  }
}

Note: Results are cached for 60 minutes.

Get Pool Historical Data

Retrieve historical data for a pool.

Get pool historical data

curl -X GET https://api.example.com/api/pools/chain/{chainId}/pool/{poolAddress}/historical-data \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Response:

{
  "status": 200,
  "message": "Pool historical data retrieved successfully",
  "data": {
    "volume": [...],
    "tvl": [...],
    "fees": [...]
  }
}

Get Pool Amounts

Calculate required token amounts for creating a liquidity position.

Get pool amounts

curl -X GET "https://api.example.com/api/pools/chain/{chainId}/pool/{poolAddress}/amounts?token0MaxAmount=1.0&token1MaxAmount=1.0&minPrice=0.0005&maxPrice=0.0006" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

Query Parameters:

token0MaxAmount - Maximum amount of token0 (humanized format, e.g., "1.0" for 1 token)
token1MaxAmount - Maximum amount of token1 (humanized format, e.g., "1.0" for 1 token)
minPrice - Minimum price for the position
maxPrice - Maximum price for the position

Response:

{
  "status": 200,
  "message": "Pool amounts retrieved successfully",
  "data": {
    "token0Amount": "1.0",
    "token1Amount": "0.5",
    "minPrice": "0.0005",
    "maxPrice": "0.0006"
  }
}

Create Liquidity Position

Create a new liquidity position in a pool.

Create liquidity position

curl -X POST https://api.example.com/api/pools/chain/{chainId}/pool/{poolAddress}/create \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "token0Amount": "1.0",
    "token1Amount": "0.5",
    "minPrice": "0.0005",
    "maxPrice": "0.0006"
  }'

Required Fields:

token0Amount - Amount of token0 to provide (humanized format, e.g., "1.0" for 1 token)
token1Amount - Amount of token1 to provide (humanized format, e.g., "0.5" for 0.5 token)
minPrice - Minimum price for the position (lower tick)
maxPrice - Maximum price for the position (upper tick)

Response:

{
  "status": 200,
  "message": "Liquidity pool created successfully",
  "data": {
    "operation": {
      "userOperationHash": "0x...",
      "tokenId": "12345"
    }
  }
}

Note: The transaction is signed automatically. You receive an NFT (tokenId) representing your position.

Increase Liquidity

Add more liquidity to an existing position.

Increase liquidity

curl -X POST https://api.example.com/api/pools/chain/{chainId}/pool/{poolAddress}/{tokenId}/increase-liquidity \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "token0Amount": "0.5",
    "token1Amount": "0.25"
  }'

Path Parameters:

chainId - Chain ID
poolAddress - Pool address
tokenId - NFT token ID of your position

Required Fields:

token0Amount - Additional amount of token0 (humanized format)
token1Amount - Additional amount of token1 (humanized format)

Response:

{
  "status": 200,
  "message": "Liquidity changed successfully",
  "data": {
    "operation": {
      "userOperationHash": "0x..."
    }
  }
}

Decrease Liquidity

Remove liquidity from an existing position.

Decrease liquidity

curl -X POST https://api.example.com/api/pools/chain/{chainId}/pool/{poolAddress}/{tokenId}/decrease-liquidity \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "percentage": "50"
  }'

Path Parameters:

chainId - Chain ID
poolAddress - Pool address
tokenId - NFT token ID of your position

Required Fields:

percentage - Percentage of liquidity to remove (0-100)

Response:

{
  "status": 200,
  "message": "Liquidity changed successfully",
  "data": {
    "operation": {
      "userOperationHash": "0x..."
    }
  }
}

Collect Fees

Collect earned trading fees from your position.

Collect fees

curl -X POST https://api.example.com/api/pools/chain/{chainId}/pool/{poolAddress}/{tokenId}/collect-fees \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "execute": true
  }'

Path Parameters:

chainId - Chain ID
poolAddress - Pool address
tokenId - NFT token ID of your position

Required Fields:

execute - Whether to execute the transaction immediately (true) or just get the operation (false)

Response:

{
  "status": 200,
  "message": "Fees collected successfully",
  "data": {
    "operation": {
      "userOperationHash": "0x..."
    }
  }
}

Note: If execute is true, the transaction is signed automatically. If false, you receive the operation hash to sign later.

Price Ranges

Liquidity positions use price ranges:

minPrice - Lower bound of the price range
maxPrice - Upper bound of the price range
Current Price - Current pool price (must be within your range to earn fees)

Important: You only earn fees when the current price is within your price range. If price moves outside your range, you stop earning fees.

Fee Tiers

Uniswap V3 pools have different fee tiers:

0.05% - Lowest fee tier (500)
0.3% - Standard fee tier (3000)
1% - Higher fee tier (10000)

Higher fee tiers typically have higher trading volume and more fees.

Error Handling

Pool Not Found

{
  "status": 404,
  "message": "Pool not found"
}

This error occurs when the pool doesn't exist.

Wallet Not Found

{
  "status": 404,
  "message": "Wallet not found"
}

This error occurs when you haven't created a wallet yet.

Invalid Percentage

{
  "status": 400,
  "message": "Percentage must be less than 100"
}

This error occurs when decreasing liquidity with a percentage greater than 100.

Token Amounts Required

{
  "status": 400,
  "message": "Token amounts are required"
}

This error occurs when increasing liquidity without providing token amounts.

Error Creating Pool

{
  "status": 500,
  "message": "Error creating liquidity pool"
}

This error occurs when there's an issue creating the position.

Error Signing Transaction

{
  "status": 500,
  "message": "Error signing transaction"
}

This error occurs when there's an issue signing the transaction.

Complete Flow Example

Here's a complete example of managing a liquidity position:

# 1. Get available pools
curl -X GET https://api.example.com/api/pools \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 2. Get pool details
curl -X GET https://api.example.com/api/pools/chain/137/pool/0x... \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 3. Calculate amounts
curl -X GET "https://api.example.com/api/pools/chain/137/pool/0x.../amounts?token0MaxAmount=1.0&token1MaxAmount=1.0&minPrice=0.0005&maxPrice=0.0006" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {tenant-id}"

# 4. Create position
curl -X POST https://api.example.com/api/pools/chain/137/pool/0x.../create \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "token0Amount": "1.0",
    "token1Amount": "0.5",
    "minPrice": "0.0005",
    "maxPrice": "0.0006"
  }'

# 5. Increase liquidity later
curl -X POST https://api.example.com/api/pools/chain/137/pool/0x.../12345/increase-liquidity \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "token0Amount": "0.5",
    "token1Amount": "0.25"
  }'

# 6. Collect fees
curl -X POST https://api.example.com/api/pools/chain/137/pool/0x.../12345/collect-fees \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "execute": true
  }'

# 7. Decrease liquidity
curl -X POST https://api.example.com/api/pools/chain/137/pool/0x.../12345/decrease-liquidity \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "percentage": "50"
  }'

Important Notes

NFT Positions: Each liquidity position is represented as an NFT. The tokenId identifies your position.
Price Ranges: Choose price ranges carefully. You only earn fees when price is within your range.
Impermanent Loss: Providing liquidity exposes you to impermanent loss risk. Understand this before providing liquidity.
Fee Collection: Fees accrue continuously. Collect them regularly to maximize returns.
Gas Fees: All operations require gas fees. Gas is paid in the pool's token0.
Liquidity Concentration: Concentrated liquidity in Uniswap V3 means you can provide liquidity in specific price ranges.
Automatic Signing: Most operations are automatically signed. You receive signature data to execute on-chain.
Caching: Pool data is cached for performance. Some data may be slightly delayed.
Supported Chains: Currently, pools are primarily available on Polygon (chain ID 137).
Amount Format: Always provide amounts in humanized format (decimal string). The API automatically handles conversion to the token's smallest unit based on token decimals.
Price Format: Prices are provided as decimal numbers representing the exchange rate.
Position Management: You can increase, decrease, or close positions at any time.

Security Considerations

Price Range Risk: If price moves outside your range, you stop earning fees and may experience impermanent loss.
Smart Contract Risk: Understand the risks of providing liquidity to automated market makers.
Market Conditions: Consider market volatility when setting price ranges.
Fee Collection: Regularly collect fees to avoid missing out on earnings.
Position Monitoring: Monitor your positions regularly to ensure they're performing as expected.
Liquidity Management: Don't over-concentrate liquidity in narrow price ranges unless you're confident about price direction.