Guides
Start typing to search…

Orca Whirlpools Guide

Orca is a leading DEX on Solana. At the core of its advanced liquidity mechanisms are Whirlpools, which implement a concentrated liquidity automated market maker (CLAMM). This model allows liquidity providers to allocate their capital to specific price ranges, potentially enhancing capital efficiency and increasing fee generation compared to traditional AMMs.

This guide provides a use case for leveraging the Cambrian API to access and analyze Orca Whirlpool data. Let's say you need to programmatically evaluate an Orca Whirlpool: perhaps to assess its viability for a trading strategy, model potential returns for liquidity provision, or simply gather comprehensive on-chain metrics. This guide outlines a common workflow, demonstrating how to chain API requests to achieve this.

The following sequence illustrates a typical approach for programmatic pool analysis:

  1. Pool Discovery (List Orca Pools):
    Your first step is typically to identify the target pool(s). The List Orca Pools endpoint returns a comprehensive list of all registered Orca Whirlpools, including their poolId (the pool's public key address), constituent tokens, and fee tiers. This allows you to programmatically filter for pools by specific token pairs or other criteria. The poolId obtained here is essential for subsequent, more targeted queries.

  2. Liquidity Distribution Analysis (Get Orca Pool Liquidity Map):
    Once a poolId is identified, you can query the Get Orca Pool Liquidity Map endpoint. This returns the current on-chain net liquidity distribution across price ticks for the specified pool. This data is crucial for assessing market depth, modeling potential price impact for swaps, or understanding the current concentration of liquidity relative to the active tick.

  3. Core Performance Metrics (Get Orca Pool Fee Metrics):
    To get a high-level overview of the pool's recent performance, use the Get Orca Pool Fee Metrics endpoint. It provides key indicators such as recent trading volume, fees generated (in USD), and current Total Value Locked (TVL) over a specified timeframeDays (e.g., 1, 7, or 30 days). This offers a quick snapshot of the pool's operational health.

  4. Historical Performance Analysis (Get Orca Pool Historical Data):
    For a deeper understanding of performance trends, the Get Orca Pool Historical Data endpoint provides daily time-series data for fees and volume (in USD) for a given poolId and timeframeDays. This allows for programmatic trend analysis, comparison over different periods, and identification of historical volatility or growth patterns.

  5. Fee APR and Utilization by Price Range (Get Orca Pool Fee Range Analysis):
    For developers building tools for liquidity providers or analyzing fee generation, the Get Orca Pool Fee Range Analysis endpoint offers valuable insights. It breaks down fee APR and swap utilization across discrete price ranges relative to the pool's current price. This data helps identify which price ticks are most actively traded and, consequently, generating the most fees, useful for modeling or optimizing liquidity provision strategies.

This workflow demonstrates how these Orca-specific endpoints can be used sequentially to build a comprehensive, data-driven understanding of a pool's characteristics and performance. The subsequent sections provide detailed specifications for each endpoint, including cURL examples and expected response structures, enabling you to integrate this data effectively into your applications and analyses.

Authentication

All requests to the Cambrian API require an API key. You must include your key in the x-api-key header of every request.

Example using cURL:

curl -H "x-api-key: YOUR_API_KEY" "https://opabinia.cambrian.org/api/v1/evm/chains"

Replace YOUR_API_KEY with your actual API key. You can obtain an API key from [Your Cambrian Dashboard Link - You'll need to add this link].

Orca API Endpoints

Here are the key Orca-specific endpoints you can use to access detailed pool data:

1. List Orca Pools

This endpoint returns a list of all Orca Whirlpools registered in our database. It includes details like token pairs, fee tiers, and creation timestamps, providing essential static information about each pool.

  • Endpoint: GET /solana/pools
  • Query Parameter:
    • dex=orca (Required): Specifies that you want to query Orca pools.
  • Example cURL Command: 
    curl --request GET \
     --url 'https://opabinia.cambrian.org/api/v1/solana/pools?dex=orca' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY' # Replace YOUR_API_KEY with your actual key
  • Example Successful Response (200 OK): 
    [
  {
    "columns": [
      {"name": "pool_address", "type": "String"},
      {"name": "created_at", "type": "DateTime('UTC')"},
      {"name": "token0_address", "type": "String"},
      {"name": "token0_symbol", "type": "String"},
      {"name": "token0_decimals", "type": "UInt8"},
      {"name": "token1_address", "type": "String"},
      {"name": "token1_symbol", "type": "String"},
      {"name": "token1_decimals", "type": "UInt8"},
      {"name": "tick_spacing", "type": "Int32"},
      {"name": "token_vault_a", "type": "String"},
      {"name": "token_vault_b", "type": "String"}
    ],
    "data": [
      [
        "12HkbTG7jAC3B1nuaMSevJ36tEQu1yH3vAtPbtgKhxTh",
        "2025-03-16T00:14:11+00:00",
        "AZsHEMXd36Bj1EMNXhowJajpUXzrKcK57wW4ZGXVa7yR",
        "GUAC",
        5,
        "Ddm4DTxNZxABUYm2A87TFLY6GDG2ktM2eJhGZS3EbzHM",
        "DISTRIBUTE",
        6,
        32896,
        "",
        ""
      ],
      [
        "12bDxpetQ7E1NCn2HQzby2eX6tUYaBFwBh2X5RL4XkBA",
        "2024-05-11T04:26:25+00:00",
        "So11111111111111111111111111111111111111112",
        "SOL",
        9,
        "7RoVuYRxfBeH9fwHrx8LeLte4uJLBM52UmF4nyh4tNiQ",
        "$smiski",
        6,
        128,
        "513tz7Vu847pd4EbezPmMN8uPy4WdgTSMXefvmBF4T7o",
        "H9u5JGqqcijw3vtka9Fz3mTSwRBs2CsAmWe8TxtanjcT"
      ]
      // ... more pool data arrays
    ],
    "rows": 13395 // Example: actual number of pools returned
  }
]

2. Get Orca Pool Fee Range Analysis

This endpoint retrieves fee APR and swap utilization data categorized by price ranges relative to the current price for a specific Orca Whirlpool. This can help you understand potential returns and liquidity utilization at different price points.

  • Endpoint: GET /solana/pools/fee_ranges
  • Query Parameters:
    • poolId=<POOL_ADDRESS> (Required): The public key address of the Orca Whirlpool. Example: Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE
    • timeframeDays=<DAYS> (Required): The number of past days for the analysis (e.g., 7).
  • Example cURL Command: 
    curl --request GET \
     --url 'https://opabinia.cambrian.org/api/v1/solana/pools/fee_ranges?poolId=Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE&timeframeDays=7' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY' # Replace YOUR_API_KEY with your actual key
  • Example Successful Response (200 OK): 
    [
  {
    "columns": [
      {"name": "range_label", "type": "String"},
      {"name": "priceRangeLower", "type": "Float64"},
      {"name": "priceRangeUpper", "type": "Float64"},
      {"name": "tickRangeLower", "type": "Float64"},
      {"name": "tickRangeUpper", "type": "Float64"},
      {"name": "utilization", "type": "Float64"},
      {"name": "updatedAt", "type": "DateTime('UTC')"}
    ],
    "data": [
      [
        "+/- 5%",
        137.49182825137277,
        151.9646522778331,
        -19843.0,
        -18843.0,
        96.51,
        "2025-05-06T19:12:47+00:00"
      ],
      [
        "+/- 10%",
        130.25541623814263,
        159.20106429106323,
        -20384.0,
        -18377.0,
        100.0,
        "2025-05-06T19:12:47+00:00"
      ],
      [
        "+/- 20%",
        115.78259221168236,
        173.6738883175235,
        -21562.0,
        -17507.0,
        100.0,
        "2025-05-06T19:12:47+00:00"
      ]
    ],
    "rows": 3
  }
]

3. Get Orca Pool Historical Data

This endpoint retrieves historical daily fee and volume data (in USD) for a specific Orca Whirlpool over a specified timeframe. This is useful for analyzing past performance and trends.

  • Endpoint: GET /solana/pools/historical_data
  • Query Parameters:
    • poolId=<POOL_ADDRESS> (Required): The public key address of the Orca Whirlpool. Example: Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE
    • timeframeDays=<DAYS> (Required): The number of past days for the analysis (e.g., 7).
  • Example cURL Command: 
    curl --request GET \
     --url 'https://opabinia.cambrian.org/api/v1/solana/pools/historical_data?poolId=Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE&timeframeDays=7' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY' # Replace YOUR_API_KEY with your actual key
  • Example Successful Response (200 OK): 
    [
  {
    "columns": [
      {"name": "timestamp", "type": "UInt32"},
      {"name": "feesUSD", "type": "Nullable(Float64)"},
      {"name": "volumeUSD", "type": "Nullable(Float64)"},
      {"name": "feeVolumeRatio", "type": "Nullable(Float64)"},
      {"name": "updatedAt", "type": "DateTime('UTC')"}
    ],
    "data": [
      [1745884800, 16151.376694608396, 40378436.86994516, 0.00040000004820965054, "2025-05-06T19:26:15+00:00"],
      [1745971200, 82475.87011726144, 206189644.55067942, 0.0004000000596392205, "2025-05-06T19:26:15+00:00"],
      [1746057600, 67389.31269560772, 168473255.72809932, 0.00040000006175679306, "2025-05-06T19:26:15+00:00"],
      [1746144000, 67325.68633846701, 168314193.9540591, 0.00040000005202676714, "2025-05-06T19:26:15+00:00"],
      [1746230400, 45771.63621411071, 114429071.76801695, 0.0004000000656031183, "2025-05-06T19:26:15+00:00"],
      [1746316800, 45196.4041920064, 112990990.1315931, 0.00040000007203555923, "2025-05-06T19:26:15+00:00"],
      [1746403200, 58041.97817765837, 145104919.73020315, 0.0004000000708837242, "2025-05-06T19:26:15+00:00"],
      [1746489600, 47214.426224194234, 118036045.01641439, 0.00040000006961965284, "2025-05-06T19:26:15+00:00"]
    ],
    "rows": 8
  }
]

4. Get Orca Pool Liquidity Map

This endpoint retrieves the distribution of net liquidity across price ticks for a specific Orca Whirlpool. It provides a snapshot of how liquidity is currently allocated, which can be crucial for understanding market depth and potential price impact of trades.

  • Endpoint: GET /solana/pools/liquidity_map
  • Query Parameters:
    • poolId=<POOL_ADDRESS> (Required): The public key address of the Orca Whirlpool. Example: DYFk5yvux4mkuQcxkA7H6FWgRQHc1Z7JUb42SJVxnhgG
    • resolution=<NUMBER> (Required): The number of data points (ticks) to return for the liquidity map. A higher number provides more granularity. Example: 200.
  • Example cURL Command: 
    curl --request GET \
     --url 'https://opabinia.cambrian.org/api/v1/solana/pools/liquidity_map?poolId=DYFk5yvux4mkuQcxkA7H6FWgRQHc1Z7JUb42SJVxnhgG&resolution=200' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY' # Replace YOUR_API_KEY with your actual key
  • Example Successful Response (200 OK): 
    [
  {
    "columns": [
      {"name": "timestamp", "type": "UInt32"},
      {"name": "tick", "type": "Int32"},
      {"name": "price", "type": "Float64"},
      {"name": "net_liquidity", "type": "Float64"},
      {"name": "updatedAt", "type": "DateTime('UTC')"}
    ],
    "data": [
      [1746515387, -49216, 0.008918862244743361, 2.2300019207003117e-12, "2025-05-06T19:49:47+00:00"],
      [1746515387, -49152, 0.008975694682432276, 2.2300019207003117e-12, "2025-05-06T19:49:47+00:00"],
      [1746515387, -49088, 0.009032996409588026, 2.2300019207003117e-12, "2025-05-06T19:49:47+00:00"],
      // ... more liquidity data points
      [1746515387, -36800, 0.041456314252619574, 16932856.9251917, "2025-05-06T19:49:47+00:00"],
      [1746515387, -36736, 0.04172418824691075, 0.0, "2025-05-06T19:49:47+00:00"]
    ],
    "rows": 200 // Matches the 'resolution' parameter
  }
]

5. Get Orca Pool Fee Metrics

This endpoint retrieves core metrics such as fees, volume, and Total Value Locked (TVL) for a specific Orca Whirlpool over a given timeframe. This data is essential for assessing overall pool health and performance.

  • Endpoint: GET /solana/pools/fee_metrics
  • Query Parameters:
    • poolId=<POOL_ADDRESS> (Required): The public key address of the Orca Whirlpool. Example: Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE
    • timeframeDays=<DAYS> (Required): The number of past days for the metrics (e.g., 1, 7, 30).
  • Example cURL Command: 
    curl --request GET \
     --url 'https://opabinia.cambrian.org/api/v1/solana/pools/fee_metrics?poolId=Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE&timeframeDays=1' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY' # Replace YOUR_API_KEY with your actual key
  • Example Successful Response (200 OK): 
    [
  {
    "columns": [
      {"name": "feesUSD", "type": "Float64"},
      {"name": "volumeUSD", "type": "Float64"},
      {"name": "tvlUSD", "type": "Float64"},
      {"name": "updatedAt", "type": "DateTime('UTC')"}
    ],
    "data": [
      [47214.426224194234, 118036045.01641439, 8396600.334619429, "2025-05-06T19:52:40+00:00"]
    ],
    "rows": 1
  }
]

This completes the overview of the key Orca-specific API endpoints. Remember to replace YOUR_API_KEY with your actual key in all examples. If you have any questions or encounter issues, please refer to our main API documentation or contact support.

Updated about 2 months ago