# Cambrian API Documentation This is a comprehensive API for blockchain and DeFi data, providing real-time and historical information across multiple chains including Solana, Base, and other EVM networks. ## OpenAPI Specifications Machine-readable API specs for client generation, AI tooling, and integration: - **DeFi Data API**: https://api.cambrian.org/openapi.json Prices, pools, tokens, portfolios for Solana & EVM chains - **Risk Analysis API**: https://api.cambrian.org/risk/openapi.json Protocol risk metrics and security assessments Full openapi json specs urls: - https://api.cambrian.org/openapi.json - https://api.cambrian.org/deep42/openapi.json - https://api.cambrian.org/risk/openapi.json ## Documentation Access **For LLMs**: All documentation links below end with `/llms.txt` - this provides machine-readable markdown format. **For Humans**: Remove the `/llms.txt` suffix from any link below to view the interactive documentation with a user-friendly interface and ability to test endpoints without providing an API key, which is otherwise required for making requests. **Example**: - LLM format: https://docs.cambrian.org/solana/pool-transactions/llms.txt - Human format: https://docs.cambrian.org/solana/pool-transactions ## API Key Required **IMPORTANT**: You need a Cambrian API key to use this API. Please obtain your API key before making requests to any endpoints. Signup for an API key here: https://console.cambrian.org/ ## Available Guides - FAQs: https://docs.cambrian.org/guides/faqs/llms.txt - CLI: https://docs.cambrian.org/guides/cli/llms.txt - Getting Started: https://docs.cambrian.org/guides/getting-started/llms.txt - MCP: https://docs.cambrian.org/guides/mcp/llms.txt - x402: https://docs.cambrian.org/guides/x402/llms.txt ## Available Endpoints ### Solana #### Ohlcv ##### Base quote - GET /solana/ohlcv/base-quote - Retrieve granular OHLCV data with separate base and quote token volumes for detailed trading analysis between any two SPL tokens. Provides the most detailed view of trading relationships with individual token flow tracking for advanced analytics. - Docs: https://docs.cambrian.org/solana/ohlcv/base-quote/llms.txt ##### Pool - GET /solana/ohlcv/pool - Retrieve OHLCV data for individual pool contracts enabling pair-specific price analysis and liquidity venue performance tracking. Essential for liquidity providers analyzing their specific pool performance and traders focusing on particular trading venues. - Docs: https://docs.cambrian.org/solana/ohlcv/pool/llms.txt ##### Token - GET /solana/ohlcv/token - Retrieve Open, High, Low, Close, and Volume data for any SPL token. - Docs: https://docs.cambrian.org/solana/ohlcv/token/llms.txt #### Orca ##### Pools - GET /solana/orca/pools - Retrieves a list of all Orca pools registered in the backend database (orca_pool_registry_target). It provides essential static information about each pool. - Docs: https://docs.cambrian.org/solana/orca/pools/llms.txt ###### Fee metrics - GET /solana/orca/pools/fee-metrics - Retrieves core metrics like fees (total, token0, token1, USD), volume (token0, token1, USD), Total Value Locked (TVL) in USD, and calculated Fee APR for a specific Orca Whirlpool over a given timeframe. - Docs: https://docs.cambrian.org/solana/orca/pools/fee-metrics/llms.txt ###### Fee ranges - GET /solana/orca/pools/fee-ranges - Retrieves fee APR and swap utilization data categorized by price ranges relative to the current price for a specific Orca Whirlpool. - Docs: https://docs.cambrian.org/solana/orca/pools/fee-ranges/llms.txt ###### Historical data - GET /solana/orca/pools/historical-data - Retrieves historical daily fee and volume data (in USD) for a specific Orca Whirlpool over a specified timeframe. - Docs: https://docs.cambrian.org/solana/orca/pools/historical-data/llms.txt ###### Liquidity map - GET /solana/orca/pools/liquidity-map - Retrieves the distribution of net liquidity across price ticks for a specific Orca Whirlpool. Returns liquidity values at representative tick intervals based on the specified resolution. Pool Must be created after 2025-02-27 - Docs: https://docs.cambrian.org/solana/orca/pools/liquidity-map/llms.txt ##### Pool - GET /solana/orca/pool - Retrieves detailed metrics and information for a specific Solana pool (identified by its program ID/address) using the pre-calculated orca_pool_details_view. - Docs: https://docs.cambrian.org/solana/orca/pool/llms.txt ##### Pool multi - GET /solana/orca/pool-multi - Get comprehensive overview metrics for multiple pools/pairs simultaneously within the same DEX. Returns pool details including price, volume, trades, and token information. - Docs: https://docs.cambrian.org/solana/orca/pool-multi/llms.txt #### Meteora dlmm ##### Pool - GET /solana/meteora-dlmm/pool - This endpoint returns basic pool information for a meteora pool. - Docs: https://docs.cambrian.org/solana/meteora-dlmm/pool/llms.txt ##### Pool multi - GET /solana/meteora-dlmm/pool-multi - Get comprehensive overview metrics for multiple pools/pairs simultaneously within the same DEX. Returns pool details including price, volume, trades, and token information. - Docs: https://docs.cambrian.org/solana/meteora-dlmm/pool-multi/llms.txt ##### Pools - GET /solana/meteora-dlmm/pools - This endpoint lists meteora pools - Docs: https://docs.cambrian.org/solana/meteora-dlmm/pools/llms.txt #### Raydium clmm ##### Pool - GET /solana/raydium-clmm/pool - This endpoint returns pool info for a specific raydium clmm pool. Among metrics returned are, tvl, apr24h, volume24h - Docs: https://docs.cambrian.org/solana/raydium-clmm/pool/llms.txt ##### Pools - GET /solana/raydium-clmm/pools - This endpoint lists basic pool information for Raydium CLMM - Docs: https://docs.cambrian.org/solana/raydium-clmm/pools/llms.txt #### Tokens - GET /solana/tokens - Returns a paginated list of known tokens for the Solana chain. - Docs: https://docs.cambrian.org/solana/tokens/llms.txt ##### Holder distribution over time - GET /solana/tokens/holder-distribution-over-time - This endpoint returns the distribution of token holders over a certain block range, at a certain interval, grouped by USD value tiers. - Docs: https://docs.cambrian.org/solana/tokens/holder-distribution-over-time/llms.txt ##### Holders - GET /solana/tokens/holders - Returns a list of accounts currently holding a specific Solana token (identified by its program ID/mint address), sorted by their current balance (descending). This endpoint leverages pre-aggregated data for performance. - Docs: https://docs.cambrian.org/solana/tokens/holders/llms.txt ##### Holders over time - GET /solana/tokens/holders-over-time - Returns a list of accounts holding a specific token (identified by its program ID/mint address) on Solana, providing snapshots at specified block intervals within a given range. First block gives full list of holders while subsequent blocks only provide holders that had balance changes in that interval. Results are sorted by block number (ascending) and then balance (descending) within each block. - Docs: https://docs.cambrian.org/solana/tokens/holders-over-time/llms.txt ##### Security - GET /solana/tokens/security - Provides comprehensive security analysis for a token on Solana, including ownership concentration, holder distribution, and transaction metrics. - Docs: https://docs.cambrian.org/solana/tokens/security/llms.txt #### Price volume ##### Multi - GET /solana/price-volume/multi - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token. Combines price and volume data in a single request to reduce API calls and improve application performance. Data aggregated across major Solana DEXs. - Docs: https://docs.cambrian.org/solana/price-volume/multi/llms.txt ##### Single - GET /solana/price-volume/single - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token. Combines price and volume data in a single request to reduce API calls and improve application performance. Data aggregated across major Solana DEXs. - Docs: https://docs.cambrian.org/solana/price-volume/single/llms.txt #### Traders ##### Leaderboard - GET /solana/traders/leaderboard - Leaderboard of the top traders by trade count, buy/sell/total volume for any SPL token across major Solana DEXs, for a specified recent interval. Supports front-end sorting of columns. Available columns for sorting are: total_volume, buy_volume, sell_volume, trade_count. - Docs: https://docs.cambrian.org/solana/traders/leaderboard/llms.txt #### Holder token balances - GET /solana/holder-token-balances - This endpoint returns token balances in usd for a specific user wallet, sorted by balance descending - Docs: https://docs.cambrian.org/solana/holder-token-balances/llms.txt #### Latest block - GET /solana/latest-block - This endpoint returns latest block and block time - Docs: https://docs.cambrian.org/solana/latest-block/llms.txt #### Pool transactions - GET /solana/pool-transactions - Retrieve a paginated list of trades/transactions for a specified Solana pool address including swaps, add liquidity, and remove liquidity events - Docs: https://docs.cambrian.org/solana/pool-transactions/llms.txt #### Pool transactions time bounded - GET /solana/pool-transactions-time-bounded - Get detailed transaction data for any SPL token across major Solana DEXs with precise Unix timestamp filtering for historical analysis and event-driven research. - Docs: https://docs.cambrian.org/solana/pool-transactions-time-bounded/llms.txt #### Price current - GET /solana/price-current - Retrieves the latest available USD price for a given Solana token program address - Docs: https://docs.cambrian.org/solana/price-current/llms.txt #### Price hour - GET /solana/price-hour - Aggregated USD price of a Solana token by program address, grouped by the specified interval (e.g., 1H, 1D, 1W, etc). Returns the average price for each interval. - Docs: https://docs.cambrian.org/solana/price-hour/llms.txt #### Price multi - GET /solana/price-multi - Retrieves the latest available USD prices for multiple Solana token program addresses (comma-separated) - Docs: https://docs.cambrian.org/solana/price-multi/llms.txt #### Price unix - GET /solana/price-unix - Retrieve historical price data for a specified Solana token at the nearest hour to a specific Unix timestamp. Returns the price, actual update time, and 24-hour price change. Essential for time-specific price analysis, backtesting, and historical data queries. - Docs: https://docs.cambrian.org/solana/price-unix/llms.txt #### Token details - GET /solana/token-details - Retrieves comprehensive details about a Solana token, including price history, trade statistics, holder information, and other key metrics - Docs: https://docs.cambrian.org/solana/token-details/llms.txt #### Token details multi - GET /solana/token-details-multi - Retrieve comprehensive details for multiple Solana tokens simultaneously. Returns the same data structure as the single token_details endpoint but for multiple tokens in a single API call. Maximum 50 tokens per request. - Docs: https://docs.cambrian.org/solana/token-details-multi/llms.txt #### Token mint burn transactions - GET /solana/token-mint-burn-transactions - Returns paginated list of mint and burn transactions for a specified Solana token, providing complete supply change audit trail with transaction details, amounts, and timing information. Essential for tracking token supply dynamics and compliance monitoring. - Docs: https://docs.cambrian.org/solana/token-mint-burn-transactions/llms.txt #### Token pool search - GET /solana/token-pool-search - Find pools containing a specific token and retrieve comprehensive trading statistics including 24h volume, trade counts, and buy/sell ratios. Essential for token analysis, liquidity discovery, and identifying the most active trading venues for any token. - Docs: https://docs.cambrian.org/solana/token-pool-search/llms.txt #### Token transactions - GET /solana/token-transactions - Retrieve a paginated list of trades/transactions for a specified Solana token address across all DEXes - Docs: https://docs.cambrian.org/solana/token-transactions/llms.txt #### Token transactions time bounded - GET /solana/token-transactions-time-bounded - Get detailed transaction data for any SPL token with precise Unix timestamp filtering for historical analysis and event-driven research. - Docs: https://docs.cambrian.org/solana/token-transactions-time-bounded/llms.txt #### Trade statistics - GET /solana/trade-statistics - Get instant trade analytics and performance metrics for any SPL tokens. View buy/sell volume breakdowns, trade counts, and USD values across customizable timeframes (1h to 30d). Perfect for portfolio tracking, performance dashboards, and quick market analysis. Query single tokens or multiple tokens at once using comma-separated addresses. Includes buy-to-sell ratios for comprehensive market insights. - Docs: https://docs.cambrian.org/solana/trade-statistics/llms.txt #### Trending tokens - GET /solana/trending-tokens - Retrieves a list of trending Solana tokens, ordered by price change in 24h, trade volume in 24h or current price. - Docs: https://docs.cambrian.org/solana/trending-tokens/llms.txt #### Wallet balance history - GET /solana/wallet-balance-history - Returns paginated list of balance changes for a specified wallet address, providing complete audit trail of portfolio changes with transaction details, pre/post balances, and timing information. Essential for portfolio tracking and compliance monitoring. - Docs: https://docs.cambrian.org/solana/wallet-balance-history/llms.txt ### Evm #### Lending ##### Morpho ###### V1 ###### Vault ###### Markets - GET /evm/lending/morpho/v1/vault/markets - Docs: https://docs.cambrian.org/evm/lending/morpho/v1/vault/markets/llms.txt ###### Vaults - GET /evm/lending/morpho/v1/vaults - Docs: https://docs.cambrian.org/evm/lending/morpho/v1/vaults/llms.txt ###### V2 ###### Vault ###### Markets - GET /evm/lending/morpho/v2/vault/markets - Docs: https://docs.cambrian.org/evm/lending/morpho/v2/vault/markets/llms.txt ###### Vaults - GET /evm/lending/morpho/v2/vaults - Docs: https://docs.cambrian.org/evm/lending/morpho/v2/vaults/llms.txt ###### Curator ###### Vaults - GET /evm/lending/morpho/curator/vaults - Docs: https://docs.cambrian.org/evm/lending/morpho/curator/vaults/llms.txt ###### Curators - GET /evm/lending/morpho/curators - Docs: https://docs.cambrian.org/evm/lending/morpho/curators/llms.txt ###### Markets - GET /evm/lending/morpho/markets - Docs: https://docs.cambrian.org/evm/lending/morpho/markets/llms.txt ##### Euler ###### V2 ###### Vault ###### Markets - GET /evm/lending/euler/v2/vault/markets - Docs: https://docs.cambrian.org/evm/lending/euler/v2/vault/markets/llms.txt ###### Vaults - GET /evm/lending/euler/v2/vaults - Docs: https://docs.cambrian.org/evm/lending/euler/v2/vaults/llms.txt ###### Curator ###### Vaults - GET /evm/lending/euler/curator/vaults - Docs: https://docs.cambrian.org/evm/lending/euler/curator/vaults/llms.txt ###### Curators - GET /evm/lending/euler/curators - Docs: https://docs.cambrian.org/evm/lending/euler/curators/llms.txt ###### Markets - GET /evm/lending/euler/markets - Docs: https://docs.cambrian.org/evm/lending/euler/markets/llms.txt ##### Aave ###### V3 ###### Pools - GET /evm/lending/aave/v3/pools - Docs: https://docs.cambrian.org/evm/lending/aave/v3/pools/llms.txt ##### Overview - GET /evm/lending/overview - This is a beta test of the lending overview endpoint - Docs: https://docs.cambrian.org/evm/lending/overview/llms.txt ##### Protocols - GET /evm/lending/protocols - This endpoint list all of the supported lending protocols - Docs: https://docs.cambrian.org/evm/lending/protocols/llms.txt #### Aero ##### V2 ###### Fee metrics - GET /evm/aero/v2/fee-metrics - Shows fee metrics and daily historical data for the previous seven completed UTC days. Usd fields are null when a pool-token price is unavailable. - Docs: https://docs.cambrian.org/evm/aero/v2/fee-metrics/llms.txt ###### Pool - GET /evm/aero/v2/pool - Get information for a specific Aerodrome V2 pool. Usd prices, valuations, and APRs are null when a required price is unavailable. - Docs: https://docs.cambrian.org/evm/aero/v2/pool/llms.txt ###### Pool volume - GET /evm/aero/v2/pool-volume - Shows recent pool activity and hourly distribution. Usd fields are null when a pool-token price is unavailable. - Docs: https://docs.cambrian.org/evm/aero/v2/pool-volume/llms.txt ###### Pools - GET /evm/aero/v2/pools - Returns liquidity pools with summary metrics for the previous 7 completed UTC days. Usd prices, valuations, and APRs are null when a required price is unavailable. - Docs: https://docs.cambrian.org/evm/aero/v2/pools/llms.txt ###### Provider summary - GET /evm/aero/v2/provider-summary - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics. Portfolio-wide Usd aggregates and weighted APRs are null if any represented position cannot be fully priced; per-pool and per-token values are nullable independently. - Docs: https://docs.cambrian.org/evm/aero/v2/provider-summary/llms.txt ##### V3 ###### Pool - GET /evm/aero/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). - Docs: https://docs.cambrian.org/evm/aero/v3/pool/llms.txt #### Alien ##### V3 ###### Pool - GET /evm/alien/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR (Annual Percentage Rate), Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). - Docs: https://docs.cambrian.org/evm/alien/v3/pool/llms.txt ###### Pools - GET /evm/alien/v3/pools - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - Docs: https://docs.cambrian.org/evm/alien/v3/pools/llms.txt #### Clones ##### V3 ###### Pool - GET /evm/clones/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR (Annual Percentage Rate), Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). - Docs: https://docs.cambrian.org/evm/clones/v3/pool/llms.txt ###### Pools - GET /evm/clones/v3/pools - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - Docs: https://docs.cambrian.org/evm/clones/v3/pools/llms.txt #### Pancake ##### V3 ###### Pool - GET /evm/pancake/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR (Annual Percentage Rate), Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). - Docs: https://docs.cambrian.org/evm/pancake/v3/pool/llms.txt ###### Pools - GET /evm/pancake/v3/pools - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - Docs: https://docs.cambrian.org/evm/pancake/v3/pools/llms.txt #### Sushi ##### V3 ###### Pool - GET /evm/sushi/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR (Annual Percentage Rate), Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). - Docs: https://docs.cambrian.org/evm/sushi/v3/pool/llms.txt ###### Pools - GET /evm/sushi/v3/pools - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - Docs: https://docs.cambrian.org/evm/sushi/v3/pools/llms.txt #### Tvl ##### Status - GET /evm/tvl/status - Returns the tokens held by an address - Docs: https://docs.cambrian.org/evm/tvl/status/llms.txt ##### Top owners - GET /evm/tvl/top-owners - Returns top token holders for a given token address. - Docs: https://docs.cambrian.org/evm/tvl/top-owners/llms.txt #### Uniswap ##### V3 ###### Pool - GET /evm/uniswap/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR (Annual Percentage Rate), Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). - Docs: https://docs.cambrian.org/evm/uniswap/v3/pool/llms.txt ###### Pools - GET /evm/uniswap/v3/pools - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - Docs: https://docs.cambrian.org/evm/uniswap/v3/pools/llms.txt #### Chains - GET /evm/chains - Returns information about supported EVM blockchain networks - Docs: https://docs.cambrian.org/evm/chains/llms.txt #### Dexes - GET /evm/dexes - List of DEXes on EVM compatible chains - Docs: https://docs.cambrian.org/evm/dexes/llms.txt #### Price current - GET /evm/price-current - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - Docs: https://docs.cambrian.org/evm/price-current/llms.txt #### Price hour - GET /evm/price-hour - Returns historical hourly price data for a specified EVM token. Limitations: Maximum 1000 hours of historical data, timestamps are in UTC format. Use /evm/tokens endpoint to get list of valid token addresses. - Docs: https://docs.cambrian.org/evm/price-hour/llms.txt #### Tokens - GET /evm/tokens - Returns a list of all erc20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - Docs: https://docs.cambrian.org/evm/tokens/llms.txt ### Deep42 #### Social data ##### Alpha tweet detection - GET /deep42/social-data/alpha-tweet-detection - Feed of tweets detected as having high alpha potential for cryptocurrency investments. Each tweet is scored across four dimensions: sentiment (bullish/bearish direction), alpha (investment insight quality), legitimacy (source reliability), and technical accuracy (correctness of crypto/DeFi claims). AI-generated reasoning explains each score. Version 2 (default) includes author track records with directional prediction accuracy measured at hourly price resolution. Methodology note (effective 2026-06-20): the sentiment scoring model was recalibrated to better distinguish neutral content from bullish content and to populate the full 0-10 scale; sentiment scored before this date reflects the prior calibration and runs higher. Historical tweets can be re-scored with the current methodology on request. - Docs: https://docs.cambrian.org/deep42/social-data/alpha-tweet-detection/llms.txt ##### Influencer credibility - GET /deep42/social-data/influencer-credibility - Returns cryptocurrency influencers ranked by credibility score, track record, accuracy, and engagement metrics. Analyzes high-quality tweets to identify the most reliable voices in crypto. Track record accuracy is measured using directional price predictions at hourly resolution: a bullish signal is correct if the token price increased, bearish if it decreased - Docs: https://docs.cambrian.org/deep42/social-data/influencer-credibility/llms.txt ##### Sentiment shifts - GET /deep42/social-data/sentiment-shifts - Identifies tokens with significant sentiment changes that could signal market movements and trading opportunities. Compares average AI-assigned sentiment scores (0-10 per tweet) between a current period and a previous period of equal length. Only includes tokens with sufficient tweet volume in both periods for statistical relevance. Methodology note (effective 2026-06-20): the sentiment scoring model was recalibrated to better distinguish neutral content from bullish content and to populate the full 0-10 scale; sentiment scored before this date reflects the prior calibration and runs higher. Historical tweets can be re-scored with the current methodology on request. - Docs: https://docs.cambrian.org/deep42/social-data/sentiment-shifts/llms.txt ##### Token analysis - GET /deep42/social-data/token-analysis - Comprehensive social intelligence report for a cryptocurrency token with sentiment analysis. Methodology note (effective 2026-06-20): the sentiment scoring model was recalibrated to better distinguish neutral content from bullish content and to populate the full 0-10 scale; sentiment scored before this date reflects the prior calibration and runs higher. Historical tweets can be re-scored with the current methodology on request. - Docs: https://docs.cambrian.org/deep42/social-data/token-analysis/llms.txt ##### Trending momentum - GET /deep42/social-data/trending-momentum - Identifies tokens with rapidly increasing social signals and momentum indicators - Docs: https://docs.cambrian.org/deep42/social-data/trending-momentum/llms.txt ### Perp risk engine - GET /risk/perp-risk-engine - Calculate liquidation risk probability for leveraged cryptocurrency positions. Uses Monte Carlo simulations with historical price data to assess risk. Internal parameters (lookback_hours, simulations, time_steps) are calculated automatically based on the risk_horizon parameter. - Docs: https://docs.cambrian.org/perp-risk-engine/llms.txt ## Key Resources - Full API documentation: https://docs.cambrian.org - OpenAPI specifications: https://docs.cambrian.org/specs - LLMs.txt (this file): https://docs.cambrian.org/llms.txt - CLI skill: https://github.com/cambriannetwork/cambrian-cli/blob/main/skills/cambrian/SKILL.md - MCP skill: https://github.com/cambriannetwork/cambrian-api-mcp/blob/main/skills/cambrian-mcp/SKILL.md ## Contact For questions or support, visit: https://discord.com/channels/1375182661202481172/1376641098516271155 --- # Full Endpoint Documentation ## Cambrian API: Detect high-alpha tweets **Endpoint:** /api/v1/deep42/social-data/alpha-tweet-detection # Alpha Tweet Detection ## Overview Detects high-alpha tweets in the cryptocurrency space by scoring each tweet across four dimensions: sentiment (bullish/bearish direction), alpha (investment insight quality), legitimacy (source reliability), and technical accuracy (correctness of crypto/DeFi claims). AI-generated reasoning explains each score, and version 2 (default) additionally includes author track records with directional prediction accuracy measured at hourly price resolution. ## Business Value - **Investment Signal Discovery**: Identify high-quality tweets with actionable cryptocurrency insights before they become mainstream - **Risk Assessment**: Evaluate the credibility and technical accuracy of crypto claims through AI-powered analysis - **Author Performance Tracking**: Access comprehensive track records showing prediction accuracy and returns across multiple timeframes - **Market Intelligence**: Discover emerging narratives and sentiment shifts from verified sources in real-time - **Alpha Generation**: Filter noise to focus on tweets with genuine DeFi alpha and investment potential ## Endpoint Details **URL**: ``` https://api.cambrian.org/deep42/social-data/alpha-tweet-detection ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | limit | integer | No | 20 | Number of tweets to analyze (maximum 100) | | token_filter | string | No | - | Filter tweets by specific token symbol for focused alpha analysis | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | twitterHandle | String | Twitter username of the tweet author | | tokenSymbol | String | Cryptocurrency token symbol mentioned in the tweet (e.g., BTC, ETH, SOL) | | text | String | Full tweet text content | | createdAtTimestamp | Integer | Unix timestamp (seconds) when the tweet was originally posted on Twitter | | scoredAtTimestamp | Integer | Unix timestamp (seconds) when the tweet was collected and scored by the AI pipeline | | retweetCountAtCollection | Integer | Retweets at time of collection (point-in-time snapshot, not live-updating) | | favoriteCountAtCollection | Integer | Likes at time of collection (point-in-time snapshot, not live-updating) | | replyCountAtCollection | Integer | Replies at time of collection (point-in-time snapshot, not live-updating) | | quoteCountAtCollection | Integer | Quote tweets at time of collection (point-in-time snapshot, not live-updating) | | sentiment | Number | AI-scored sentiment direction. Range 0-10. >=7 = bullish, <=3 = bearish, 4-6 = neutral | | alpha | Number | DeFi alpha investment insight quality. Range 0-10. Higher = more novel, specific, tradeable insight | | legitimacy | Number | Source and claim legitimacy. Range 0-10. Assesses verified sources and factual on-chain references | | technicalAccuracy | Number | Technical correctness of crypto/DeFi claims. Range 0-10 | | isRecent | Boolean | Whether the tweet content discusses recent events at the time of scoring | | isVerifiable | Boolean | Whether the tweet's claims can be independently verified via on-chain data or public sources | | scoresReasoning | String | AI-generated explanation of all score assignments, including cited evidence and risk factors | | tweetUrl | String | Direct URL to the original tweet on X/Twitter | **Note**: Version 2 (default) response also includes `userTrackRecord*` fields (e.g., `userTrackRecordAccuracy24h`, `userTrackRecordPerformanceTier`) with author-level directional prediction accuracy. These are omitted above because the examples below were captured against the v1 response schema. ## Examples ### 1. Default Alpha Tweet Feed Fetches the 5 most recent high-alpha tweets across all tokens. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/alpha-tweet-detection?limit=5" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "solanafloor", "tokenSymbol": "SOL", "text": "BREAKING: BlackRock has filed with the SEC to launch the BlackRock Daily Reinvestment Stablecoin Reserve Vehicle on @Solana, designed to serve as an eligible stablecoin reserve asset under the GENIUS Act. https://t.co/1LsHhplDAx", "createdAtTimestamp": 1785775429, "scoredAtTimestamp": 1785942558, "retweetCountAtCollection": 23, "favoriteCountAtCollection": 174, "replyCountAtCollection": 22, "quoteCountAtCollection": 5, "sentiment": 10, "alpha": 10, "legitimacy": 9, "technicalAccuracy": 9, "isRecent": true, "isVerifiable": true, "scoresReasoning": "BlackRock filed with the SEC on May 8, 2026, for a 'BlackRock Daily Reinvestment Stablecoin Reserve Vehicle' (BRSRV). This vehicle is designed to be a compliant reserve asset under the GENIUS Act, which was signed into law on July 18, 2025, providing a regulatory framework for stablecoins. The BRSRV's 'OnChain Shares' are confirmed to support Solana, along with Ethereum and Tempo.", "tweetUrl": "https://x.com/solanafloor/status/2084319336907317657" }, { "twitterHandle": "madblocksbp", "tokenSymbol": "XPR", "text": "XPRDROPS is not an airdrop. It's a wallet drainer wearing @XPRNetwork's name. Nobody is handing out free $XPR. Nobody. The moment you connect and sign, the account is no longer yours.", "createdAtTimestamp": 1785768826, "scoredAtTimestamp": 1785942558, "retweetCountAtCollection": 3, "favoriteCountAtCollection": 17, "replyCountAtCollection": 1, "quoteCountAtCollection": 0, "sentiment": 0, "alpha": 10, "legitimacy": 9, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "Multiple recent sources confirm a surge in fake airdrop and phishing scams targeting XRP and XRPL users, often involving impersonation of legitimate projects like XPR Network. These scams operate as wallet drainers, tricking users into connecting their wallets and signing malicious transactions.", "tweetUrl": "https://x.com/madblocksbp/status/2084291643331522997" }, { "twitterHandle": "bscgemsalert", "tokenSymbol": "ACX", "text": "Binance will delist @AcrossProtocol $ACX, @Hashflow $HFT, @_PIVX $PIVX, @VulcanForged $PYR, @Vanarchain $VANRY, and @BuildOnViction $VIC on August 17th", "createdAtTimestamp": 1785857171, "scoredAtTimestamp": 1785942558, "retweetCountAtCollection": 1, "favoriteCountAtCollection": 10, "replyCountAtCollection": 2, "quoteCountAtCollection": 0, "sentiment": 0, "alpha": 10, "legitimacy": 10, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "Binance officially announced the delisting of ACX, HFT, PIVX, PYR, VANRY, and VIC, with spot trading ceasing on August 17, 2026. This announcement was made on August 3, 2026, and is widely reported by multiple reputable crypto news sources.", "tweetUrl": "https://x.com/bscgemsalert/status/2084662190166934000" }, { "twitterHandle": "trump666eth", "tokenSymbol": "LINK", "text": "DTCC chose @chainlink's Runtime Environment for production use. Live trades already started. $33 trillion in transaction value has already moved through Chainlink oracles.", "createdAtTimestamp": 1785731820, "scoredAtTimestamp": 1785942558, "retweetCountAtCollection": 8, "favoriteCountAtCollection": 50, "replyCountAtCollection": 3, "quoteCountAtCollection": 0, "sentiment": 10, "alpha": 9, "legitimacy": 8, "technicalAccuracy": 9, "isRecent": true, "isVerifiable": true, "scoresReasoning": "DTCC has indeed chosen Chainlink's Runtime Environment (CRE) for its Collateral AppChain. Live production trades using tokenized US stocks and ETFs as collateral began in July 2026. Chainlink's historical metrics (approximately $32.8 trillion in transaction value, 19.62 billion verified messages) align closely with the tweet's claims.", "tweetUrl": "https://x.com/trump666eth/status/2084136429450600646" }, { "twitterHandle": "wealthmatica", "tokenSymbol": "ZETA", "text": "$ZETA reported their 20th consecutive BEAT & RAISE quarter. GAAP EPS: $0.03. Organic revenue growth came in at 28% YoY.", "createdAtTimestamp": 1785932332, "scoredAtTimestamp": 1785942558, "retweetCountAtCollection": 2, "favoriteCountAtCollection": 19, "replyCountAtCollection": 6, "quoteCountAtCollection": 1, "sentiment": 10, "alpha": 9, "legitimacy": 2, "technicalAccuracy": 8, "isRecent": true, "isVerifiable": true, "scoresReasoning": "The tweet explicitly refers to '$ZETA cryptocurrency' but discusses financial metrics characteristic of the publicly traded company Zeta Global (NYSE: ZETA), not the ZetaChain cryptocurrency. While the financial figures cited are largely accurate for Zeta Global's Q2 2026 earnings, attributing them to a cryptocurrency is fundamentally incorrect and misleading, resulting in a low legitimacy score.", "tweetUrl": "https://x.com/wealthmatica/status/2084977436354118037" } ] ``` Note how the `legitimacy` score for the `$ZETA` tweet (2/10) is much lower than the others despite a high `alpha` score — the AI reasoning flags that the tweet conflates a publicly traded stock with a similarly-named cryptocurrency, demonstrating the value of legitimacy scoring for filtering misleading content. ### 2. Token-Filtered Alpha Feed Filters results to only tweets mentioning a specific token symbol (BTC), useful for token-focused research workflows. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/alpha-tweet-detection?limit=3&token_filter=BTC" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "dustybc", "tokenSymbol": "BTC", "text": "JUST IN: Michael Saylor says \"When I say 'Never Sell Your Bitcoin,' I speak as one saver to another. I have never sold mine. Not one satoshi. Strategy is a public company, not my wallet. Since 2020, it has disclosed it may buy or sell $BTC to manage capital.\"", "createdAtTimestamp": 1785779688, "scoredAtTimestamp": 1785942579, "retweetCountAtCollection": 1, "favoriteCountAtCollection": 28, "replyCountAtCollection": 3, "quoteCountAtCollection": 0, "sentiment": 9, "alpha": 8, "legitimacy": 10, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "Michael Saylor's statement is a direct quote, confirmed by multiple recent news sources, clarifying his personal 'never sell' Bitcoin philosophy versus Strategy Inc.'s corporate capital management strategy, which has disclosed since 2020 that it may buy or sell BTC to manage capital.", "tweetUrl": "https://x.com/dustybc/status/2084337199659585794" }, { "twitterHandle": "andrewmoh", "tokenSymbol": "BTC", "text": "For anyone who wants to manually find extra yields on FXRP: new destinations @Morpho and @SentoraHQ. This adoption marks a historic moment when FXRP is accepted as collateral in an institutional lending vault on Ethereum.", "createdAtTimestamp": 1785844767, "scoredAtTimestamp": 1785942579, "retweetCountAtCollection": 0, "favoriteCountAtCollection": 3, "replyCountAtCollection": 3, "quoteCountAtCollection": 0, "sentiment": 9, "alpha": 8, "legitimacy": 9, "technicalAccuracy": 9, "isRecent": true, "isVerifiable": true, "scoresReasoning": "The tweet accurately reports a very recent and significant development: FXRP has been accepted as collateral in Sentora's RLUSD lending vault on Morpho on Ethereum. Minor discrepancies exist in specific ranking details, but the core claims are legitimate and represent valuable, market-moving information.", "tweetUrl": "https://x.com/andrewmoh/status/2084610162585965043" }, { "twitterHandle": "whaleinsider", "tokenSymbol": "BTC", "text": "JUST IN: BlackRock clients buy $111.43 million worth of $BTC. https://t.co/7LPOmpoQ1R", "createdAtTimestamp": 1785821100, "scoredAtTimestamp": 1785942579, "retweetCountAtCollection": 18, "favoriteCountAtCollection": 190, "replyCountAtCollection": 40, "quoteCountAtCollection": 2, "sentiment": 8, "alpha": 8, "legitimacy": 9, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "The claim is legitimate, recent, and verifiable. Farside Investors data indicates that BlackRock's iShares Bitcoin Trust (IBIT) recorded $111.4 million in net inflows on August 3, 2026, making it the largest inflow among U.S. spot Bitcoin ETFs for that day.", "tweetUrl": "https://x.com/whaleinsider/status/2084510894948552777" } ] ``` All three results are BTC-specific tweets with high legitimacy and technical accuracy scores, demonstrating that `token_filter` reliably narrows the feed to a single token while preserving the full scoring detail. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/deep42/social-data/alpha-tweet-detection" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/deep42/social-data/alpha-tweet-detection") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## API Versioning This endpoint supports multiple API versions. Use the `Accept` header to request a specific version. ### Available Versions | Version | State | Default | Accept Header | |---------|-------|---------|---------------| | 2.0.0 | Current | Yes | `application/vnd.cambrian.deep42.social-data.alpha-tweet-detection.v2+json` | | 1.0.0 | Current | No | `application/vnd.cambrian.deep42.social-data.alpha-tweet-detection.v1+json` | ### How to Request a Specific Version ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/alpha-tweet-detection" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Accept: application/vnd.cambrian.deep42.social-data.alpha-tweet-detection.v2+json" ``` ### Version Lifecycle - **Current**: Actively maintained and recommended for new integrations - **Deprecated**: Still functional but scheduled for removal (check `deprecated_at`) - **Sunset**: No longer available (returns `410 Gone`) **Note**: If no `Accept` header is specified, the default version (2.0.0) is returned. --- ## Related Endpoints - `/deep42/social-data/influencer-credibility` - Returns cryptocurrency influencers ranked by credibility score, track record, accuracy, and engagement metrics. - `/deep42/social-data/sentiment-shifts` - Identifies tokens with significant sentiment changes that could signal market movements and trading opportunities. - `/deep42/social-data/token-analysis` - Comprehensive social intelligence report for a cryptocurrency token with sentiment analysis. - `/deep42/social-data/trending-momentum` - Identifies tokens with rapidly increasing social signals and momentum indicators. --- ## Cambrian API: Detect high-alpha tweets **Endpoint:** /api/v1/deep42/social-data/alpha-tweet-detection # Alpha Tweet Detection ## Overview This endpoint detects high-alpha tweets related to cryptocurrency investments using AI-powered analysis. Each tweet is scored using a combination of sentiment, legitimacy, and technical accuracy metrics, providing investors with curated high-potential trading signals from social media. ## Business Value - **Alpha Discovery**: Identify high-alpha cryptocurrency tweets before they trend broadly - **Sentiment Analysis**: Access AI-powered scoring of sentiment, alpha potential, legitimacy, and technical accuracy - **Historical Performance**: Track record analysis of Twitter users provides credibility assessment - **Risk Assessment**: Legitimacy and technical accuracy scores help filter out noise and misinformation - **Real-time Intelligence**: Get fresh alpha signals as they emerge on social media platforms ## Endpoint Details **URL**: ``` https://deep42.cambrian.network/deep42/social-data/alpha-tweet-detection ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | limit | integer | No | 20 | Number of tweets to analyze (maximum: 100) | | token_filter | string | No | - | Filter tweets by specific token symbol for focused alpha analysis | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | twitterHandle | String | Twitter username of the author | | tokenSymbol | String | Cryptocurrency token symbol mentioned in the tweet | | text | String | Full text content of the tweet | | createdAtTimestamp | Number | Unix timestamp when the tweet was created | | scoredAtTimestamp | Number | Unix timestamp when the tweet was analyzed | | retweetCountAtCollection | Number | Number of retweets at time of collection | | favoriteCountAtCollection | Number | Number of likes/favorites at time of collection | | replyCountAtCollection | Number | Number of replies at time of collection | | quoteCountAtCollection | Number | Number of quote tweets at time of collection | | sentiment | Number | Sentiment score (1-10, where 10 is most bullish) | | alpha | Number | Alpha potential score (1-10, where 10 is highest alpha) | | legitimacy | Number | Legitimacy score (1-10, where 10 is most legitimate) | | technicalAccuracy | Number | Technical accuracy score (1-10, where 10 is most accurate) | | isRecent | Boolean | Whether the tweet is recent enough to be actionable | | isVerifiable | Boolean | Whether the tweet claims can be verified | | scoresReasoning | String | AI-generated explanation for the assigned scores | | tweetUrl | String | Direct URL to the tweet | | userTrackRecordSignals | Number | Total number of signals from this user | | userTrackRecordUniqueTokens | Number | Number of unique tokens this user has signaled | | userTrackRecordActiveDays | Number | Number of days this user has been active | | userTrackRecordFirstSignalDate | String | Date of user's first signal (YYYY-MM-DD format) | | userTrackRecordLastSignalDate | String | Date of user's most recent signal (YYYY-MM-DD format) | | userTrackRecordAccuracy24h | Number | User's prediction accuracy over 24 hours (percentage) | | userTrackRecordAccuracy7d | Number | User's prediction accuracy over 7 days (percentage) | | userTrackRecordAccuracy30d | Number | User's prediction accuracy over 30 days (percentage) | | userTrackRecordAvgReturn24h | Number | Average return percentage for user's 24-hour predictions | | userTrackRecordAvgReturn7d | Number | Average return percentage for user's 7-day predictions | | userTrackRecordAvgReturn30d | Number | Average return percentage for user's 30-day predictions | | userTrackRecordBullishSignals | Number | Number of bullish signals from this user | | userTrackRecordBearishSignals | Number | Number of bearish signals from this user | | userTrackRecordAvgSentiment | Number | User's average sentiment score across all signals | | userTrackRecordAvgAlpha | Number | User's average alpha score across all signals | | userTrackRecordPerformanceTier | String | Performance tier classification (e.g., "unproven", "proven", "top_performer") | ## Examples ### 1. Get Latest Alpha Tweets Retrieve the most recent high-alpha cryptocurrency tweets with default parameters. ```bash curl -X GET "https://x402.cambrian.network/deep42/social-data/alpha-tweet-detection?limit=5" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "bitcoinlfgo", "tokenSymbol": "BTC", "text": "💥 BREAKING \n\n$BTC BREAKS $90,000\n\nBULLS ARE BACKKKKK https://t.co/QDzTSL3JPh", "createdAtTimestamp": 1766980898, "scoredAtTimestamp": 1767026969, "retweetCountAtCollection": 79, "favoriteCountAtCollection": 629, "replyCountAtCollection": 77, "quoteCountAtCollection": 1, "sentiment": 10, "alpha": 10, "legitimacy": 10, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "The tweet uses strong positive language ('BREAKS', 'BULLS ARE BACKKKKK') and emoji ('💥') following a significant price milestone ($90,000), indicating extreme bullish sentiment and high relevance for BTC.", "tweetUrl": "https://x.com/bitcoinlfgo/status/2005489361002090645", "userTrackRecordSignals": 62, "userTrackRecordUniqueTokens": 14, "userTrackRecordActiveDays": 38, "userTrackRecordFirstSignalDate": "2025-03-05", "userTrackRecordLastSignalDate": "2025-12-29", "userTrackRecordAccuracy24h": 46.7, "userTrackRecordAccuracy7d": 57.7, "userTrackRecordAccuracy30d": 71.0, "userTrackRecordAvgReturn24h": 0.13, "userTrackRecordAvgReturn7d": 1.88, "userTrackRecordAvgReturn30d": 11.87, "userTrackRecordBullishSignals": 55, "userTrackRecordBearishSignals": 7, "userTrackRecordAvgSentiment": 7.65, "userTrackRecordAvgAlpha": 6.15, "userTrackRecordPerformanceTier": "unproven" }, { "twitterHandle": "CryptoTice_", "tokenSymbol": "BTC", "text": "🚨 BREAKING: U.S. MOVES TOWARD A STRATEGIC $BTC RESERVE 🇺🇸\n\nCongress just introduced a bill that:\n• Lets Americans pay taxes in Bitcoin\n• Removes capital gains tax on those payments\n\nThis isn't small change.\nIt's structural adoption.\n\n• Bitcoin becomes a sovereign-backed asset\n• Scarcity tightens as demand hits the national level\n• Policy flips from selling to stacking\n\nThis changes everything.\n$BTC is no longer optional it's infrastructure.", "createdAtTimestamp": 1766916002, "scoredAtTimestamp": 1767026969, "retweetCountAtCollection": 62, "favoriteCountAtCollection": 372, "replyCountAtCollection": 36, "quoteCountAtCollection": 3, "sentiment": 10, "alpha": 10, "legitimacy": 10, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "The tweet is overwhelmingly positive, using strong bullish language ('BREAKING', 'structural adoption', 'sovereign-backed asset', 'changes everything', 'infrastructure') regarding proposed US legislation that benefits BTC (tax payments in BTC, removal of capital gains). This suggests a very strong positive signal for the token's future adoption and valuation.", "tweetUrl": "https://x.com/CryptoTice_/status/2005217165994266725", "userTrackRecordSignals": 45, "userTrackRecordUniqueTokens": 5, "userTrackRecordActiveDays": 19, "userTrackRecordFirstSignalDate": "2025-06-29", "userTrackRecordLastSignalDate": "2025-12-29", "userTrackRecordAccuracy24h": 61.5, "userTrackRecordAccuracy7d": 32.4, "userTrackRecordAccuracy30d": 100.0, "userTrackRecordAvgReturn24h": 0.11, "userTrackRecordAvgReturn7d": -2.07, "userTrackRecordAvgReturn30d": 55.36, "userTrackRecordBullishSignals": 40, "userTrackRecordBearishSignals": 5, "userTrackRecordAvgSentiment": 7.76, "userTrackRecordAvgAlpha": 8.36, "userTrackRecordPerformanceTier": "proven" }, { "twitterHandle": "ArdiNSC", "tokenSymbol": "ZEC", "text": "Another banger on $ZEC. 🎯\n\n+1300% for the month of December on my Zcash trades alone.\n\nHappy Saturday 💰 https://t.co/wGm8MO6lsw", "createdAtTimestamp": 1766850870, "scoredAtTimestamp": 1767026969, "retweetCountAtCollection": 22, "favoriteCountAtCollection": 188, "replyCountAtCollection": 78, "quoteCountAtCollection": 0, "sentiment": 10, "alpha": 10, "legitimacy": 10, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "Extremely positive sentiment indicated by 'banger' and massive reported gains (+1300%). The specific, large gain suggests high confidence and strong trading value for those interested in ZEC.", "tweetUrl": "https://x.com/ArdiNSC/status/2004943984242938021", "userTrackRecordSignals": 78, "userTrackRecordUniqueTokens": 9, "userTrackRecordActiveDays": 19, "userTrackRecordFirstSignalDate": "2025-12-07", "userTrackRecordLastSignalDate": "2025-12-28", "userTrackRecordAccuracy24h": 73.5, "userTrackRecordAccuracy7d": 62.1, "userTrackRecordAccuracy30d": null, "userTrackRecordAvgReturn24h": 2.62, "userTrackRecordAvgReturn7d": 2.28, "userTrackRecordAvgReturn30d": null, "userTrackRecordBullishSignals": 24, "userTrackRecordBearishSignals": 54, "userTrackRecordAvgSentiment": 3.99, "userTrackRecordAvgAlpha": 7.5, "userTrackRecordPerformanceTier": "top_performer" }, { "twitterHandle": "gustloureiro", "tokenSymbol": "AVICI", "text": "Only things I'm holding into 2026 and why and in decrescent order:\n\n$AVICI -> Study ownership coins + highest drive founder (@RamXBT) I've ever seen + hottest roadmap + neobank is a trillion dollar size narrative + I freakin' use the product and love it. Can see 10-30x here even if 2026 is a bear.\n\n$UMBRA -> Again, ownership coins + think privacy will still rise in 2026 + will fill a hole in the Solana eco as soon as it launches. Can see 10x from here, but think it's more risky than avici because competition is fiercer\n\n$SOL -> Only chain that matters. ETH, I've been saying it for the last 2 years, is dying from a thousand cuts + Lots of adoption going on for SOL, feels like anything that happens in crypto eventually finds a way to happen in SOL. No-brainer 10x from here.\n\n$BTC -> OG, obligatory hold.\n\n$JLP -> Been holding it for 2.5 years now, and even though it has some (very) light exposure to ETH, I really like its model. Has unironically been my best performance this entire year while having the lowest volatility. I treat it almost as a stable-park-my-profits type of token", "createdAtTimestamp": 1766756445, "scoredAtTimestamp": 1767026969, "retweetCountAtCollection": 1, "favoriteCountAtCollection": 27, "replyCountAtCollection": 2, "quoteCountAtCollection": 0, "sentiment": 10, "alpha": 10, "legitimacy": 10, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "The tweet expresses extremely high conviction and enthusiasm for $AVICI, citing multiple strong positive factors (high founder drive, strong roadmap, relevant narrative, personal product usage) and predicting a significant 10-30x return even in a bear market. This represents an excellent alpha signal.", "tweetUrl": "https://x.com/gustloureiro/status/2004547937020289427", "userTrackRecordSignals": 3, "userTrackRecordUniqueTokens": 3, "userTrackRecordActiveDays": 1, "userTrackRecordFirstSignalDate": "2025-12-26", "userTrackRecordLastSignalDate": "2025-12-26", "userTrackRecordAccuracy24h": 50.0, "userTrackRecordAccuracy7d": null, "userTrackRecordAccuracy30d": null, "userTrackRecordAvgReturn24h": -2.43, "userTrackRecordAvgReturn7d": null, "userTrackRecordAvgReturn30d": null, "userTrackRecordBullishSignals": 3, "userTrackRecordBearishSignals": 0, "userTrackRecordAvgSentiment": 9.0, "userTrackRecordAvgAlpha": 8.33, "userTrackRecordPerformanceTier": "unproven" }, { "twitterHandle": "rkmtimes", "tokenSymbol": "GOLD", "text": "JUST IN🪙🇺🇸🔥Goldman Sachs says, $GOLD is unstoppable, it will reach $5000 per ounce by the beginning of Q1 in 2026.\n\n🔥#Gold just hit a record-high of $4500 after Goldman Sachs, Bank of America, and JP Morgan forecast prices rising to $5100 per ounce by December 2026.", "createdAtTimestamp": 1766726453, "scoredAtTimestamp": 1767026969, "retweetCountAtCollection": 3, "favoriteCountAtCollection": 17, "replyCountAtCollection": 0, "quoteCountAtCollection": 1, "sentiment": 10, "alpha": 10, "legitimacy": 10, "technicalAccuracy": 10, "isRecent": true, "isVerifiable": true, "scoresReasoning": "The tweet contains extremely positive language ('unstoppable', 'record-high') and high price targets ($5000, $5100) from major financial institutions regarding the token/asset 'GOLD'. This is a very strong bullish signal.", "tweetUrl": "https://x.com/rkmtimes/status/2004422141467676782", "userTrackRecordSignals": 3, "userTrackRecordUniqueTokens": 1, "userTrackRecordActiveDays": 3, "userTrackRecordFirstSignalDate": "2025-12-16", "userTrackRecordLastSignalDate": "2025-12-29", "userTrackRecordAccuracy24h": 100.0, "userTrackRecordAccuracy7d": 100.0, "userTrackRecordAccuracy30d": null, "userTrackRecordAvgReturn24h": 0.2, "userTrackRecordAvgReturn7d": 3.45, "userTrackRecordAvgReturn30d": null, "userTrackRecordBullishSignals": 2, "userTrackRecordBearishSignals": 1, "userTrackRecordAvgSentiment": 6.0, "userTrackRecordAvgAlpha": 7.0, "userTrackRecordPerformanceTier": "top_performer" } ] ``` This response returns 5 high-alpha cryptocurrency tweets with comprehensive scoring and user track record analysis. Note how each tweet receives perfect scores (10/10) across all metrics, indicating they've been identified as highly promising alpha signals. ### 2. Filter by Specific Token Filter alpha tweets to focus on a specific cryptocurrency token. ```bash curl -X GET "https://x402.cambrian.network/deep42/social-data/alpha-tweet-detection?limit=10&token_filter=BTC" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "bitcoinlfgo", "tokenSymbol": "BTC", "text": "💥 BREAKING \n\n$BTC BREAKS $90,000\n\nBULLS ARE BACKKKKK https://t.co/QDzTSL3JPh", "sentiment": 10, "alpha": 10, "legitimacy": 10, "technicalAccuracy": 10, "scoresReasoning": "The tweet uses strong positive language ('BREAKS', 'BULLS ARE BACKKKKK') and emoji ('💥') following a significant price milestone ($90,000), indicating extreme bullish sentiment and high relevance for BTC.", "userTrackRecordAccuracy30d": 71.0, "userTrackRecordPerformanceTier": "unproven" } ] ``` When filtering by token, you receive only tweets relevant to that specific cryptocurrency, allowing for focused alpha discovery and analysis. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) - pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start ```typescript import { Wallet } from 'ethers'; const wallet = new Wallet('YOUR_PRIVATE_KEY'); const response = await fetch('https://x402.cambrian.network/process', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: { role: 'user', parts: [{ kind: 'text', text: 'Get data' }], metadata: { target_endpoint: 'https://x402.cambrian.network/deep42/social-data/alpha-tweet-detection' // Optional: add query_params for filtering // query_params: { limit: 100, token_filter: "BTC" } } } }) }); ``` ### Payment Flow 1. Send request to gateway (no API key needed) 2. Gateway returns `402 Payment Required` with payment details 3. Sign EIP-712 payment authorization with your wallet 4. Resubmit request with signed payment 5. Gateway verifies payment and returns API response **Network**: Base (Ethereum L2) | **Price**: $0.05 USDC per request --- ## API Versioning This endpoint supports multiple API versions. Use the `Accept` header to request a specific version. ### Available Versions | Version | State | Default | Accept Header | |---------|-------|---------|---------------| | 2.0.0 | Current | Yes | `application/vnd.cambrian.deep42.social-data.alpha-tweet-detection.v2+json` | | 1.0.0 | Supported | No | `application/vnd.cambrian.deep42.social-data.alpha-tweet-detection.v1+json` | ### How to Request a Specific Version ```bash curl -X GET "https://x402.cambrian.network/deep42/social-data/alpha-tweet-detection" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Accept: application/vnd.cambrian.deep42.social-data.alpha-tweet-detection.v2+json" ``` ### Version Lifecycle - **Current**: Actively maintained and recommended for new integrations - **Deprecated**: Still functional but scheduled for removal (check `deprecated_at`) - **Sunset**: No longer available (returns `410 Gone`) **Note**: If no `Accept` header is specified, the default version (2.0.0) is returned. --- ## Cambrian API: Crypto Influencer Credibility Rankings **Endpoint:** /api/v1/deep42/social-data/influencer-credibility # Influencer Credibility ## Overview Returns cryptocurrency influencers ranked by a composite credibility score based on track record, prediction accuracy, and engagement metrics. The endpoint analyzes high-quality tweets to identify reliable crypto commentators, using directional price predictions (bullish/bearish) at hourly resolution to validate track record accuracy. ## Business Value - **Identify Reliable Voices**: Find the most credible cryptocurrency influencers based on comprehensive metrics including engagement, reach, and track record accuracy - **Track Record Analysis**: Analyze historical performance with directional price predictions measured at 24h, 7d, and 30d timeframes - **Performance-Based Filtering**: Filter influencers by activity level, token focus, and proven track records to find relevant voices for specific use cases - **Risk Assessment**: Evaluate influencer performance tiers (topPerformer >=70% accuracy, proven >=60%, unproven <60%) for informed decision making - **Social Intelligence**: Access detailed engagement metrics, reach data, and sentiment analysis to understand influencer impact and reliability ## Endpoint Details **URL**: ``` https://api.cambrian.org/deep42/social-data/influencer-credibility ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | min_tweets | integer | No | 5 | Minimum number of high-quality tweets required for inclusion (not follower count). Filters out influencers with insufficient track record. | | limit | integer | No | 25 | Maximum number of influencers to return (1-100). | | token_focus | string | No | - | Filter by specific token symbol (e.g., 'BTC', 'ETH', 'SOL'). Returns influencers who have tweeted about this token. | | sort_by | string | No | credibility | Sort results by specified metric. Options: `credibility`, `tweets`, `engagement`, `reach`, `alpha`, `accuracy`. | | order | string | No | desc | Sort direction: `asc` or `desc` (highest first). | | time_window | string | No | - | Filter influencers by recent activity window (e.g., `24h`, `48h`, `7d`, `30d`). | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | twitterHandle | String | Twitter username of the influencer | | avgViewsPerTweet | Number | Average views per high-quality tweet in the analysis window | | avgEngagementPerTweet | Number | Average engagement actions (likes + retweets + replies) per tweet in the analysis window | | credibilityScore | Number | Composite credibility score. Formula: (avg_views/50K)\*10 + (avg_alpha/10)\*5 + (avg_sentiment/10)\*2 + log(tweet_count+1)\*2. Unbounded, typically 5-300. >10 = credible, >50 = highly credible, >200 = top-tier | | influenceScore | Number | Influence score measuring reach-weighted engagement. Calculated as: (total_views / 1M) \* engagement_rate_percent. Unbounded, typically 0-50. >5 = significant, >20 = major influencer | | totalReach | Integer | Sum of views across all analyzed tweets in the time window | | tokensCovered | Integer | Number of distinct cryptocurrency tokens discussed in high-quality tweets during the analysis window | > **Note**: The response above reflects API version `v1`. Version `v2` (current default) adds additional track record fields (`trackRecordSignals`, `trackRecordAccuracy24h`, `trackRecordAccuracy7d`, `trackRecordAccuracy30d`, `trackRecordAvgReturn24h/7d/30d`, `trackRecordPerformanceTier`, etc.) for directional prediction performance. Request `v2` via the `Accept` header to receive these fields. ## Examples ### 1. Default Credibility Rankings Fetches the top influencers ranked by credibility score using default parameters (min 5 tweets, top 25 results). ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/influencer-credibility" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "blknoiz06", "avgViewsPerTweet": 129639.57, "avgEngagementPerTweet": 1616.36, "credibilityScore": 36.47, "influenceScore": 1.79, "totalReach": 1814954, "tokensCovered": 6 } ] ``` The top-ranked influencer by credibility score (`blknoiz06`) shows strong reach (1.8M total views) and covers 6 distinct tokens; a credibility score of 36.47 falls in the "highly credible" range. ### 2. Filter by Token Focus Returns influencers who have discussed Solana (SOL), limited to the top 5 results. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/influencer-credibility?token_focus=SOL&limit=5" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "solanafloor", "avgViewsPerTweet": 5010.89, "avgEngagementPerTweet": 56.19, "credibilityScore": 14.16, "influenceScore": 0.26, "totalReach": 265577, "tokensCovered": 1 }, { "twitterHandle": "degeneratenews", "avgViewsPerTweet": 24645, "avgEngagementPerTweet": 140.83, "credibilityScore": 13.69, "influenceScore": 0.07, "totalReach": 147870, "tokensCovered": 1 }, { "twitterHandle": "bscnews", "avgViewsPerTweet": 10186.73, "avgEngagementPerTweet": 39.73, "credibilityScore": 12.64, "influenceScore": 0.05, "totalReach": 152801, "tokensCovered": 1 }, { "twitterHandle": "cryptocurb", "avgViewsPerTweet": 2594.82, "avgEngagementPerTweet": 90.06, "credibilityScore": 11.58, "influenceScore": 0.12, "totalReach": 44112, "tokensCovered": 1 }, { "twitterHandle": "cryptosr_us", "avgViewsPerTweet": 7054.5, "avgEngagementPerTweet": 35.5, "credibilityScore": 11.36, "influenceScore": 0.02, "totalReach": 56436, "tokensCovered": 1 } ] ``` Filtering by `token_focus=SOL` returns influencers specifically discussing Solana, ranked by default credibility sort. All 5 results cover exactly 1 token, which points to specialized rather than generalist commentary. ## API Versioning This endpoint supports multiple API versions. Use the `Accept` header to request a specific version. ### Available Versions | Version | State | Default | Accept Header | |---------|-------|---------|---------------| | 2.0.0 | Current | Yes | `application/vnd.cambrian.deep42.social-data.influencer-credibility.v2+json` | | 1.0.0 | Current | No | `application/vnd.cambrian.deep42.social-data.influencer-credibility.v1+json` | ### How to Request a Specific Version ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/influencer-credibility" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Accept: application/vnd.cambrian.deep42.social-data.influencer-credibility.v2+json" ``` ### Version Lifecycle - **Current**: Actively maintained and recommended for new integrations - **Deprecated**: Still functional but scheduled for removal (check `deprecated_at`) - **Sunset**: No longer available (returns `410 Gone`) **Note**: If no `Accept` header is specified, the default version (2.0.0) is returned. --- ## Related Endpoints - `/deep42/social-data/alpha-tweet-detection` - Feed of tweets detected as having high alpha potential for cryptocurrency investments, scored on sentiment, alpha, legitimacy, and technical accuracy - `/deep42/social-data/sentiment-shifts` - Identifies tokens with significant sentiment changes that could signal market movements and trading opportunities - `/deep42/social-data/token-analysis` - Comprehensive social intelligence report for a cryptocurrency token with sentiment analysis - `/deep42/social-data/trending-momentum` - Identifies tokens with rapidly increasing social signals and momentum indicators --- ## Cambrian API: Crypto Influencer Credibility Rankings **Endpoint:** /api/v1/deep42/social-data/influencer-credibility # Influencer Credibility ## Overview Returns cryptocurrency influencers ranked by credibility score, track record, accuracy, and engagement metrics. Analyzes high-quality tweets to identify the most reliable voices in crypto. ## Business Value - **Credible Voice Discovery**: Identify the most reliable cryptocurrency influencers based on comprehensive credibility scoring that considers track record, accuracy, and engagement metrics - **Risk Mitigation**: Filter out unreliable sources by setting minimum quality thresholds (min_tweets) to ensure sufficient track record before inclusion - **Token-Specific Expertise**: Focus on influencers who specialize in specific cryptocurrencies using the token_focus parameter for targeted analysis - **Performance Analytics**: Access detailed track records including accuracy percentages, return metrics, and sentiment analysis to make informed decisions - **Flexible Sorting**: Customize rankings by different metrics (credibility, engagement, reach, alpha generation) to match your specific research or investment strategy ## Endpoint Details **URL**: ``` https://deep42.cambrian.network/deep42/social-data/influencer-credibility ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | min_tweets | integer | false | 5 | Minimum number of high-quality tweets required for inclusion (not follower count). Filters out influencers with insufficient track record. Range: 1-100 | | limit | integer | false | 25 | Maximum number of influencers to return. Range: 1-100 | | token_focus | string | false | - | Filter by specific token symbol (e.g., 'BTC', 'ETH', 'SOL'). Returns influencers who have tweeted about this token. Pattern: ^[A-Z0-9]{1,10}$ | | sort_by | string | false | credibility | Sort results by specified metric. Options: credibility, tweets, engagement, reach, alpha, accuracy | | order | string | false | desc | Sort direction. Options: asc, desc | | time_window | string | false | - | Filter influencers by recent activity. Returns only influencers who posted within the specified time window (e.g., '24h', '48h', '7d', '30d'). Pattern: ^[0-9]+[hd]$ | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | twitterHandle | string | Twitter username/handle of the influencer | | avgViewsPerTweet | number | Average number of views per tweet | | avgEngagementPerTweet | number | Average engagement (likes, retweets, replies) per tweet | | credibilityScore | number | Overall credibility score combining multiple factors | | influenceScore | number | Numerical score representing overall influence | | totalReach | number | Total reach across all tweets | | tokensCovered | integer | Number of different tokens the influencer has discussed | | trackRecordSignals | integer | Total number of trading signals/predictions made (null if insufficient data) | | trackRecordUniqueTokens | integer | Number of unique tokens in track record (null if insufficient data) | | trackRecordActiveDays | integer | Number of active days with signals (null if insufficient data) | | trackRecordFirstSignalDate | string | Date of first recorded signal (YYYY-MM-DD format, null if insufficient data) | | trackRecordLastSignalDate | string | Date of most recent signal (YYYY-MM-DD format, null if insufficient data) | | trackRecordAccuracy24h | number | Prediction accuracy over 24 hours (percentage, null if insufficient data) | | trackRecordAccuracy7d | number | Prediction accuracy over 7 days (percentage, null if insufficient data) | | trackRecordAccuracy30d | number | Prediction accuracy over 30 days (percentage, null if insufficient data) | | trackRecordAvgReturn24h | number | Average return of predictions over 24 hours (percentage, null if insufficient data) | | trackRecordAvgReturn7d | number | Average return of predictions over 7 days (percentage, null if insufficient data) | | trackRecordAvgReturn30d | number | Average return of predictions over 30 days (percentage, null if insufficient data) | | trackRecordBullishSignals | integer | Number of bullish signals given (null if insufficient data) | | trackRecordBearishSignals | integer | Number of bearish signals given (null if insufficient data) | | trackRecordAvgSentiment | number | Average sentiment score of signals (scale 1-10, null if insufficient data) | | trackRecordAvgAlpha | number | Average alpha generation score (scale 1-10, null if insufficient data) | | trackRecordPerformanceTier | string | Performance tier classification (null if insufficient data) | ## Examples ### 1. Top Credible Crypto Influencers This example demonstrates getting the most credible cryptocurrency influencers with a minimum track record threshold. ```bash curl -X GET "https://deep42.cambrian.network/deep42/social-data/influencer-credibility?limit=3&min_tweets=5" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "cobie", "avgViewsPerTweet": 1102953.43, "avgEngagementPerTweet": 11280.0, "credibilityScore": 226.39, "influenceScore": 7.0, "totalReach": 7720674, "tokensCovered": 1, "trackRecordSignals": null, "trackRecordUniqueTokens": null, "trackRecordActiveDays": null, "trackRecordFirstSignalDate": null, "trackRecordLastSignalDate": null, "trackRecordAccuracy24h": null, "trackRecordAccuracy7d": null, "trackRecordAccuracy30d": null, "trackRecordAvgReturn24h": null, "trackRecordAvgReturn7d": null, "trackRecordAvgReturn30d": null, "trackRecordBullishSignals": null, "trackRecordBearishSignals": null, "trackRecordAvgSentiment": null, "trackRecordAvgAlpha": null, "trackRecordPerformanceTier": null }, { "twitterHandle": "watcherguru", "avgViewsPerTweet": 394270.55, "avgEngagementPerTweet": 6012.91, "credibilityScore": 87.93, "influenceScore": 6.17, "totalReach": 4336976, "tokensCovered": 3, "trackRecordSignals": 59, "trackRecordUniqueTokens": 21, "trackRecordActiveDays": 48, "trackRecordFirstSignalDate": "2025-03-03", "trackRecordLastSignalDate": "2026-03-06", "trackRecordAccuracy24h": 58.1, "trackRecordAccuracy7d": 53.4, "trackRecordAccuracy30d": 55.9, "trackRecordAvgReturn24h": 1.28, "trackRecordAvgReturn7d": 12.61, "trackRecordAvgReturn30d": 2.11, "trackRecordBullishSignals": 52, "trackRecordBearishSignals": 7, "trackRecordAvgSentiment": 7.03, "trackRecordAvgAlpha": 6.93, "trackRecordPerformanceTier": "unproven" }, { "twitterHandle": "vitalikbuterin", "avgViewsPerTweet": 141308.21, "avgEngagementPerTweet": 1316.07, "credibilityScore": 37.25, "influenceScore": 1.56, "totalReach": 1978315, "tokensCovered": 3, "trackRecordSignals": 1, "trackRecordUniqueTokens": 1, "trackRecordActiveDays": 1, "trackRecordFirstSignalDate": "2026-02-18", "trackRecordLastSignalDate": "2026-02-18", "trackRecordAccuracy24h": null, "trackRecordAccuracy7d": 100.0, "trackRecordAccuracy30d": null, "trackRecordAvgReturn24h": null, "trackRecordAvgReturn7d": 0.07, "trackRecordAvgReturn30d": null, "trackRecordBullishSignals": 1, "trackRecordBearishSignals": 0, "trackRecordAvgSentiment": 9.0, "trackRecordAvgAlpha": 7.0, "trackRecordPerformanceTier": null } ] ``` The response shows three top-credible crypto influencers. "cobie" leads with the highest credibility score (226.39) and massive reach (over 1.1M average views per tweet). "watcherguru" has a substantial track record with 59 signals and detailed performance metrics. "vitalikbuterin" shows high-quality engagement despite lower volume, with perfect 7-day accuracy (100%). ### 2. Bitcoin-Focused Influencer Analysis This example demonstrates filtering for influencers who specifically discuss Bitcoin, sorted by engagement metrics. ```bash curl -X GET "https://deep42.cambrian.network/deep42/social-data/influencer-credibility?token_focus=BTC&sort_by=engagement&limit=5&min_tweets=10" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "twitterHandle": "cobie", "avgViewsPerTweet": 1102953.43, "avgEngagementPerTweet": 11280.0, "credibilityScore": 226.39, "influenceScore": 7.0, "totalReach": 7720674, "tokensCovered": 1, "trackRecordSignals": null, "trackRecordUniqueTokens": null, "trackRecordActiveDays": null, "trackRecordFirstSignalDate": null, "trackRecordLastSignalDate": null, "trackRecordAccuracy24h": null, "trackRecordAccuracy7d": null, "trackRecordAccuracy30d": null, "trackRecordAvgReturn24h": null, "trackRecordAvgReturn7d": null, "trackRecordAvgReturn30d": null, "trackRecordBullishSignals": null, "trackRecordBearishSignals": null, "trackRecordAvgSentiment": null, "trackRecordAvgAlpha": null, "trackRecordPerformanceTier": null }, { "twitterHandle": "watcherguru", "avgViewsPerTweet": 394270.55, "avgEngagementPerTweet": 6012.91, "credibilityScore": 87.93, "influenceScore": 6.17, "totalReach": 4336976, "tokensCovered": 3, "trackRecordSignals": 59, "trackRecordUniqueTokens": 21, "trackRecordActiveDays": 48, "trackRecordFirstSignalDate": "2025-03-03", "trackRecordLastSignalDate": "2026-03-06", "trackRecordAccuracy24h": 58.1, "trackRecordAccuracy7d": 53.4, "trackRecordAccuracy30d": 55.9, "trackRecordAvgReturn24h": 1.28, "trackRecordAvgReturn7d": 12.61, "trackRecordAvgReturn30d": 2.11, "trackRecordBullishSignals": 52, "trackRecordBearishSignals": 7, "trackRecordAvgSentiment": 7.03, "trackRecordAvgAlpha": 6.93, "trackRecordPerformanceTier": "unproven" }, { "twitterHandle": "vitalikbuterin", "avgViewsPerTweet": 141308.21, "avgEngagementPerTweet": 1316.07, "credibilityScore": 37.25, "influenceScore": 1.56, "totalReach": 1978315, "tokensCovered": 3, "trackRecordSignals": 1, "trackRecordUniqueTokens": 1, "trackRecordActiveDays": 1, "trackRecordFirstSignalDate": "2026-02-18", "trackRecordLastSignalDate": "2026-02-18", "trackRecordAccuracy24h": null, "trackRecordAccuracy7d": 100.0, "trackRecordAccuracy30d": null, "trackRecordAvgReturn24h": null, "trackRecordAvgReturn7d": 0.07, "trackRecordAvgReturn30d": null, "trackRecordBullishSignals": 1, "trackRecordBearishSignals": 0, "trackRecordAvgSentiment": 9.0, "trackRecordAvgAlpha": 7.0, "trackRecordPerformanceTier": null } ] ``` This query filters for Bitcoin-focused influencers with established track records (minimum 10 tweets) and ranks them by engagement metrics. The results would show influencers who have specifically discussed Bitcoin, sorted by their average engagement per tweet, helping identify the most engaging voices in the Bitcoin community.## API Versioning This endpoint supports multiple API versions. Use the `Accept` header to request a specific version. ### Available Versions | Version | State | Default | Accept Header | |---------|-------|---------|---------------| | 2.0.0 | Current | Yes | `application/vnd.cambrian.deep42.social-data.influencer-credibility.v2+json` | | 1.0.0 | Current | No | `application/vnd.cambrian.deep42.social-data.influencer-credibility.v1+json` | ### How to Request a Specific Version ```bash curl -X GET "https://deep42.cambrian.network/deep42/social-data/influencer-credibility" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Accept: application/vnd.cambrian.deep42.social-data.influencer-credibility.v2+json" ``` ### Version Lifecycle - **Current**: Actively maintained and recommended for new integrations - **Deprecated**: Still functional but scheduled for removal (check `deprecated_at`) - **Sunset**: No longer available (returns `410 Gone`) **Note**: If no `Accept` header is specified, the default version (2.0.0) is returned. --- ## Cambrian API: Detect major sentiment shifts in crypto tokens **Endpoint:** /api/v1/deep42/social-data/sentiment-shifts # Sentiment Shifts ## Overview Detects tokens with significant sentiment changes between a current period and a comparable previous period. This surfaces potential market-moving shifts in crypto Twitter discourse. The endpoint compares AI-assigned sentiment scores (0-10 per tweet) across time windows and only includes tokens with sufficient tweet volume in both periods for statistical relevance. ## Business Value - **Early Market Signal Detection**: Catch sentiment shifts before they translate to price movements, giving traders a potential timing advantage - **Risk Management**: Identify tokens experiencing bearish sentiment shifts that may warrant position adjustments or increased monitoring - **Portfolio Opportunity Discovery**: Find tokens with improving sentiment that could represent new investment opportunities - **Data-Driven Decision Making**: Replace gut feelings about market sentiment with quantified, statistical analysis of social media conversations - **Statistical Validation**: Only includes tokens with sufficient tweet volume in both periods for statistically relevant sentiment comparisons ## Endpoint Details **URL**: ``` https://api.cambrian.org/deep42/social-data/sentiment-shifts ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | comparison_period | string | No | 3d | Period to compare against. Enum: `24h`, `3d`, `7d` | | limit | integer | No | 20 | Number of tokens to return (maximum 50) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenSymbol | String | Cryptocurrency token symbol (e.g., BTC, ETH, SOL) | | sentimentShift | Number | Change in average sentiment between current and previous period (currentSentiment - previousSentiment). Range -10 to +10. Positive = bullish shift, negative = bearish shift. >2 = notable, >5 = major shift | | currentSentiment | Number | Average AI-assigned sentiment score across tweets in the current period (last 24 hours). Range 0-10 (0 = very bearish, 5 = neutral, 10 = very bullish). Minimum 3 tweets required | | previousSentiment | Number | Average AI-assigned sentiment score in the previous period (from comparison_period ago to 24h ago). Range 0-10. Minimum 2 tweets required | | currentPeriodTweets | Integer | Number of tweets about this token in the current period (last 24 hours) | | previousPeriodTweets | Integer | Number of tweets about this token in the previous period; used as denominator for volumeChange | | currentPeriodAuthors | Integer | Number of distinct authors discussing this token in the current period | | bullishRatio | Number | Percentage of current-period tweets with bullish sentiment (score >=6). Range 0-100. >60 = bullish majority, <40 = bearish majority | | volumeChange | Number | Ratio of current period tweet count to previous period. 1.0 = unchanged, 2.0 = doubled, 0.5 = halved. >1.5 = significant increase in discussion volume | | qualityScore | Number | Sum of average sentiment + average alpha for current period tweets. Range 0-20. >10 = above-average, >15 = high quality | | volatility | Number | Standard deviation of sentiment scores within the current period. Range 0-5. <1 = strong consensus, >2 = highly divided opinions | | confidenceScore | Number | Confidence in the detected shift: log(tweet_count + 1) * abs(sentiment_shift). >3 = moderate confidence, >5 = high confidence | | signalMagnitude | Number | Shift magnitude normalized by volatility: abs(sentiment_shift) / max(volatility, 1). >1 = shift exceeds normal variance, >2 = 2x normal variance | ## Examples ### 1. Default 3-Day Comparison Fetches the top 5 tokens with the most significant sentiment shifts using the default 3-day comparison window. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/sentiment-shifts?limit=5&comparison_period=3d" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "tokenSymbol": "WLD", "sentimentShift": 2.92, "currentSentiment": 8.67, "previousSentiment": 5.75, "currentPeriodTweets": 3, "previousPeriodTweets": 4, "currentPeriodAuthors": 3, "bullishRatio": 100, "volumeChange": 0.75, "qualityScore": 15.67, "volatility": 0.58, "confidenceScore": 4.04, "signalMagnitude": 2.92 }, { "tokenSymbol": "DOGE", "sentimentShift": -2.8, "currentSentiment": 6, "previousSentiment": 8.8, "currentPeriodTweets": 6, "previousPeriodTweets": 5, "currentPeriodAuthors": 6, "bullishRatio": 67, "volumeChange": 1.2, "qualityScore": 13.17, "volatility": 3.29, "confidenceScore": 5.45, "signalMagnitude": 0.85 }, { "tokenSymbol": "BNB", "sentimentShift": 2, "currentSentiment": 7.67, "previousSentiment": 5.67, "currentPeriodTweets": 3, "previousPeriodTweets": 3, "currentPeriodAuthors": 3, "bullishRatio": 100, "volumeChange": 1, "qualityScore": 14.67, "volatility": 0.58, "confidenceScore": 2.77, "signalMagnitude": 2 }, { "tokenSymbol": "ONDO", "sentimentShift": 1.25, "currentSentiment": 8.25, "previousSentiment": 7, "currentPeriodTweets": 8, "previousPeriodTweets": 14, "currentPeriodAuthors": 6, "bullishRatio": 100, "volumeChange": 0.57, "qualityScore": 15.25, "volatility": 1.04, "confidenceScore": 2.75, "signalMagnitude": 1.21 }, { "tokenSymbol": "BICO", "sentimentShift": -1, "currentSentiment": 7, "previousSentiment": 8, "currentPeriodTweets": 4, "previousPeriodTweets": 3, "currentPeriodAuthors": 4, "bullishRatio": 75, "volumeChange": 1.33, "qualityScore": 14, "volatility": 3.37, "confidenceScore": 1.61, "signalMagnitude": 0.3 } ] ``` WLD shows the strongest bullish shift (+2.92) with a fully bullish ratio (100%). DOGE shows a notable bearish shift (-2.8) with high volatility (3.29), which points to divided author sentiment despite the overall downward move. ### 2. Weekly Comparison Window Fetches the top 3 tokens using a 7-day comparison period, useful for spotting longer-term sentiment trend reversals rather than short-term noise. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/sentiment-shifts?limit=3&comparison_period=7d" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "tokenSymbol": "LDO", "sentimentShift": -4.33, "currentSentiment": 3.67, "previousSentiment": 8, "currentPeriodTweets": 3, "previousPeriodTweets": 2, "currentPeriodAuthors": 2, "bullishRatio": 33, "volumeChange": 1.5, "qualityScore": 11.33, "volatility": 2.08, "confidenceScore": 6.01, "signalMagnitude": 2.08 }, { "tokenSymbol": "CVX", "sentimentShift": -2.17, "currentSentiment": 6.33, "previousSentiment": 8.5, "currentPeriodTweets": 3, "previousPeriodTweets": 2, "currentPeriodAuthors": 3, "bullishRatio": 67, "volumeChange": 1.5, "qualityScore": 13.67, "volatility": 3.79, "confidenceScore": 3, "signalMagnitude": 0.57 }, { "tokenSymbol": "DASH", "sentimentShift": 2, "currentSentiment": 7, "previousSentiment": 5, "currentPeriodTweets": 4, "previousPeriodTweets": 7, "currentPeriodAuthors": 4, "bullishRatio": 75, "volumeChange": 0.57, "qualityScore": 14.25, "volatility": 3.37, "confidenceScore": 3.22, "signalMagnitude": 0.59 } ] ``` Over the 7-day window, LDO shows a major bearish shift (-4.33) with high confidence (6.01). This points to a substantial and statistically reliable sentiment reversal compared to the prior week. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key is required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/deep42/social-data/sentiment-shifts" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/deep42/social-data/sentiment-shifts") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/deep42/social-data/alpha-tweet-detection` - Feed of tweets scored for alpha potential, sentiment, legitimacy, and technical accuracy - `/deep42/social-data/influencer-credibility` - Cryptocurrency influencers ranked by credibility, track record, and accuracy - `/deep42/social-data/token-analysis` - Comprehensive social intelligence report for a single cryptocurrency token - `/deep42/social-data/trending-momentum` - Identifies tokens with rapidly increasing social signals and momentum indicators --- ## Cambrian API: Deep social analysis for a specific token **Endpoint:** /api/v1/deep42/social-data/token-analysis # Token Analysis ## Overview Comprehensive social intelligence report for a cryptocurrency token, combining sentiment analysis, engagement metrics, and sentiment-to-price correlation. Supports both a single aggregate snapshot (`granularity=total`) and time-series breakdowns (e.g. hourly or daily buckets) for trend analysis. ## Business Value - **Real-time Market Intelligence**: Access curated insights from 38K high-quality DeFi tweets to identify emerging trends and sentiment shifts - **Multi-dimensional Scoring**: Comprehensive analysis across sentiment, alpha potential, legitimacy, technical accuracy, and engagement metrics - **Investment Signal Detection**: Identify potential alpha opportunities through AI-scored social media analysis from credible sources - **Risk Assessment**: Evaluate content legitimacy and technical accuracy to filter out noise and misinformation - **Social Trading Insights**: Track engagement metrics and content previews to understand market discourse and community sentiment ## Endpoint Details **URL**: ``` https://api.cambrian.org/deep42/social-data/token-analysis ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_symbol | string | No | SOL | Token symbol to analyze (e.g. BTC, ETH, SOL). Defaults to SOL when omitted; in that case the response includes `tokenSymbolDefaulted=true`. | | days_back | integer | No | 7 | Number of days of history to analyze. Values are clamped to the range 1 to 730 (out-of-range values are silently clamped, not rejected). Non-integer values return a 400. | | granularity | string | No | total | Aggregation granularity. Use `total` for a single aggregate object, or a fixed bucket width expressed as `h` (hours) or `d` (days) for a time series, e.g. 1h, 4h, 6h, 1d, 7d, 30d. Supported range: 1h to 365d. Time-series buckets are returned most-recent first, up to 1000. | ## Response Field Descriptions ### Aggregate response (`granularity=total`) | Response Field | Type | Description | |---------------|------|-------------| | tokenSymbol | String | Token symbol analyzed | | totalTweets | Integer | Total high-quality tweets in the analysis period | | uniqueAuthors | Integer | Number of unique authors discussing this token | | avgSentiment | Number | Average sentiment score. Range 0-10. 0 = very bearish, 5 = neutral, 10 = very bullish | | avgAlpha | Number | Average alpha (novelty/actionability) score. Range 0-10 | | sentimentVolatility | Number | Standard deviation of sentiment scores. Range 0-5. <1 = strong consensus, >2 = highly divided opinions | | totalLikes | Integer | Total likes across all tweets | | totalRetweets | Integer | Total retweets across all tweets | | totalReplies | Integer | Total replies across all tweets | | totalViews | Integer | Total views across all tweets | | totalEngagement | Integer | Total engagement (likes + retweets + replies) | | engagementRate | Number | Engagement as a percentage of views: (likes + retweets + replies) / views * 100 | | avgLikesPerTweet | Number | Average likes per tweet | | avgRetweetsPerTweet | Number | Average retweets per tweet | | veryBullishTweets | Integer | Count of tweets with sentiment >= 8 | | bullishTweets | Integer | Count of tweets with sentiment 6-7.9 | | neutralTweets | Integer | Count of tweets with sentiment 4-5.9 | | bearishTweets | Integer | Count of tweets with sentiment < 4 | | veryBullishPct | Number | Percentage of very bullish tweets. Range 0-100 | | bullishPct | Number | Percentage of bullish tweets. Range 0-100 | | neutralPct | Number | Percentage of neutral tweets. Range 0-100 | | bearishPct | Number | Percentage of bearish tweets. Range 0-100 | | firstTweet | String | Timestamp of earliest tweet in the period | | latestTweet | String | Timestamp of most recent tweet in the period | | activeDays | Integer | Number of days with at least one tweet | | analysisPeriodDays | Integer | Total days covered by the analysis | | tokenSymbolDefaulted | Boolean | True when token_symbol was omitted and the analysis defaulted to SOL | | priceCorrelationBullishAccuracy24h/7d/30d | Number | % of bullish signals followed by a price increase after 24h/7d/30d | | priceCorrelationBearishAccuracy24h/7d/30d | Number | % of bearish signals followed by a price decrease after 24h/7d/30d | | priceCorrelationBullishAvgReturn24h/7d/30d | Number | Average % return after a bullish signal at each horizon | | priceCorrelationBearishAvgReturn24h/7d/30d | Number | Average % return after a bearish signal at each horizon | | priceCorrelationBullishSignals | Integer | Total bullish sentiment signals tracked over the trailing 90-day correlation window | | priceCorrelationBearishSignals | Integer | Total bearish sentiment signals tracked over the trailing 90-day correlation window | | priceCorrelationEnrichedSignals | Integer | Signals with completed price data | | priceCorrelationPendingSignals | Integer | Signals awaiting price data | | priceCorrelationFirstSignalDate | String | Earliest signal date (YYYY-MM-DD) | | priceCorrelationLastSignalDate | String | Latest signal date (YYYY-MM-DD) | ### Time-series response (`granularity != total`) | Response Field | Type | Description | |---------------|------|-------------| | tokenSymbol | String | Token symbol analyzed | | granularity | String | Echo of the requested (normalized) granularity, e.g. `1d` | | analysisPeriodDays | Integer | Days looked back | | tokenSymbolDefaulted | Boolean | True when token_symbol was omitted and the analysis defaulted to SOL | | bucketCount | Integer | Number of time buckets returned in this response | | maxBuckets | Integer | Maximum buckets returnable in a single response (row cap) | | truncated | Boolean | True when the oldest buckets were dropped due to the row cap | | timeseries[].timeBucket | String | Bucket start timestamp (inclusive), UTC | | timeseries[].tweetsCount | Integer | High-quality tweets in this bucket | | timeseries[].uniqueAuthors | Integer | Distinct authors in this bucket | | timeseries[].avgSentiment | Number | Average sentiment score for the bucket. Range 0-10 | | timeseries[].avgAlpha | Number | Average alpha score for the bucket. Range 0-10 | | timeseries[].totalLikes | Integer | Total likes in this bucket | | timeseries[].totalRetweets | Integer | Total retweets in this bucket | | timeseries[].totalReplies | Integer | Total replies in this bucket | | timeseries[].totalViews | Integer | Total views in this bucket | | timeseries[].veryBullish | Integer | Count of tweets with sentiment >= 8 | | timeseries[].bullish | Integer | Count of tweets with sentiment 6-7.9 | | timeseries[].neutral | Integer | Count of tweets with sentiment 4-5.9 | | timeseries[].bearish | Integer | Count of tweets with sentiment < 4 | ## Examples ### 1. Aggregate Social Analysis for a Major Token Fetches a single aggregate social intelligence snapshot for BTC over the last 7 days, including sentiment breakdown, engagement metrics, and sentiment-to-price correlation. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/token-analysis?token_symbol=BTC&days_back=7" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json { "tokenSymbol": "BTC", "totalTweets": 204, "uniqueAuthors": 118, "avgSentiment": 5.64, "avgAlpha": 7.09, "sentimentVolatility": 2.82, "totalLikes": 10769, "totalRetweets": 990, "totalReplies": 2252, "totalViews": 1321368, "totalEngagement": 14011, "engagementRate": 1.06, "avgLikesPerTweet": 52.8, "avgRetweetsPerTweet": 4.9, "veryBullishTweets": 84, "bullishTweets": 39, "neutralTweets": 17, "bearishTweets": 64, "veryBullishPct": 41.2, "bullishPct": 19.1, "neutralPct": 8.3, "bearishPct": 31.4, "firstTweet": "2026-07-28T07:39:27+00:00", "latestTweet": "2026-08-04T17:48:40+00:00", "activeDays": 8, "analysisPeriodDays": 7, "priceCorrelationBullishAccuracy24h": 49.8, "priceCorrelationBullishAccuracy7d": 36.4, "priceCorrelationBullishAccuracy30d": 35.3, "priceCorrelationBearishAccuracy24h": 51.5, "priceCorrelationBearishAccuracy7d": 65, "priceCorrelationBearishAccuracy30d": 62.9, "priceCorrelationBullishAvgReturn24h": -0.26, "priceCorrelationBullishAvgReturn7d": -1.97, "priceCorrelationBullishAvgReturn30d": -10.36, "priceCorrelationBearishAvgReturn24h": -0.37, "priceCorrelationBearishAvgReturn7d": -2.1, "priceCorrelationBearishAvgReturn30d": -9.08, "priceCorrelationBullishSignals": 14000, "priceCorrelationBearishSignals": 6843, "priceCorrelationEnrichedSignals": 19020, "priceCorrelationPendingSignals": 1823, "priceCorrelationFirstSignalDate": "2026-05-07", "priceCorrelationLastSignalDate": "2026-08-04" } ``` BTC shows mixed sentiment (avgSentiment 5.64/10) with high volatility (2.82), driven by a near-even split between very bullish (41.2%) and bearish (31.4%) tweets. Note that price-correlation metrics (priceCorrelationBullish*/Bearish*) are computed over a fixed trailing 90-day window and are not directly comparable to the 7-day totalTweets figure. ### 2. Daily Time-Series Sentiment for a Token Fetches daily sentiment and engagement buckets for SOL over the last 7 days, useful for tracking sentiment trends over time. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/token-analysis?token_symbol=SOL&days_back=7&granularity=1d" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json { "tokenSymbol": "SOL", "granularity": "1d", "analysisPeriodDays": 7, "bucketCount": 8, "maxBuckets": 1000, "truncated": false, "timeseries": [ { "timeBucket": "2026-08-04 00:00:00+00", "tweetsCount": 22, "uniqueAuthors": 19, "avgSentiment": 8.27, "avgAlpha": 7.32, "totalLikes": 1115, "totalRetweets": 95, "totalReplies": 339, "totalViews": 140462, "veryBullish": 19, "bullish": 3, "neutral": 0, "bearish": 0 }, { "timeBucket": "2026-08-03 00:00:00+00", "tweetsCount": 25, "uniqueAuthors": 19, "avgSentiment": 8.04, "avgAlpha": 7.68, "totalLikes": 1726, "totalRetweets": 193, "totalReplies": 252, "totalViews": 140049, "veryBullish": 19, "bullish": 6, "neutral": 0, "bearish": 0 }, { "timeBucket": "2026-08-02 00:00:00+00", "tweetsCount": 10, "uniqueAuthors": 10, "avgSentiment": 7.5, "avgAlpha": 7.2, "totalLikes": 195, "totalRetweets": 10, "totalReplies": 85, "totalViews": 9158, "veryBullish": 9, "bullish": 0, "neutral": 0, "bearish": 1 }, { "timeBucket": "2026-08-01 00:00:00+00", "tweetsCount": 4, "uniqueAuthors": 4, "avgSentiment": 8.75, "avgAlpha": 7, "totalLikes": 162, "totalRetweets": 25, "totalReplies": 63, "totalViews": 24726, "veryBullish": 4, "bullish": 0, "neutral": 0, "bearish": 0 }, { "timeBucket": "2026-07-31 00:00:00+00", "tweetsCount": 8, "uniqueAuthors": 7, "avgSentiment": 7.5, "avgAlpha": 7, "totalLikes": 577, "totalRetweets": 42, "totalReplies": 212, "totalViews": 47325, "veryBullish": 6, "bullish": 1, "neutral": 0, "bearish": 1 }, { "timeBucket": "2026-07-30 00:00:00+00", "tweetsCount": 25, "uniqueAuthors": 22, "avgSentiment": 8.32, "avgAlpha": 7.28, "totalLikes": 2234, "totalRetweets": 409, "totalReplies": 631, "totalViews": 194881, "veryBullish": 21, "bullish": 4, "neutral": 0, "bearish": 0 }, { "timeBucket": "2026-07-29 00:00:00+00", "tweetsCount": 22, "uniqueAuthors": 20, "avgSentiment": 8.23, "avgAlpha": 7.32, "totalLikes": 433, "totalRetweets": 43, "totalReplies": 216, "totalViews": 46045, "veryBullish": 20, "bullish": 1, "neutral": 0, "bearish": 1 }, { "timeBucket": "2026-07-28 00:00:00+00", "tweetsCount": 16, "uniqueAuthors": 12, "avgSentiment": 8.19, "avgAlpha": 7.13, "totalLikes": 687, "totalRetweets": 98, "totalReplies": 120, "totalViews": 68401, "veryBullish": 12, "bullish": 4, "neutral": 0, "bearish": 0 } ] } ``` SOL shows consistently strong bullish sentiment across all 8 daily buckets (avgSentiment ranging 7.5-8.75/10), with almost no bearish activity — contrasting with BTC's more divided sentiment in Example 1. `truncated: false` confirms all requested days fit within the 1000-bucket cap. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/deep42/social-data/token-analysis" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/deep42/social-data/token-analysis") # Optional: add query_params for filtering # query_params: { limit: 100 } print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/deep42/social-data/alpha-tweet-detection` - Feed of tweets detected as having high alpha potential for cryptocurrency investments, scored on sentiment, alpha, legitimacy, and technical accuracy. - `/deep42/social-data/influencer-credibility` - Returns cryptocurrency influencers ranked by credibility score, track record, accuracy, and engagement metrics. - `/deep42/social-data/sentiment-shifts` - Identifies tokens with significant sentiment changes that could signal market movements and trading opportunities. --- ## Cambrian API: Detect trending tokens with social momentum **Endpoint:** /api/v1/deep42/social-data/trending-momentum # Trending Momentum ## Overview Detects tokens with rapidly increasing social signals by measuring the rate of change in tweet volume, engagement, and quality. It returns a composite momentum score that highlights tokens accelerating in social attention, either as a single aggregate ranking or as a time series of momentum changes across time buckets. ## Business Value - **Early Market Detection**: Identify tokens gaining social traction before mainstream adoption, providing alpha opportunities for traders and analysts - **Social Sentiment Analysis**: Track sentiment changes and social momentum patterns to gauge market mood and potential price movements - **Risk Assessment**: Use quality scores and author diversity metrics to evaluate the authenticity and reliability of social signals - **Portfolio Optimization**: Incorporate social momentum data into trading strategies to enhance timing and position sizing decisions - **Trend Validation**: Confirm technical analysis signals with social momentum indicators for more robust trading decisions ## Endpoint Details **URL**: ``` https://api.cambrian.org/deep42/social-data/trending-momentum ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | lookback_hours | integer | No | 24 | Hours to look back for trend detection (min 1, max 168) | | min_velocity | number | No | 0.3 | Minimum velocity score (rate of change) | | limit | integer | No | 15 | Number of trending tokens to return (max 50) | | granularity | string | No | total | Time granularity for momentum analysis. `total` returns a single aggregate momentum ranking. Other values (`1h`, `3h`, `6h`, `12h`, `24h`, `1d`, `3d`, `7d`, `30d`) return time-series momentum data (max 1000 rows) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenSymbol | String | Token symbol | | recentTweets | Integer | Recent tweet count in the lookback window | | uniqueAuthors | Integer | Number of unique authors discussing this token | | sentiment | Number | Average sentiment score. Range 0-10. 0 = very bearish, 5 = neutral, 10 = very bullish | | qualityScore | Number | Average quality of tweets based on author credibility and content depth. Range 0-10. >7 = high quality | | qualityDelta | Number | Change in quality score relative to the prior period | | totalReach | Integer | Total views across all tweets in the window | | tweetVelocity | Number | Rate of tweet volume change as a multiplier. 1.0 = flat, 2.0 = doubled. >1.5 = strong acceleration | | engagementVelocity | Number | Rate of engagement change as a multiplier. 1.0 = flat, 2.0 = doubled. >1.5 = strong acceleration | | momentumScore | Number | Composite momentum score combining velocity, volume, and quality. Unbounded, typically 0-100. >10 = trending, >50 = viral momentum | ## Examples ### 1. Default Aggregate Momentum Ranking Fetches the top trending tokens by composite momentum score over the default 24-hour lookback window, using the default `total` granularity. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/trending-momentum" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "tokenSymbol": "HOME", "recentTweets": 10, "uniqueAuthors": 8, "sentiment": 7.3, "qualityScore": 14.5, "qualityDelta": 0.5, "totalReach": 43354, "tweetVelocity": 3.25, "engagementVelocity": 32.9, "momentumScore": 503.16 }, { "tokenSymbol": "STX", "recentTweets": 7, "uniqueAuthors": 6, "sentiment": 8.71, "qualityScore": 16, "qualityDelta": 1, "totalReach": 6887, "tweetVelocity": 2.5, "engagementVelocity": 25.71, "momentumScore": 353.5 }, { "tokenSymbol": "SEI", "recentTweets": 4, "uniqueAuthors": 3, "sentiment": 7.5, "qualityScore": 14.75, "qualityDelta": 0, "totalReach": 20386, "tweetVelocity": 2.33, "engagementVelocity": 54.5, "momentumScore": 341.5 }, { "tokenSymbol": "LINK", "recentTweets": 27, "uniqueAuthors": 20, "sentiment": 8.48, "qualityScore": 16.07, "qualityDelta": 0.79, "totalReach": 114420, "tweetVelocity": 1.76, "engagementVelocity": 60.04, "momentumScore": 330.4 }, { "tokenSymbol": "SATUSD", "recentTweets": 3, "uniqueAuthors": 3, "sentiment": 9, "qualityScore": 16, "qualityDelta": 0, "totalReach": 11156, "tweetVelocity": 2, "engagementVelocity": 78.67, "momentumScore": 298.23 }, { "tokenSymbol": "HEI", "recentTweets": 3, "uniqueAuthors": 3, "sentiment": 8.67, "qualityScore": 16, "qualityDelta": 0, "totalReach": 7081, "tweetVelocity": 2, "engagementVelocity": 22, "momentumScore": 283.69 }, { "tokenSymbol": "DOGE", "recentTweets": 5, "uniqueAuthors": 5, "sentiment": 5.6, "qualityScore": 12.8, "qualityDelta": -3.2, "totalReach": 54726, "tweetVelocity": 2, "engagementVelocity": 110, "momentumScore": 279.3 }, { "tokenSymbol": "RENDER", "recentTweets": 6, "uniqueAuthors": 5, "sentiment": 8.83, "qualityScore": 16.17, "qualityDelta": 0.17, "totalReach": 5350, "tweetVelocity": 1.8, "engagementVelocity": 28.33, "momentumScore": 249.82 }, { "tokenSymbol": "TRX", "recentTweets": 3, "uniqueAuthors": 3, "sentiment": 8.33, "qualityScore": 15.33, "qualityDelta": 0, "totalReach": 2890, "tweetVelocity": 2, "engagementVelocity": 11, "momentumScore": 244.39 }, { "tokenSymbol": "RLUSD", "recentTweets": 6, "uniqueAuthors": 6, "sentiment": 8.33, "qualityScore": 15.5, "qualityDelta": 1, "totalReach": 5996, "tweetVelocity": 1.8, "engagementVelocity": 15, "momentumScore": 242.7 } ] ``` `HOME` leads the ranking with a momentum score of 503.16, driven by a 3.25x tweet velocity and 32.9x engagement velocity spike relative to the prior window — a strong signal of accelerating social attention. ### 2. Daily Time-Series Granularity Requests momentum data with `granularity=1d` and `limit=5` to view daily momentum evolution instead of a single aggregate ranking. ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/trending-momentum?granularity=1d&limit=5" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "tokenSymbol": "LINK", "recentTweets": 0, "uniqueAuthors": 7, "sentiment": 8.44, "qualityScore": 16.11, "qualityDelta": 0, "totalReach": 68953, "tweetVelocity": 9, "engagementVelocity": 4.64, "momentumScore": 154.99 }, { "tokenSymbol": "INJ", "recentTweets": 0, "uniqueAuthors": 1, "sentiment": 8.25, "qualityScore": 15.63, "qualityDelta": 0, "totalReach": 314, "tweetVelocity": 8, "engagementVelocity": 3.94, "momentumScore": 125.08 }, { "tokenSymbol": "BTC", "recentTweets": 0, "uniqueAuthors": 6, "sentiment": 5.17, "qualityScore": 12.33, "qualityDelta": 0, "totalReach": 8864, "tweetVelocity": 6, "engagementVelocity": 22.6, "momentumScore": 74.64 } ] ``` With daily granularity, `tweetVelocity` compares each day's tweet count to the previous day rather than a single aggregate window, so tokens like `LINK` show a 9x day-over-day tweet velocity even with fewer tokens recorded as "recent" in this particular slice. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/deep42/social-data/trending-momentum" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/deep42/social-data/trending-momentum") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## API Versioning This endpoint supports multiple API versions. Use the `Accept` header to request a specific version. ### Available Versions | Version | State | Default | Accept Header | |---------|-------|---------|---------------| | 1.1.0 | Current | Yes | `application/vnd.cambrian.deep42.social-data.trending-momentum.v1+json` | | 1.0.0 | Current | No | `application/vnd.cambrian.deep42.social-data.trending-momentum.v1+json` | ### How to Request a Specific Version ```bash curl -X GET "https://api.cambrian.org/deep42/social-data/trending-momentum" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Accept: application/vnd.cambrian.deep42.social-data.trending-momentum.v1+json" ``` ### Version Lifecycle - **Current**: Actively maintained and recommended for new integrations - **Deprecated**: Still functional but scheduled for removal (check `deprecated_at`) - **Sunset**: No longer available (returns `410 Gone`) **Note**: If no `Accept` header is specified, the default version (1.1.0) is returned. --- ## Related Endpoints - `/deep42/social-data/alpha-tweet-detection` - Feed of tweets detected as having high alpha potential for cryptocurrency investments, scored across sentiment, alpha, legitimacy, and technical accuracy. - `/deep42/social-data/sentiment-shifts` - Identifies tokens with significant sentiment changes that could signal market movements and trading opportunities. - `/deep42/social-data/token-analysis` - Comprehensive social intelligence report for a cryptocurrency token with sentiment analysis. - `/deep42/social-data/influencer-credibility` - Returns cryptocurrency influencers ranked by credibility score, track record, accuracy, and engagement metrics. --- ## Cambrian API: Detect trending tokens with social momentum **Endpoint:** /api/v1/deep42/social-data/trending-momentum # Trending Momentum ## Overview Identifies tokens with rapidly increasing social signals and momentum indicators. Detects tokens showing significant velocity changes in tweet activity, engagement, and overall social momentum. ## Business Value - **Real-time Trend Detection**: Identify tokens gaining social momentum before they reach mainstream awareness - **Quantitative Social Metrics**: Access precise momentum scores, tweet velocity, and engagement rates for data-driven decisions - **Customizable Time Windows**: Configure lookback periods from 1 hour to 7 days to match trading strategies - **Quality-Filtered Results**: Focus on high-quality social activity with minimum velocity thresholds and author diversity metrics - **Time-Series Analysis**: Track momentum evolution over time with granular time-series data for pattern recognition ## Endpoint Details **URL**: ``` https://deep42.cambrian.network/deep42/social-data/trending-momentum ``` **Method**: GET **Authentication**: Required via `X-API-KEY` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | lookback_hours | integer | No | 24 | Hours to look back for trend detection (1-168) | | min_velocity | number | No | 0.3 | Minimum velocity score (rate of change) | | limit | integer | No | 15 | Number of trending tokens to return (max 50) | | granularity | string | No | total | Time granularity: 'total' for aggregate ranking, or time-series values (1h, 3h, 6h, 12h, 24h, 1d, 3d, 7d, 30d) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenSymbol | string | Token symbol (e.g., "XRP", "BTC", "TAO") | | recentTweets | integer | Number of recent tweets in the lookback period | | uniqueAuthors | integer | Number of unique authors contributing to the conversation | | sentiment | number | Average sentiment score of tweets (scale varies) | | qualityScore | number | Overall quality score of social activity | | qualityDelta | number | Change in quality score compared to previous period | | totalReach | integer | Total audience reach across all tweets | | tweetVelocity | number | Rate of tweet increase (velocity metric) | | engagementVelocity | number | Rate of engagement increase (velocity metric) | | momentumScore | number | Combined momentum score ranking tokens by trending strength | ## Examples ### 1. Default Trending Momentum Query Retrieves the top 15 trending tokens with default settings (24-hour lookback, minimum velocity 0.3). ```bash curl -X GET "https://x402.cambrian.network/deep42/social-data/trending-momentum" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "tokenSymbol": "XRP", "recentTweets": 15, "uniqueAuthors": 4, "sentiment": 7.13, "qualityScore": 13.93, "qualityDelta": -0.42, "totalReach": 132104, "tweetVelocity": 0.75, "engagementVelocity": 153.53, "momentumScore": 123.22 }, { "tokenSymbol": "BTC", "recentTweets": 9, "uniqueAuthors": 7, "sentiment": 6.89, "qualityScore": 14.11, "qualityDelta": -1.1, "totalReach": 25802, "tweetVelocity": 0.64, "engagementVelocity": 80.11, "momentumScore": 92.15 }, { "tokenSymbol": "TAO", "recentTweets": 3, "uniqueAuthors": 3, "sentiment": 8.67, "qualityScore": 16.67, "qualityDelta": -0.5, "totalReach": 6412, "tweetVelocity": 0.5, "engagementVelocity": 50.33, "momentumScore": 73.05 } ] ``` This response shows XRP leading with the highest momentum score (123.22) driven by strong engagement velocity (153.53) and significant total reach (132,104), while maintaining moderate tweet velocity (0.75). ### 2. High-Velocity Filter with Extended Lookback Finds tokens with strong momentum using a higher velocity threshold and 48-hour lookback period to capture more sustained trends. ```bash curl -X GET "https://x402.cambrian.network/deep42/social-data/trending-momentum?min_velocity=0.8&lookback_hours=48&limit=10" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "tokenSymbol": "XRP", "recentTweets": 15, "uniqueAuthors": 4, "sentiment": 7.13, "qualityScore": 13.93, "qualityDelta": -0.42, "totalReach": 132104, "tweetVelocity": 0.75, "engagementVelocity": 153.53, "momentumScore": 123.22 }, { "tokenSymbol": "BTC", "recentTweets": 9, "uniqueAuthors": 7, "sentiment": 6.89, "qualityScore": 14.11, "qualityDelta": -1.1, "totalReach": 25802, "tweetVelocity": 0.64, "engagementVelocity": 80.11, "momentumScore": 92.15 }, { "tokenSymbol": "TAO", "recentTweets": 3, "uniqueAuthors": 3, "sentiment": 8.67, "qualityScore": 16.67, "qualityDelta": -0.5, "totalReach": 6412, "tweetVelocity": 0.5, "engagementVelocity": 50.33, "momentumScore": 73.05 } ] ``` With higher velocity filtering and extended lookback, this query identifies tokens with more sustained momentum patterns rather than short-term spikes. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.network/deep42/social-data/trending-momentum" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.network/deep42/social-data/trending-momentum") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## API Versioning This endpoint supports multiple API versions. Use the `Accept` header to request a specific version. ### Available Versions | Version | State | Default | Accept Header | |---------|-------|---------|---------------| | 1.1.0 | Current | Yes | `application/vnd.cambrian.deep42.social-data.trending-momentum.v1+json` | | 1.0.0 | Current | No | `application/vnd.cambrian.deep42.social-data.trending-momentum.v1+json` | ### How to Request a Specific Version ```bash curl -X GET "https://x402.cambrian.network/deep42/social-data/trending-momentum" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Accept: application/vnd.cambrian.deep42.social-data.trending-momentum.v1+json" ``` ### Version Lifecycle - **Current**: Actively maintained and recommended for new integrations - **Deprecated**: Still functional but scheduled for removal (check `deprecated_at`) - **Sunset**: No longer available (returns `410 Gone`) **Note**: If no `Accept` header is specified, the default version (1.1.0) is returned. --- ## Related Endpoints - `/deep42/social-data/alpha-tweet-detection` - Detects high-quality alpha tweets with trading signals pi/v1/deep42/discovery/search-projects` - Searches cryptocurrency projects using various criteria/d pi/v1/deep42/social-data/influencer-credibility` - Analyzes influence and credibility of social media accounts/d pi/v1/deep42/social-data/token-analysis` - Comprehensive token analysis combining social and market metrics/d pi/v1/deep42/social-data/sentiment-shifts` - Monitors sentiment changes across cryptocurrency discussions/d pi/v1/deep42/social-data/alpha-tweet-detection` - Detects high-quality alpha tweets with trading signals/d - `/deep42/social-data/sentiment-shifts` - Monitors sentiment changes across cryptocurrency discussions pi/v1/deep42/discovery/search-projects` - Searches cryptocurrency projects using various criteria/d pi/v1/deep42/social-data/influencer-credibility` - Analyzes influence and credibility of social media accounts/d pi/v1/deep42/social-data/token-analysis` - Comprehensive token analysis combining social and market metrics/d pi/v1/deep42/social-data/sentiment-shifts` - Monitors sentiment changes across cryptocurrency discussions/d pi/v1/deep42/social-data/alpha-tweet-detection` - Detects high-quality alpha tweets with trading signals/d - `/deep42/social-data/token-analysis` - Comprehensive token analysis combining social and market metrics pi/v1/deep42/discovery/search-projects` - Searches cryptocurrency projects using various criteria/d pi/v1/deep42/social-data/influencer-credibility` - Analyzes influence and credibility of social media accounts/d pi/v1/deep42/social-data/token-analysis` - Comprehensive token analysis combining social and market metrics/d pi/v1/deep42/social-data/sentiment-shifts` - Monitors sentiment changes across cryptocurrency discussions/d pi/v1/deep42/social-data/alpha-tweet-detection` - Detects high-quality alpha tweets with trading signals/d - `/deep42/social-data/influencer-credibility` - Analyzes influence and credibility of social media accounts pi/v1/deep42/discovery/search-projects` - Searches cryptocurrency projects using various criteria/d pi/v1/deep42/social-data/influencer-credibility` - Analyzes influence and credibility of social media accounts/d pi/v1/deep42/social-data/token-analysis` - Comprehensive token analysis combining social and market metrics/d pi/v1/deep42/social-data/sentiment-shifts` - Monitors sentiment changes across cryptocurrency discussions/d pi/v1/deep42/social-data/alpha-tweet-detection` - Detects high-quality alpha tweets with trading signals/d - `/deep42/discovery/search-projects` - Searches cryptocurrency projects using various criteria pi/v1/deep42/discovery/search-projects` - Searches cryptocurrency projects using various criteria/d pi/v1/deep42/social-data/influencer-credibility` - Analyzes influence and credibility of social media accounts/d pi/v1/deep42/social-data/token-analysis` - Comprehensive token analysis combining social and market metrics/d pi/v1/deep42/social-data/sentiment-shifts` - Monitors sentiment changes across cryptocurrency discussions/d pi/v1/deep42/social-data/alpha-tweet-detection` - Detects high-quality alpha tweets with trading signals/d --- ## Cambrian API: V2 - Fee Metrics **Endpoint:** /api/v1/evm/aero/v2/fee-metrics # Aerodrome V2 Fee Metrics ## Overview Returns fee metrics and daily historical fee/volume data for a specific Aerodrome V2 pool over the previous seven completed UTC days. USD-denominated fields are returned as `null` when a required pool-token price is unavailable. ## Business Value - **Pool Performance Analysis**: Track fee generation efficiency and profitability of liquidity pools over time - **Yield Optimization**: Monitor fee APR to make informed decisions about liquidity provision strategies - **Historical Insights**: Access detailed historical fee data to understand trends and patterns in pool activity - **Risk Assessment**: Evaluate pool stability and fee consistency for investment decision making - **Competitive Analysis**: Compare fee metrics across different pools to identify the most profitable opportunities ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/aero/v2/fee-metrics ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | pool_address | string | Yes | - | Pool address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolId | String | Pool contract address (0x-prefixed) | | feeTier | UInt256 | Pool fee tier | | timeframeAt | String | Timeframe label for the aggregated metrics (e.g., "7d") | | feeMetrics | Map(String,Nullable(String)) | Aggregate fee metrics for the timeframe: `feeAPR` (fee-based annual percentage rate), `feeVolumeRatio` (fees as a fraction of volume), `feesToken0` / `feesToken1` (fees accrued in each pool token), `feesUsd` (total fees in USD, null when a token price is unavailable) | | historicalFees | Array(Map(String,Nullable(Float64))) | Daily entries for the previous seven completed UTC days, each with `feeVolumeRatio`, `feesUsd` (null when a token price is unavailable), `timestamp` (Unix seconds for the day), and `volume` (trading volume in USD) | | updatedAt | UInt32 | Unix timestamp (seconds) when the record was last updated | | tvlPriceComplete | UInt8 | 1 if all token prices needed for USD calculations were available, 0 otherwise | ## Examples ### 1. Fetch Fee Metrics for a Pool Retrieves fee metrics and the seven-day historical fee/volume series for a specific Aerodrome V2 pool on Base. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v2/fee-metrics?pool_address=0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolId", "type": "String" }, { "name": "feeTier", "type": "UInt256" }, { "name": "timeframeAt", "type": "String" }, { "name": "feeMetrics", "type": "Map(String,Nullable(String))" }, { "name": "historicalFees", "type": "Array(Map(String,Nullable(Float64)))" }, { "name": "updatedAt", "type": "UInt32" }, { "name": "tvlPriceComplete", "type": "UInt8" } ], "data": [ [ "0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "30", "7d", { "feeAPR": "5.037095", "feeVolumeRatio": "0.003", "feesToken0": "11762.110525473", "feesToken1": "30350.903844302637", "feesUsd": "24301.576865" }, [ { "feeVolumeRatio": 0.003, "feesUsd": 6546.220184, "timestamp": 1785283200, "volume": 2182073.394557 }, { "feeVolumeRatio": 0.003, "feesUsd": 4638.387547, "timestamp": 1785369600, "volume": 1546129.182205 }, { "feeVolumeRatio": 0.003, "feesUsd": 2244.425888, "timestamp": 1785456000, "volume": 748141.962749 }, { "feeVolumeRatio": 0.003, "feesUsd": 1528.679329, "timestamp": 1785542400, "volume": 509559.776427 }, { "feeVolumeRatio": 0.003, "feesUsd": 3464.647679, "timestamp": 1785628800, "volume": 1154882.559784 }, { "feeVolumeRatio": 0.003, "feesUsd": 2277.916267, "timestamp": 1785715200, "volume": 759305.422461 }, { "feeVolumeRatio": 0.003, "feesUsd": 3601.29997, "timestamp": 1785801600, "volume": 1200433.323441 } ], 1785904200, 1 ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. The pool has a 0.3% fee tier (`feeTier: "30"`), a 7-day fee APR of ~5.04%, and complete pricing (`tvlPriceComplete: 1`), so all `feesUsd` values are populated across the daily history. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/aero/v2/fee-metrics" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/aero/v2/fee-metrics") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /evm/aero/v2/pool - Get information for a specific Aerodrome V2 pool. Usd prices, valuations, and APRs are null when a required price is unavailable. - /evm/aero/v2/pool-volume - Shows recent pool activity and hourly distribution. Usd fields are null when a pool-token price is unavailable. - /evm/aero/v2/pools - Returns liquidity pools with summary metrics for the previous 7 completed UTC days. Usd prices, valuations, and APRs are null when a required price is unavailable. - /evm/aero/v2/provider-summary - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics. Portfolio-wide Usd aggregates and weighted APRs are null if any represented position cannot be fully priced; per-pool and per-token values are nullable independently. --- ## Cambrian API: V2 - Pool Info **Endpoint:** /api/v1/evm/aero/v2/pool # Aerodrome V2 Pool Info ## Overview Returns detailed information for a specific Aerodrome V2 liquidity pool on Base, including token reserves, TVL, and USD-denominated fees, rewards, bribes, and APR breakdowns. USD prices, valuations, and APRs are null when a required token price is unavailable. ## Business Value - **Pool Analytics**: Access detailed metrics including TVL, reserves, and APR to analyze pool performance and profitability - **Risk Assessment**: Evaluate pool composition with token balances, prices, and reserve ratios for informed investment decisions - **Yield Optimization**: Compare APR breakdowns (swap fees, rewards, bribes) to identify highest-yielding liquidity opportunities - **Portfolio Management**: Monitor pool positions with real-time pricing and reserve data for active liquidity management - **Trading Intelligence**: Understand pool depth and composition to optimize trade execution and slippage management ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/aero/v2/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. Only 8453 (Base) is supported. | | pool_address | string | Yes | - | Pool address with 0x prefix, e.g. `0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d`. | | apr_days_annualized | integer | Yes | - | Number of previous completed UTC days to calculate APR from (1-30). 7 annualizes activity from the previous 7 completed UTC days. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolAddress | String | Address of the liquidity pool. | | token0Address | String | Contract address of token0 in the pair. | | token0Symbol | String | Symbol of token0. | | token0Name | String | Name of token0. | | token0Decimals | UInt8 | Decimal precision of token0. | | token1Address | String | Contract address of token1 in the pair. | | token1Symbol | String | Symbol of token1. | | token1Name | String | Name of token1. | | token1Decimals | UInt8 | Decimal precision of token1. | | reserve0 | Int256 | Raw on-chain reserve of token0 (in token0's smallest unit). | | reserve1 | Int256 | Raw on-chain reserve of token1 (in token1's smallest unit). | | tvlToken0 | Float64 | Reserve of token0 adjusted for decimals. | | tvlToken1 | Float64 | Reserve of token1 adjusted for decimals. | | token0PriceUsd | Nullable(Float64) | USD price of token0. Null when unavailable. | | token1PriceUsd | Nullable(Float64) | USD price of token1. Null when unavailable. | | tvlUsd | Nullable(Float64) | Total value locked in USD. Null when a required token price is unavailable. | | feesXdUsd | Nullable(Float64) | Swap fees earned in USD over the annualization window. Null when a required price is unavailable. | | aeroRewardsXdUsd | Nullable(Float64) | AERO emission rewards earned in USD over the annualization window. Null when a required price is unavailable. | | bribesXdUsd | Nullable(Float64) | Bribe rewards earned in USD over the annualization window. Null when a required price is unavailable. | | swapFeeAPR | Nullable(Float64) | Annualized percentage return from swap fees. Null when a required price is unavailable. | | aeroRewardAPR | Nullable(Float64) | Annualized percentage return from AERO emission rewards. Null when a required price is unavailable. | | bribeFeeAPR | Nullable(Float64) | Annualized percentage return from bribes. Null when a required price is unavailable. | | totalAPR | Nullable(Float64) | Combined annualized percentage return across swap fees, AERO rewards, and bribes. Null when a required price is unavailable. | | calculationTimestampAt | UInt32 | Unix timestamp when the calculation was performed. | | baseCurrency | String | Currency used for USD-denominated fields (e.g. "Usd"). | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | tvlPriceComplete | UInt8 | 1 if all tokens in the pool have complete pricing data, 0 otherwise. | | unpricedTokenAddresses | Array(String) | Addresses of tokens in the pool lacking price data, if any. | ## Examples ### 1. 7-Day Annualized Pool APR Fetch pool details for the USDC/AERO pool on Base, annualizing APR from the previous 7 completed UTC days. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v2/pool?chain_id=8453&pool_address=0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d&apr_days_annualized=7" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ {"name": "poolAddress", "type": "String"}, {"name": "token0Address", "type": "String"}, {"name": "token0Symbol", "type": "String"}, {"name": "token0Name", "type": "String"}, {"name": "token0Decimals", "type": "UInt8"}, {"name": "token1Address", "type": "String"}, {"name": "token1Symbol", "type": "String"}, {"name": "token1Name", "type": "String"}, {"name": "token1Decimals", "type": "UInt8"}, {"name": "reserve0", "type": "Int256"}, {"name": "reserve1", "type": "Int256"}, {"name": "tvlToken0", "type": "Float64"}, {"name": "tvlToken1", "type": "Float64"}, {"name": "token0PriceUsd", "type": "Nullable(Float64)"}, {"name": "token1PriceUsd", "type": "Nullable(Float64)"}, {"name": "tvlUsd", "type": "Nullable(Float64)"}, {"name": "feesXdUsd", "type": "Nullable(Float64)"}, {"name": "aeroRewardsXdUsd", "type": "Nullable(Float64)"}, {"name": "bribesXdUsd", "type": "Nullable(Float64)"}, {"name": "swapFeeAPR", "type": "Nullable(Float64)"}, {"name": "aeroRewardAPR", "type": "Nullable(Float64)"}, {"name": "bribeFeeAPR", "type": "Nullable(Float64)"}, {"name": "totalAPR", "type": "Nullable(Float64)"}, {"name": "calculationTimestampAt", "type": "UInt32"}, {"name": "baseCurrency", "type": "String"}, {"name": "createdAt", "type": "DateTime('UTC')"}, {"name": "tvlPriceComplete", "type": "UInt8"}, {"name": "unpricedTokenAddresses", "type": "Array(String)"} ], "data": [ [ "0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", "USD Coin", 6, "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", "Aerodrome", 18, "12601279199261", "30392701917380872686694266", 12601279.199261, 30392701.917380873, 1, 0.41335875, 25164368.38, 30381.42, 95109.51, null, 0.063, 0.1971, null, null, 1785883500, "Usd", "2023-09-07T22:50:45+00:00", 1, [] ] ], "rows": 1 } ] ``` This example annualizes fee and reward activity from the previous 7 completed UTC days. The pool holds ~$25.16M TVL, with `swapFeeAPR` null (unpriced in this window) while `aeroRewardAPR` is 6.3%. `bribeFeeAPR` and `totalAPR` are null here because at least one required component price was unavailable. ### 2. 30-Day Annualized Pool APR Fetch the same pool but annualize APR over the previous 30 completed UTC days to smooth out short-term volatility. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v2/pool?chain_id=8453&pool_address=0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d&apr_days_annualized=30" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ {"name": "poolAddress", "type": "String"}, {"name": "token0Address", "type": "String"}, {"name": "token0Symbol", "type": "String"}, {"name": "token0Name", "type": "String"}, {"name": "token0Decimals", "type": "UInt8"}, {"name": "token1Address", "type": "String"}, {"name": "token1Symbol", "type": "String"}, {"name": "token1Name", "type": "String"}, {"name": "token1Decimals", "type": "UInt8"}, {"name": "reserve0", "type": "Int256"}, {"name": "reserve1", "type": "Int256"}, {"name": "tvlToken0", "type": "Float64"}, {"name": "tvlToken1", "type": "Float64"}, {"name": "token0PriceUsd", "type": "Nullable(Float64)"}, {"name": "token1PriceUsd", "type": "Nullable(Float64)"}, {"name": "tvlUsd", "type": "Nullable(Float64)"}, {"name": "feesXdUsd", "type": "Nullable(Float64)"}, {"name": "aeroRewardsXdUsd", "type": "Nullable(Float64)"}, {"name": "bribesXdUsd", "type": "Nullable(Float64)"}, {"name": "swapFeeAPR", "type": "Nullable(Float64)"}, {"name": "aeroRewardAPR", "type": "Nullable(Float64)"}, {"name": "bribeFeeAPR", "type": "Nullable(Float64)"}, {"name": "totalAPR", "type": "Nullable(Float64)"}, {"name": "calculationTimestampAt", "type": "UInt32"}, {"name": "baseCurrency", "type": "String"}, {"name": "createdAt", "type": "DateTime('UTC')"}, {"name": "tvlPriceComplete", "type": "UInt8"}, {"name": "unpricedTokenAddresses", "type": "Array(String)"} ], "data": [ [ "0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", "USD Coin", 6, "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", "Aerodrome", 18, "12601279199261", "30392701917380872686694266", 12601279.199261, 30392701.917380873, 1, 0.41335875, 25164368.38, 199216.55, 489954.63, null, 0.0963, 0.2369, null, null, 1785883500, "Usd", "2023-09-07T22:50:45+00:00", 1, [] ] ], "rows": 1 } ] ``` Over the 30-day window, cumulative `feesXdUsd` ($199,216.55) and `aeroRewardsXdUsd` ($489,954.63) are larger since they cover more activity, and `aeroRewardAPR` rises to 9.63%. TVL and reserves remain the same because they reflect the current pool state, independent of the annualization window. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/aero/v2/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/aero/v2/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/aero/v2/fee-metrics` - Shows fee metrics and daily historical data for the previous seven completed UTC days. Usd fields are null when a pool-token price is unavailable. - `/evm/aero/v2/pool-volume` - Shows recent pool activity and hourly distribution. Usd fields are null when a pool-token price is unavailable. - `/evm/aero/v2/pools` - Returns liquidity pools with summary metrics for the previous 7 completed UTC days. Usd prices, valuations, and APRs are null when a required price is unavailable. - `/evm/aero/v2/provider-summary` - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics. - `/evm/aero/v3/pool` - Returns current pool TVL, Swap Volume, Price volatility and other metrics for recent time ranges. --- ## Cambrian API: V2 - List Pools **Endpoint:** /api/v1/evm/aero/v2/pools # Aerodrome V2 Pools ## Overview Returns Aerodrome V2 liquidity pools on Base with summary metrics aggregated over the previous 7 completed UTC days. Each pool record includes token pair details, TVL, volume, fees, rewards, and APR breakdowns. ## Business Value - **Pool Discovery**: Browse all available Aerodrome V2 pools with complete token pair information and symbols - **TVL Analysis**: Access real-time total value locked data for both tokens in each pool with USD valuations - **Yield Optimization**: Compare APR across pools including swap fees, AERO rewards, and bribe incentives - **Volume Tracking**: Monitor trading activity with 24h and 7-day volume metrics for investment decisions - **Risk Assessment**: Evaluate pool health through TVL, volume, and fee generation metrics ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/aero/v2/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. Only `8453` (Base) is supported. | | limit | integer | No | 100 | Limit the number of results. Maximum: 1000. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. Maximum: 100000. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolId | String | Address of the Aerodrome V2 pool contract. | | token0 | String | Contract address of the pool's first token. | | token0Symbol | String | Symbol of the pool's first token. | | token0Decimals | UInt8 | Decimal precision of the first token. | | token1 | String | Contract address of the pool's second token. | | token1Symbol | String | Symbol of the pool's second token. | | token1Decimals | UInt8 | Decimal precision of the second token. | | tvlToken0 | Float64 | Total value locked of token0, denominated in token0 units. | | tvlToken1 | Float64 | Total value locked of token1, denominated in token1 units. | | priceUsdToken0 | Nullable(Float64) | USD price of token0. Null if unavailable. | | priceUsdToken1 | Nullable(Float64) | USD price of token1. Null if unavailable. | | poolTvlUsd | Nullable(Float64) | Total value locked in the pool, denominated in USD. | | volume24hUsd | Nullable(Float64) | Trading volume over the last 24 hours, in USD. | | volume7dUsd | Nullable(Float64) | Trading volume over the last 7 completed UTC days, in USD. | | fees7dUsd | Nullable(Float64) | Swap fees collected over the last 7 completed UTC days, in USD. | | aeroRewards7dUsd | Nullable(Float64) | AERO emission rewards distributed over the last 7 completed UTC days, in USD. | | bribes7dUsd | Nullable(Float64) | Bribe rewards paid to voters over the last 7 completed UTC days, in USD. | | swapFeeApr7d | Nullable(Float64) | Annualized percentage rate derived from swap fees over the last 7 days. | | aeroRewardApr7d | Nullable(Float64) | Annualized percentage rate derived from AERO emission rewards over the last 7 days. | | bribeFeeApr7d | Nullable(Float64) | Annualized percentage rate derived from bribe rewards over the last 7 days. | | totalApr7d | Nullable(Float64) | Combined annualized percentage rate (swap fees + AERO rewards + bribes) over the last 7 days. | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | tvlPriceComplete | UInt8 | Flag (1/0) indicating whether all tokens in the pool have a resolvable USD price for TVL calculation. | | unpricedTokenAddresses | Array(String) | List of token addresses in the pool that lack a resolvable USD price. | ## Examples ### 1. List Top Aerodrome V2 Pools Retrieve the default set of Aerodrome V2 pools on Base with their 7-day summary metrics. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v2/pools" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolId", "type": "String" }, { "name": "token0", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "tvlToken0", "type": "Float64" }, { "name": "tvlToken1", "type": "Float64" }, { "name": "priceUsdToken0", "type": "Nullable(Float64)" }, { "name": "priceUsdToken1", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "volume24hUsd", "type": "Nullable(Float64)" }, { "name": "volume7dUsd", "type": "Nullable(Float64)" }, { "name": "fees7dUsd", "type": "Nullable(Float64)" }, { "name": "aeroRewards7dUsd", "type": "Nullable(Float64)" }, { "name": "bribes7dUsd", "type": "Nullable(Float64)" }, { "name": "swapFeeApr7d", "type": "Nullable(Float64)" }, { "name": "aeroRewardApr7d", "type": "Nullable(Float64)" }, { "name": "bribeFeeApr7d", "type": "Nullable(Float64)" }, { "name": "totalApr7d", "type": "Nullable(Float64)" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "tvlPriceComplete", "type": "UInt8" }, { "name": "unpricedTokenAddresses", "type": "Array(String)" } ], "data": [ [ "0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 18, 12601279.199261, 30392701.917380873, 1, 0.41335875, 25164368.38, 1163798.73, 10127138.8, 30381.42, 95109.51, null, 0.063, 0.1971, null, null, "2023-09-07T22:50:45+00:00", 1, [] ], [ "0xde4fb30ccc2f1210fce2c8ad66410c586c8d1f9a", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x7ba6f01772924a82d9626c126347a28299e98c98", "msETH", 18, 2116.64090057896, 7206.929065515169, 1873.11058738, 1348.95235501, 13686506.42, 40074.73, 7585256.48, 3792.63, 9521.67, 7242.67, 0.0144, 0.0363, 0.0276, 0.0783, "2024-06-05T21:56:33+00:00", 1, [] ] ], "rows": 100 } ] ``` The response is returned in a columnar table format (`columns` + `data` rows). The top pool by TVL is the USDC/AERO pool with a 7-day total APR of 19.71%, followed by the WETH/msETH pool at 7.83% total APR. Note: this example response has been truncated to the first 10 rows for documentation purposes; the `rows` field reflects the true total (100) available with default pagination. ### 2. Paginate Through Results Use `limit` and `offset` to page through the full pool list beyond the default page size. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v2/pools?limit=5&offset=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolId", "type": "String" }, { "name": "token0", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "tvlToken0", "type": "Float64" }, { "name": "tvlToken1", "type": "Float64" }, { "name": "priceUsdToken0", "type": "Nullable(Float64)" }, { "name": "priceUsdToken1", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "volume24hUsd", "type": "Nullable(Float64)" }, { "name": "volume7dUsd", "type": "Nullable(Float64)" }, { "name": "fees7dUsd", "type": "Nullable(Float64)" }, { "name": "aeroRewards7dUsd", "type": "Nullable(Float64)" }, { "name": "bribes7dUsd", "type": "Nullable(Float64)" }, { "name": "swapFeeApr7d", "type": "Nullable(Float64)" }, { "name": "aeroRewardApr7d", "type": "Nullable(Float64)" }, { "name": "bribeFeeApr7d", "type": "Nullable(Float64)" }, { "name": "totalApr7d", "type": "Nullable(Float64)" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "tvlPriceComplete", "type": "UInt8" }, { "name": "unpricedTokenAddresses", "type": "Array(String)" } ], "data": "... (see full response schema above; use offset=10 to retrieve rows 11-15 with limit=5)", "rows": 100 } ] ``` Setting `offset=10` with `limit=5` skips the first 10 pools (already retrieved in Example 1) and returns the next 5, enabling efficient pagination across the full 100-row result set. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/aero/v2/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/aero/v2/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/aero/v2/pool` - Get information for a specific Aerodrome V2 pool. - `/evm/aero/v2/pool-volume` - Shows recent pool activity and hourly distribution. - `/evm/aero/v2/fee-metrics` - Shows fee metrics and daily historical data for the previous seven completed UTC days. - `/evm/aero/v2/provider-summary` - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics. - `/evm/aero/v3/pools` - Returns a list of all Aerodrome V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. --- ## Cambrian API: V2 - Pool Volume **Endpoint:** /api/v1/evm/aero/v2/pool-volume # V2 - Pool Volume ## Overview Returns recent trading activity for a specific Aerodrome V2 pool, including total volume, swap counts, hourly volume distribution, per-token volume breakdown, and the largest recent swaps. USD-denominated fields are null when a pool-token price is unavailable. ## Business Value - **Real-time Trading Analytics**: Monitor pool activity and trading patterns in real-time for informed decision making - **Volume Trend Analysis**: Track hourly volume patterns to identify peak trading times and market activity cycles - **Liquidity Pool Performance**: Assess pool health through swap counts, average transaction sizes, and volume changes - **Large Transaction Monitoring**: Identify significant trades and their impact on pool dynamics - **Cross-Token Volume Insights**: Understand directional trading flows between token pairs within the pool ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/aero/v2/pool-volume ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. Allowed values: 8453 | | pool_address | string | Yes | - | Pool address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolId | String | Pool address with 0x prefix | | timeframeAt | String | Timeframe label for the reported volume window (e.g. "24h") | | volumeUsd | Nullable(Float64) | Total swap volume in USD over the timeframe; null when a pool-token price is unavailable | | volumeToken0 | String | Total swap volume denominated in token0 units | | volumeToken1 | String | Total swap volume denominated in token1 units | | volumeChange | Nullable(Float64) | Percentage change in volume versus the prior equivalent period | | swapCount | UInt64 | Number of swaps executed during the timeframe | | averageSwapSize | Nullable(Float64) | Average swap size in USD; null when a pool-token price is unavailable | | volumeByHour | Array(Map(String,Nullable(String))) | Hourly breakdown of swap activity, each entry containing swapCount, timestamp, and volumeUsd | | volumeByToken | Map(String,Nullable(String)) | Directional volume breakdown between token0 and token1, including percentages and converted amounts | | largestSwaps | Array(Map(String,Nullable(String))) | List of the largest recent swaps, each containing amountToken0, amountToken1, amountUsd, timestamp, txHash, and type | | updatedAt | UInt32 | Unix timestamp of when the data was last updated | | tvlPriceComplete | UInt8 | Flag indicating whether all prices needed for valuation are available (1) or not (0) | ## Examples ### 1. Retrieve recent volume activity for an Aerodrome V2 pool Fetches recent pool activity, including hourly volume distribution and the largest recent swaps, for a specific Aerodrome V2 pool. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v2/pool-volume?pool_address=0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolId", "type": "String" }, { "name": "timeframeAt", "type": "String" }, { "name": "volumeUsd", "type": "Nullable(Float64)" }, { "name": "volumeToken0", "type": "String" }, { "name": "volumeToken1", "type": "String" }, { "name": "volumeChange", "type": "Nullable(Float64)" }, { "name": "swapCount", "type": "UInt64" }, { "name": "averageSwapSize", "type": "Nullable(Float64)" }, { "name": "volumeByHour", "type": "Array(Map(String,Nullable(String)))" }, { "name": "volumeByToken", "type": "Map(String,Nullable(String))" }, { "name": "largestSwaps", "type": "Array(Map(String,Nullable(String)))" }, { "name": "updatedAt", "type": "UInt32" }, { "name": "tvlPriceComplete", "type": "UInt8" } ], "data": [ [ "0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "24h", 1106569.559754, "1098226.305408", "2647525.1171569736", -9.001126, 2103, 526.186191, [ { "swapCount": "91", "timestamp": "1785844800", "volumeUsd": "53297.28152" }, { "swapCount": "108", "timestamp": "1785848400", "volumeUsd": "74018.733603" }, { "swapCount": "120", "timestamp": "1785852000", "volumeUsd": "84188.153718" }, { "swapCount": "96", "timestamp": "1785855600", "volumeUsd": "45376.629463" }, { "swapCount": "86", "timestamp": "1785859200", "volumeUsd": "49637.697251" }, { "swapCount": "77", "timestamp": "1785862800", "volumeUsd": "33752.630014" }, { "swapCount": "88", "timestamp": "1785866400", "volumeUsd": "25602.388183" }, { "swapCount": "117", "timestamp": "1785870000", "volumeUsd": "72146.605551" }, { "swapCount": "112", "timestamp": "1785873600", "volumeUsd": "58741.002662" }, { "swapCount": "52", "timestamp": "1785877200", "volumeUsd": "5231.220695" } ], { "token0Percentage": "0.545155", "token0ToToken1": "603252.179332", "token1Percentage": "0.454845", "token1ToToken0": "503317.380422" }, [ { "amountToken0": "10962.600648", "amountToken1": "26011.94969148394", "amountUsd": "10962.600648", "timestamp": "1785908307", "txHash": "0x1b7b96bd1eb439133b8366e52c53b4e19efe8c9328d23dfd46f22c989cfe0331", "type": "token0ToToken1" }, { "amountToken0": "10157.903789", "amountToken1": "24218.23997559632", "amountUsd": "10157.903789", "timestamp": "1785908289", "txHash": "0x66fdb4b34850fee90e6691ca2f66514848ffb1e4bbcbdaf84db2410401515890", "type": "token0ToToken1" }, { "amountToken0": "8574.462363", "amountToken1": "20879.98949338514", "amountUsd": "8768.939905", "timestamp": "1785845841", "txHash": "0x375beb7b08808dd5b431d7aa03b11f1b0dccea5827a79eb9d62808080a7ab52e", "type": "token1ToToken0" }, { "amountToken0": "8493.802303", "amountToken1": "20554.205433610492", "amountUsd": "8632.12083", "timestamp": "1785886735", "txHash": "0x06c1183b09a2ba0232f5b9e4692269ff289e652ae7570f014f2037eb966563fc", "type": "token1ToToken0" }, { "amountToken0": "8574.462363", "amountToken1": "20554.205433610492", "amountUsd": "8574.462363", "timestamp": "1785872543", "txHash": "0x648e7b99dedbd76ea4b4436b0dbede396e497d2cc71b786115657073fa9b8c2a", "type": "token0ToToken1" }, { "amountToken0": "8493.802303", "amountToken1": "20220.993864243097", "amountUsd": "8493.802303", "timestamp": "1785908295", "txHash": "0xbddb78ea6636f3e76b7f4b043f859aa291d8f6da9e990f547f5b5eae93233344", "type": "token0ToToken1" }, { "amountToken0": "6925.090793", "amountToken1": "16957.17630494124", "amountUsd": "7121.481551", "timestamp": "1785851219", "txHash": "0xff120a99aa73cd2e5048811a3d51e7720d9b392804e6f111888ef7d14494296a", "type": "token1ToToken0" }, { "amountToken0": "6246.678857", "amountToken1": "14907.97619626249", "amountUsd": "6246.678857", "timestamp": "1785908289", "txHash": "0x6c67a2a6f40ea1ebd9d5822777f419960a859d4bae5a27add55a2563cfd051fe", "type": "token0ToToken1" }, { "amountToken0": "5708.470588", "amountToken1": "13547.10621033063", "amountUsd": "5708.470588", "timestamp": "1785912069", "txHash": "0xd602d3bdc737b3b9191a660d6948336e0cd6ab85b2eaa6c35cfd24506712521f", "type": "token0ToToken1" }, { "amountToken0": "5626.079852", "amountToken1": "13469.27111617974", "amountUsd": "5626.079852", "timestamp": "1785908275", "txHash": "0xdc6de225131413aee2a913818eab4011e339482d96373cdc401d89741574b777", "type": "token0ToToken1" } ], 1785928500, 1 ] ], "rows": 1 } ] ``` Result collections such as `volumeByHour` and `largestSwaps` are limited to 10 items each. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), paying **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/aero/v2/pool-volume" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/aero/v2/pool-volume") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /evm/aero/v2/fee-metrics - Shows fee metrics and daily historical data for the previous seven completed UTC days. - /evm/aero/v2/pool - Get information for a specific Aerodrome V2 pool. - /evm/aero/v2/pools - Returns liquidity pools with summary metrics for the previous 7 completed UTC days. - /evm/aero/v2/provider-summary - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics. - /evm/aero/v3/pool - Returns current pool TVL, Swap Volume, Price volatility and related metrics. --- ## Cambrian API: V2 - Provider Summary **Endpoint:** /api/v1/evm/aero/v2/provider-summary # V2 - Provider Summary ## Overview Returns the Aerodrome V2 liquidity-provider summary and portfolio metrics for a given wallet address on an EVM chain. Portfolio-wide USD aggregates and weighted APRs are null if any represented position cannot be fully priced; per-pool and per-token values are nullable independently. ## Business Value - **Portfolio Analysis**: Understand concentration risk and token exposure across multiple liquidity pools - **Performance Tracking**: Monitor historical fees earned and APR performance over 7-day and 30-day periods - **Position Management**: Analyze position sizes and distribution to optimize capital allocation - **Risk Assessment**: Calculate HHI concentration index to measure portfolio diversification - **Strategic Planning**: Identify top performing pools and fee opportunities for future positions ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/aero/v2/provider-summary ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. Enum: [8453] | | wallet_address | string | Yes | - | Liquidity provider address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | providerId | String | Liquidity provider wallet address | | totalValueLockedUsd | Nullable(Float64) | Total USD value locked across all positions; null if any position cannot be fully priced | | activePositionCount | UInt64 | Number of currently active liquidity positions | | totalFeesEarned7d | Nullable(Float64) | Total fees earned in USD over the trailing 7 days | | averageAPR7dWeighted | Nullable(Float64) | Position-size-weighted average APR over the trailing 7 days | | firstPositionTimestamp | Nullable(DateTime('UTC')) | Timestamp of the provider's first liquidity position | | lastActiveTimestamp | Nullable(DateTime('UTC')) | Timestamp of the provider's most recent activity | | poolCount | UInt64 | Number of distinct pools the provider has positions in | | topPoolsData | Array(Tuple(FixedString(42), String, String, Nullable(Float64), Nullable(Float64))) | Top pools by size: pool address, token0 symbol, token1 symbol, position value USD, share of portfolio | | tokenExposure | Array(Tuple(FixedString(42), String, Float64, Nullable(Float64), Nullable(Float64))) | Per-token exposure: token address, token symbol, token amount, USD value, share of portfolio | | averagePositionSizeUsd | Nullable(Float64) | Average USD size of the provider's positions | | medianPositionSizeUsd | Nullable(Float64) | Median USD size of the provider's positions | | minPositionSizeUsd | Nullable(Float64) | Smallest USD position size | | maxPositionSizeUsd | Nullable(Float64) | Largest USD position size | | hhiConcentrationIndex | Nullable(Float64) | Herfindahl-Hirschman Index measuring portfolio concentration across positions | | totalFeesEarned30d | Nullable(Float64) | Total fees earned in USD over the trailing 30 days | | averageAPR30dWeighted | Nullable(Float64) | Position-size-weighted average APR over the trailing 30 days | | feeAprByPool30d | Array(Tuple(FixedString(42), String, String, Nullable(Float64), Nullable(Float64))) | Per-pool 30-day fee APR breakdown: pool address, token0 symbol, token1 symbol, fee amount USD, weighted APR | ## Examples ### 1. Retrieve Provider Summary for a Wallet Fetches the Aerodrome V2 liquidity-provider summary for a specific wallet address on Base (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/aero/v2/provider-summary?wallet_address=0x8115afd8dffce5579381ad27524b6feeae917bef" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "providerId", "type": "String" }, { "name": "totalValueLockedUsd", "type": "Nullable(Float64)" }, { "name": "activePositionCount", "type": "UInt64" }, { "name": "totalFeesEarned7d", "type": "Nullable(Float64)" }, { "name": "averageAPR7dWeighted", "type": "Nullable(Float64)" }, { "name": "firstPositionTimestamp", "type": "Nullable(DateTime('UTC'))" }, { "name": "lastActiveTimestamp", "type": "Nullable(DateTime('UTC'))" }, { "name": "poolCount", "type": "UInt64" }, { "name": "topPoolsData", "type": "Array(Tuple(FixedString(42),String,String,Nullable(Float64),Nullable(Float64)))" }, { "name": "tokenExposure", "type": "Array(Tuple(FixedString(42),String,Float64,Nullable(Float64),Nullable(Float64)))" }, { "name": "averagePositionSizeUsd", "type": "Nullable(Float64)" }, { "name": "medianPositionSizeUsd", "type": "Nullable(Float64)" }, { "name": "minPositionSizeUsd", "type": "Nullable(Float64)" }, { "name": "maxPositionSizeUsd", "type": "Nullable(Float64)" }, { "name": "hhiConcentrationIndex", "type": "Nullable(Float64)" }, { "name": "totalFeesEarned30d", "type": "Nullable(Float64)" }, { "name": "averageAPR30dWeighted", "type": "Nullable(Float64)" }, { "name": "feeAprByPool30d", "type": "Array(Tuple(FixedString(42),String,String,Nullable(Float64),Nullable(Float64)))" } ], "data": [ [ "0x8115afd8dffce5579381ad27524b6feeae917bef", null, 3, null, null, "2025-05-04T15:37:35+00:00", "2025-11-14T21:23:41+00:00", 3, [ [ "0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "USDC", "AERO", 7.64293913380204, null ], [ "0xcdac0d6c6c59727a65f871236188350531885c43", "WETH", "USDC", 4.0592370820075985, null ], [ "0x55b27dbddf95a55bd46d0284348dc8231cd72a2c", "USDC.e", "Unitos.net", null, null ] ], [ [ "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 5.846573580342932, 5.846573580342932, null ], [ "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 9.258544786616937, 3.8259097792025174, null ], [ "0x4200000000000000000000000000000000000006", "WETH", 0.0010864921894428372, 2.0296928562641887, null ], [ "0x04e4dfbdbd7c9416a96e144ac51d95d78f83fb19", "USDC.e", 16109.845441127067, null, null ], [ "0xd88707f590528b4a1e316eeebe7bb6ac8b0ea461", "Unitos.net", 3627.4473281608107, null, null ] ], null, null, null, null, null, null, null, [ [ "0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "USDC", "AERO", 0.0593277037736198, 0.09444277695736393 ], [ "0xcdac0d6c6c59727a65f871236188350531885c43", "WETH", "USDC", 0.011900108337477979, 0.03566794659052249 ], [ "0x55b27dbddf95a55bd46d0284348dc8231cd72a2c", "USDC.e", "Unitos.net", null, null ] ] ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. This wallet has 3 active positions across 3 pools. The USD-denominated aggregates (totalValueLockedUsd, fee earnings, and weighted APRs) come back null because at least one position could not be fully priced, while per-pool and per-token exposure values are still populated wherever pricing data is available. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/aero/v2/provider-summary" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/aero/v2/provider-summary") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /evm/aero/v2/fee-metrics - Fee metrics and daily historical data for the previous seven completed UTC days. - /evm/aero/v2/pool - Information for a specific Aerodrome V2 pool. - /evm/aero/v2/pool-volume - Recent pool activity and hourly distribution. - /evm/aero/v2/pools - Liquidity pools with summary metrics for the previous 7 completed UTC days. --- ## Cambrian API: V3 - Pool Info **Endpoint:** /api/v1/evm/aero/v3/pool # Aerodrome V3 Pool Info ## Overview Returns current pool TVL (Total Value Locked), swap volume, price volatility and mean adjusted volatility (percentage), tick pressure per 1M$ volume, number of swaps, and unique users for a specific Aerodrome V3 (concentrated liquidity) pool on Base. Metrics are broken down across multiple recent time ranges (5 minutes, 1 hour, 1 day, 1 week, 1 month, and 1 year). ## Business Value - **Real-time Pool Analytics**: Get current pool health metrics including TVL and liquidity for informed trading decisions - **Volume Analysis**: Track swap volume patterns across different time periods to identify trading activity trends - **Fee Income Assessment**: Monitor APR rates to evaluate fee generation potential and yield opportunities - **Market Activity Insights**: Analyze swap counts and unique user metrics to understand pool adoption and usage - **Risk Management**: Assess tick utilization to understand price range efficiency and concentration risk ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/aero/v3/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | pool_address | string | Yes | - | Pool address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | String | Contract address of token0 in the pool | | token0Symbol | String | Symbol of token0 | | token0Decimals | UInt8 | Decimal precision of token0 | | token1Address | String | Contract address of token1 in the pool | | token1Symbol | String | Symbol of token1 | | token1Decimals | UInt8 | Decimal precision of token1 | | tickSpacing | Int32 | Minimum tick spacing configured for the pool | | currentLiquidity | Nullable(Int256) | Current in-range liquidity of the pool at the active tick | | currentSqrtPriceX96 | Nullable(UInt256) | Current pool price expressed as sqrt(price) * 2^96 (Uniswap V3-style encoding) | | currentTick | Nullable(Int32) | Current active tick of the pool | | currentPoolPrice | Nullable(Float64) | Current human-readable price of token1 denominated in token0 (or vice versa, depending on pool convention) | | poolTvlUsd | Nullable(Float64) | Total value locked in the pool, denominated in USD | | swapVolumeUsd | Map(String,Nullable(Float64)) | Total swap volume in USD, keyed by time range ("5 minute", "1 hour", "1 day", "1 week", "1 month", "1 year") | | priceVolatilityPct | Map(String,Float64) | Price volatility (percentage) over each time range | | priceVolatilityAdjustedPct | Map(String,Float64) | Mean-adjusted price volatility (percentage) over each time range | | tickPressurePer1MUsd | Map(String,Nullable(Float64)) | Tick movement pressure per $1M of swap volume, keyed by time range | | swapCount | Map(String,UInt64) | Number of swaps executed, keyed by time range | | uniqueUserCount | Map(String,UInt64) | Number of unique users who swapped, keyed by time range | ## Examples ### 1. Get V3 Pool Info for WETH/cbBTC Fetch current pool metrics for the WETH/cbBTC Aerodrome V3 pool on Base. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v3/pool?chain_id=8453&pool_address=0xffa192f04b1e5f9f5124fb40a96407564492ed20" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2025-02-13T22:12:07+00:00", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, 10, "56389843308", "135531666605172087391945", -265587, 0.02926323871608235, 34.851306584948645, { "1 day": 0.0750185699423578, "1 hour": 0, "1 month": 783.647302016295, "1 week": 378.18435935401294, "1 year": 4766.040834024103, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0.031000322701857774, "1 week": 0.01371590088020538, "1 year": 1, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0.0015618088088647807, "1 week": 0.0009954027098261833, "1 year": 1, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 451223.3999787921, "1 week": 303026.8099816486, "1 year": 90068993.31106928, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "1 month": 392, "1 week": 186, "1 year": 1161, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "5 minute": 0 } ] ], "rows": 1 } ] ``` This pool has relatively low TVL (~$34.85) and shows zero swap activity in the 1-hour, 1-day, and 5-minute windows, but has processed swaps over longer windows (e.g., 392 swaps in the past month with $783.65 in volume). ### 2. Get V3 Pool Info for WETH/USDC Fetch current pool metrics for the higher-volume WETH/USDC Aerodrome V3 pool on Base. ```bash curl -X GET "https://api.cambrian.org/evm/aero/v3/pool?chain_id=8453&pool_address=0xb2cc224c1c9fee385f8ad6a55b4d94e92359dc59" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2024-05-01T18:45:31+00:00", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, 100, "4882948427719440609", "3429336856146121144326862", -200965, 1873.5320484968538, 6401648.766035728, { "1 day": 44754468.83826165, "1 hour": 1120992.9963265602, "1 month": 1355451478.3275385, "1 week": 261042365.47260854, "1 year": 46294130909.72368, "5 minute": 23130.240714292144 }, { "1 day": 0.008755330134790818, "1 hour": 0.0012113898660744346, "1 month": 0.07192239934185146, "1 week": 0.02448668823680449, "1 year": 0.9723014890417713, "5 minute": 0.00006973043789367841 }, { "1 day": 0.00007000469320576046, "1 hour": 0.00006373599467932553, "1 month": 0.00009258266288696674, "1 week": 0.0000757055066943909, "1 year": 0.0002791508568309004, "5 minute": 0.000018652947436337457 }, { "1 day": 1.3931569655161569, "1 hour": 1.2667340515536416, "1 month": 2.1560343890774196, "1 week": 1.717920381192134, "1 year": 1.2289970430798092, "5 minute": 1.2970033632837656 }, { "1 day": 15641, "1 hour": 361, "1 month": 603488, "1 week": 104617, "1 year": 12131764, "5 minute": 11 }, { "1 day": 119, "1 hour": 33, "5 minute": 6 } ] ], "rows": 1 } ] ``` This is a significantly higher-activity pool with ~$6.4M TVL, $44.75M in 1-day swap volume, and 15,641 swaps in the past day alone, illustrating how the same endpoint scales across pools of very different liquidity and trading intensity. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/aero/v3/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/aero/v3/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/aero/v2/pool` - Get information for a specific Aerodrome V2 pool. Usd prices, valuations, and APRs are null when a required price is unavailable. - `/evm/aero/v3/pools` - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/aero/v2/pool-volume` - Shows recent pool activity and hourly distribution. Usd fields are null when a pool-token price is unavailable. - `/evm/aero/v2/fee-metrics` - Shows fee metrics and daily historical data for the previous seven completed UTC days. Usd fields are null when a pool-token price is unavailable. - `/evm/aero/v2/provider-summary` - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics. Portfolio-wide Usd aggregates and weighted APRs are null if any represented position cannot be fully priced; per-pool and per-token values are nullable independently. --- ## Cambrian API: V3 - Pool Info **Endpoint:** /api/v1/evm/alien/v3/pool # V3 Pool Info (Alien Base) ## Overview Returns current-state and time-windowed analytics for a specific AlienBase V3 liquidity pool on an EVM chain. Metrics include TVL, swap volume, fee APR, price volatility (raw and mean-adjusted), tick pressure per $1M volume, swap count, and unique user count across six rolling windows (5 minutes, 1 hour, 1 day, 1 week, 1 month, 1 year). ## Business Value - **Real-time Pool Analytics**: Get up-to-date metrics for liquidity pools to assess performance and activity levels - **Multi-timeframe Analysis**: Access data across different time horizons for comprehensive trend analysis and market timing - **Liquidity Provider Insights**: Monitor TVL, fees, and utilization metrics to optimize liquidity provision strategies - **Trading Intelligence**: Track swap volumes and user activity to identify high-volume and active pools for trading opportunities - **Risk Assessment**: Evaluate pool health through tick utilization and liquidity distribution metrics ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/alien/v3/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | pool_address | string | Yes | - | Pool address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | String | Contract address of token0 | | token0Symbol | String | Symbol of token0 | | token0Decimals | UInt8 | Decimal places of token0 | | token1Address | String | Contract address of token1 | | token1Symbol | String | Symbol of token1 | | token1Decimals | UInt8 | Decimal places of token1 | | feeTier | UInt32 | Pool fee tier (in hundredths of a bip) | | tickSpacing | Int32 | Minimum tick spacing for the pool | | currentLiquidity | Nullable(Int256) | Current in-range liquidity of the pool | | currentSqrtPriceX96 | Nullable(UInt256) | Current sqrt price in X96 fixed-point format | | currentTick | Nullable(Int32) | Current tick of the pool | | currentPoolPrice | Nullable(Float64) | Current pool price (token1 per token0) | | poolTvlUsd | Nullable(Float64) | Current total value locked in the pool, in USD | | swapVolumeUsd | Map(String,Nullable(Float64)) | Swap volume in USD, keyed by time window (5 minute, 1 hour, 1 day, 1 week, 1 month, 1 year) | | feeApr | Map(String,Nullable(Float64)) | Fee-based annual percentage rate, keyed by time window | | priceVolatilityPct | Map(String,Float64) | Price volatility percentage, keyed by time window | | priceVolatilityAdjustedPct | Map(String,Float64) | Mean-adjusted price volatility percentage, keyed by time window | | tickPressurePer1MUsd | Map(String,Nullable(Float64)) | Tick pressure per $1M of volume, keyed by time window | | swapCount | Map(String,UInt64) | Number of swaps, keyed by time window | | uniqueUserCount | Map(String,UInt64) | Number of unique users, keyed by time window | ## Examples ### 1. Fetch Pool Info for EURC/USDC Pool This example retrieves current TVL, price, and time-windowed metrics for a stablecoin pair pool (EURC/USDC) on Base. ```bash curl -X GET "https://api.cambrian.org/evm/alien/v3/pool?chain_id=8453&pool_address=0x63170b42585b86e3c439820ade18fbd07a8933cd" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2024-09-11T18:27:29+00:00", "0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42", "EURC", 6, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, 200, 4, "10472813", "85042117852324013360279677254", 1416, 1.1521498477613974, 25.29667234043353, { "1 day": 0.007334871200317039, "1 hour": 0, "1 month": 0.17332569448107238, "1 week": 0.09121907886901764, "1 year": 12.068390750089282, "5 minute": 0 }, { "1 day": 2.1166641620577968e-05, "1 hour": 0, "1 month": 1.6444125976588614e-05, "1 week": 3.75021033387637e-05, "1 year": 9.541484814822451e-05, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0.006280861745086321, "1 week": 0.00319535547429214, "1 year": 0.27689133513102515, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0.0014359264150442907, "1 week": 0.0008205896363839643, "1 year": 0.019095402382108252, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 203374347.38419232, "1 week": 172661248.01167503, "1 year": 330615745.1001064, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "1 month": 17, "1 week": 7, "1 year": 210, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "5 minute": 0 } ] ], "rows": 1 } ] ``` This EURC/USDC pool (0.02% fee tier) shows a current TVL of ~$25.30, with a tight price of ~1.152 and low volatility, typical of a low-liquidity stablecoin pair. Note that `uniqueUserCount` omits the "1 month" and "1 year" keys in the map for this pool — only windows with data are populated. ### 2. Fetch Pool Info for WETH/AERO Pool This example retrieves current metrics for a more actively traded pair (WETH/AERO), demonstrating higher TVL and swap activity. ```bash curl -X GET "https://api.cambrian.org/evm/alien/v3/pool?chain_id=8453&pool_address=0xddb12424d09dd35852fd5263485e7594c40555c7" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2026-07-26T07:46:05+00:00", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 18, 750, 15, "10313258915862161", "5378294517729380315740283171340", 84360, 4608.185933385387, 0.1681031067826902, { "1 day": 0.0034108194532485227, "1 hour": 0, "1 month": 0.02945997094799778, "1 week": 0.02248861923624091, "1 year": 0.02945997094799778, "5 minute": 0 }, { "1 day": 0.005554399577717552, "1 hour": 0, "1 month": 0.001577244725611947, "1 week": 0.005217370261616767, "1 year": 0.00013143706046766224, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0, "1 week": 0, "1 year": 0, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0, "1 week": 0, "1 year": 0, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0, "1 week": 0, "1 year": 0, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "1 month": 13, "1 week": 9, "1 year": 13, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "5 minute": 0 } ] ], "rows": 1 } ] ``` This WETH/AERO pool (0.75% fee tier) was created recently and has a much higher implied price (~4608 AERO per WETH) and higher pool price magnitude than the stablecoin example, with zero recorded price volatility so far — consistent with a newly created pool with limited trading history. *Note: Result collections in the examples above are limited to their first 10 items (this endpoint returns a single row per request, so no truncation was needed here).* ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/alien/v3/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/alien/v3/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/alien/v3/pools` - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/uniswap/v3/pool` - Returns current pool TVL, swap volume, fee APR, and volatility metrics for a Uniswap V3 pool. - `/evm/aero/v3/pool` - Returns current pool TVL, swap volume, and volatility metrics for an Aerodrome V3 pool. - `/evm/sushi/v3/pool` - Returns current pool TVL, swap volume, fee APR, and volatility metrics for a SushiSwap V3 pool. - `/evm/price-current` - Returns current price of a token calculated based on Uniswap V3 and clones liquidity pools. --- ## Cambrian API: V3 - List Pools **Endpoint:** /api/v1/evm/alien/v3/pools # V3 - List Pools (Alien Base) ## Overview Returns a list of all Alien Base V3 liquidity pools on EVM chains, including token pairs, fee tiers, tick spacing, and creation timestamps. Results can be filtered by chain or token address and support pagination and sorting. ## Business Value - **Pool Discovery**: Identify all available liquidity pools with complete metadata including token symbols, decimals, and addresses - **DEX Analytics**: Analyze fee structures, tick spacing configurations, and pool creation patterns across different time periods - **Portfolio Management**: Track and monitor specific pools by filtering on token addresses or sorting by various metrics - **Market Research**: Understand the AlienBase ecosystem structure through comprehensive pool data including creation timestamps and fee tiers - **Integration Support**: Access standardized pool data for building applications, trading interfaces, or analytical tools ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/alien/v3/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | No | - | Pool token address. See tokens for valid addresses. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | | order_asc | array | No | - | List of column names to order by in ascending order divided by comma. Leave empty items to combine with descending order | | order_desc | array | No | - | List of column names to order by in descending order divided by comma. Leave empty items to combine with ascending order | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID. | | dexAddress | FixedString(42) | Address of the DEX (Alien Base) factory/router contract. | | dexName | String | Name of the DEX. | | poolAddress | FixedString(42) | Address of the liquidity pool contract. | | token0Address | String | Contract address of the first token in the pair. | | token0Symbol | String | Symbol of the first token in the pair. | | token0Decimals | UInt8 | Decimal places of the first token. | | token1Address | String | Contract address of the second token in the pair. | | token1Symbol | String | Symbol of the second token in the pair. | | token1Decimals | UInt8 | Decimal places of the second token. | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | fee | UInt32 | Pool fee tier (in hundredths of a bip). | | tickSpacing | Int32 | Minimum tick spacing allowed for the pool. | ## Examples ### 1. List Alien Base V3 Pools Retrieve all Alien Base V3 pools on Base (chain ID 8453) using default pagination. ```bash curl -X GET "https://api.cambrian.org/evm/alien/v3/pools" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0xb15a485232f9ec085283c50db922c3d4b006b65f", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x50c5725949a6f0c72e6c4a641f24049a917db0cb", "DAI", 18, "2026-07-28T07:55:37+00:00", 200, 4 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0xddb12424d09dd35852fd5263485e7594c40555c7", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 18, "2026-07-26T07:46:05+00:00", 750, 15 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0x2f6b86121e7048e7d70adb01193a8b1169bc05a3", "0xb111b7690f6420fc27d63d6870aad4450dbe22d0", "FUN", 6, "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2", "USDT", 6, "2026-07-14T11:32:03+00:00", 200, 4 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0xe96af482c188bdf6f1bfb1ce47cefb763c13a053", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xb111b7690f6420fc27d63d6870aad4450dbe22d0", "FUN", 6, "2026-07-14T11:29:13+00:00", 200, 4 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0xa945bcd3c959939dcb01687f24fb03412ac91f8d", "0x30457a1ab7cd796d6e55e4e5ba12e09f2283e856", "DUB", 18, "0xb111b7690f6420fc27d63d6870aad4450dbe22d0", "FUN", 6, "2026-07-11T02:43:47+00:00", 10000, 200 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0x30d534865caa3bb3db3ef1da4c6e05cc0c0677c7", "0x1dd2d631c92b1acdfcdd51a0f7145a50130050c4", "ALB", 18, "0xa9b631abcc4fd0bc766d7c0c8fcbf866e2bb0445", "HASH", 18, "2026-07-07T09:27:41+00:00", 200, 4 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0x402e3118713f78839ee1900ee618fb8883f6a1d7", "0x490c05dfe97dbab7730be2199e02a5747f85abb8", "agentinz", 18, "0x7504334d6a621039570fb9787bbe00ea8808fb07", "evoluter", 18, "2026-07-03T12:32:11+00:00", 10000, 200 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0xc4ac08977f316eec11b8c915d722bde979aaae44", "0x100145862a4e1e0f22432a12abf5db88a17ab8fe", "ETSAR", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-07-03T03:33:55+00:00", 10000, 200 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0x106d24a09ebcecefc8004692814f74e68c35268d", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x9c8cd8d3961f445d653713de65c6578be11668e7", "SINC", 8, "2026-06-27T05:48:19+00:00", 10000, 200 ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "0x943051049fe52d2e236663da081d7b7ecbcc9466", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0x9c8cd8d3961f445d653713de65c6578be11668e7", "SINC", 8, "2026-06-27T03:45:25+00:00", 10000, 200 ] ], "rows": 100 } ] ``` Result collections are limited to 10 items. This response shows the most recently created Alien Base V3 pools on Base, including WETH/DAI, WETH/AERO, and several stablecoin/token pairs, with fee tiers ranging from 200 to 10000. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/alien/v3/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/alien/v3/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /evm/alien/v3/pool - Returns current pool TVL, Swap Volume, Fees APR, Price volatility, Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for a specific Alien Base V3 pool. - /evm/aero/v3/pools - Returns a list of all Aerodrome V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - /evm/clones/v3/pools - Returns a list of all Clones V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - /evm/pancake/v3/pools - Returns a list of all PancakeSwap V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - /evm/sushi/v3/pools - Returns a list of all SushiSwap V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. --- ## Cambrian API: Supported Chains **Endpoint:** /api/v1/evm/chains # Supported Chains ## Overview Returns information about supported EVM blockchain networks. This endpoint returns a list of chain IDs and names for the EVM-compatible networks the Cambrian API supports. ## Business Value - **Network Discovery**: Easily identify which EVM networks are available for data queries - **Integration Planning**: Plan multi-chain applications by understanding supported networks - **Chain Validation**: Verify chain compatibility before making network-specific API calls - **Development Support**: Simplify blockchain application development with network enumeration - **Network Monitoring**: Track the expansion of supported blockchain networks over time ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/chains ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | - | - | - | - | This endpoint takes no query parameters | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | id | UInt32 | Numeric chain ID of the EVM network | | name | String | Human-readable name of the EVM network | ## Examples ### 1. List Supported EVM Chains Retrieve the list of all EVM chains currently supported by the API. ```bash curl -X GET "https://api.cambrian.org/evm/chains" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "id", "type": "UInt32" }, { "name": "name", "type": "String" } ], "data": [ [ 8453, "base" ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. In this result, one supported chain is returned: Base (chain ID 8453). ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/chains" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/chains") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /evm/dexes - List of DEXes on EVM compatible chains - /evm/tokens - Returns a list of all erc20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - /evm/price-current - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - /evm/price-hour - Returns historical hourly price data for a specified EVM token. - /evm/tvl/status - Returns the tokens held by an address --- ## Cambrian API: V3 - Pool Info **Endpoint:** /api/v1/evm/clones/v3/pool # Pool Info (Uniswap Clones V3) ## Overview Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR (Annual Percentage Rate), Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). This endpoint covers Uniswap V3 clone/fork deployments on supported EVM chains. ## Business Value - **Pool Analytics**: Access comprehensive liquidity pool data for DeFi analysis and monitoring - **Trading Intelligence**: Get real-time price, liquidity, and trading volume metrics for informed decision making - **Performance Tracking**: Monitor fee APRs, tick utilization, and swap activity across different time periods - **Token Information**: Retrieve detailed token pair data including addresses, symbols, and decimals - **Risk Assessment**: Analyze pool TVL, liquidity distribution, and trading patterns for risk management ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/clones/v3/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | pool_address | string | Yes | - | Pool address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | token0Address | String | Contract address of token0 in the pool. | | token0Symbol | String | Symbol of token0. | | token0Decimals | UInt8 | Decimal places for token0. | | token1Address | String | Contract address of token1 in the pool. | | token1Symbol | String | Symbol of token1. | | token1Decimals | UInt8 | Decimal places for token1. | | feeTier | UInt32 | Pool fee tier (in hundredths of a bip, e.g. 500 = 0.05%). | | tickSpacing | Int32 | Minimum tick spacing allowed for the pool. | | currentLiquidity | Nullable(Int256) | Current on-chain liquidity value of the pool. | | currentSqrtPriceX96 | Nullable(UInt256) | Current pool price expressed as sqrtPriceX96 (Uniswap V3 format). | | currentTick | Nullable(Int32) | Current active tick of the pool. | | currentPoolPrice | Nullable(Float64) | Current pool price of token0 in terms of token1 (human-readable). | | poolTvlUsd | Nullable(Float64) | Current Total Value Locked in the pool, denominated in USD. | | swapVolumeUsd | Map(String,Nullable(Float64)) | Swap volume in USD, keyed by time range (5 minute, 1 hour, 1 day, 1 week, 1 month, 1 year). | | feeApr | Map(String,Nullable(Float64)) | Fee-based Annual Percentage Rate, keyed by time range. | | priceVolatilityPct | Map(String,Float64) | Price volatility percentage, keyed by time range. | | priceVolatilityAdjustedPct | Map(String,Float64) | Mean-adjusted price volatility percentage, keyed by time range. | | tickPressurePer1MUsd | Map(String,Nullable(Float64)) | Tick pressure per $1M of volume, keyed by time range. | | swapCount | Map(String,UInt64) | Number of swaps executed in the pool, keyed by time range. | | uniqueUserCount | Map(String,UInt64) | Number of unique users who swapped in the pool, keyed by time range. | ## Examples ### 1. Get Current Pool Info for a Base Uniswap V3 Clone Pool This example retrieves the current TVL, price, and multi-timeframe volume/APR metrics for a specific pool (WBTC/cbBTC) on Base (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/clones/v3/pool?chain_id=8453&pool_address=0x5fdb371f38e2713139446a22b6472705c2cd3c9e" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** Note: Result collections in this example are limited to the first 10 items; the response structure and metadata are otherwise unchanged. ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2025-05-19T12:40:57+00:00", "0x0555e30da8f98308edb960aa94c0db47230d2b9c", "WBTC", 8, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, 500, 10, "1450597", "79221440124519138490223773807", -2, 0.9998303102245572, 2.045655168407765, { "1 day": 0.4214282629809602, "1 hour": 0, "1 month": 0.4214282629809602, "1 week": 0.4214282629809602, "1 year": 70.47077914092279, "5 minute": 0 }, { "1 day": 0.03759707852124883, "1 hour": 0, "1 month": 0.001236068334945167, "1 week": 0.005356296118095723, "1 year": 0.017224501037428924, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0, "1 week": 0, "1 year": 1, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0, "1 week": 0, "1 year": 1, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0, "1 week": 0, "1 year": 3779038677.3991437, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "1 month": 1, "1 week": 1, "1 year": 153, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "5 minute": 0 } ] ], "rows": 1 } ] ``` This pool (WBTC/cbBTC, 0.05% fee tier) currently has a TVL of roughly $2.05, a current price of ~0.99983, and shows minimal recent trading activity — with a single swap over the past day/week/month, 153 swaps over the past year, and near-zero volatility across most timeframes. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/clones/v3/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/clones/v3/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/clones/v3/pools` - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/price-current` - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - `/evm/uniswap/v3/pool` - Returns current pool TVL, Swap Volume, Fees APR, Price volatility, Tick Pressure, Swap Count, and Unique users for recent time ranges. - `/evm/tokens` - Returns a list of all ERC20 tokens for the specified EVM chain, including contract addresses, symbols, names, and decimal places. - `/evm/dexes` - List of DEXes on EVM compatible chains. --- ## Cambrian API: V3 - List Pools **Endpoint:** /api/v1/evm/clones/v3/pools # V3 Pools (Uniswap Clones) ## Overview Returns a list of all liquidity pools deployed by Uniswap V3 clone DEXs on a given EVM chain, including token pair details, fee tiers, tick spacing, and pool creation timestamps. Results can be filtered by token address and support flexible sorting and pagination. ## Business Value - **Pool Discovery**: Find liquidity pools across multiple Uniswap V3 clone DEXs in a single query, enabling comprehensive market analysis - **Token Pair Analysis**: Identify available trading pairs and their associated fee structures for optimal trading route planning - **Liquidity Monitoring**: Track pool creation patterns and growth across different decentralized exchanges - **Cross-DEX Comparison**: Compare fee tiers and pool availability across different Uniswap V3 clone implementations - **Integration Support**: Provide essential pool metadata for DEX aggregators, portfolio trackers, and analytics platforms ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/clones/v3/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | No | - | Pool token address. See tokens for valid addresses. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | | order_asc | array | No | - | List of column names to order by in ascending order divided by comma. Leave empty items to combine with descending order. | | order_desc | array | No | - | List of column names to order by in descending order divided by comma. Leave empty items to combine with ascending order. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the pool is deployed on. | | dexAddress | FixedString(42) | Contract address of the DEX factory/router associated with the pool. | | dexName | String | Name of the Uniswap V3 clone DEX (e.g., 9mm, Thick, Solidly). | | poolAddress | FixedString(42) | Contract address of the liquidity pool. | | token0Address | String | Contract address of the pool's token0. | | token0Symbol | String | Symbol of token0. | | token0Decimals | UInt8 | Decimal precision of token0. | | token1Address | String | Contract address of the pool's token1. | | token1Symbol | String | Symbol of token1. | | token1Decimals | UInt8 | Decimal precision of token1. | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | fee | UInt32 | Pool fee tier, in hundredths of a basis point (e.g., 2500 = 0.25%). | | tickSpacing | Int32 | Minimum tick spacing configured for the pool. | ## Examples ### 1. List All Pools on Base Retrieve the most recently created liquidity pools across all Uniswap V3 clone DEXs on Base (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/clones/v3/pools?chain_id=8453" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0xe65eb14f55c54563408b6d2388ed31307414bd34", "0xbb5cbdae23c5368557cc9a32337863eecf03cf9f", "wBEPE", 18, "0xc5a90b067ea7535c0be245fb0d52a8b9ae7f6adf", "BEPE", 18, "2026-07-11T07:13:53+00:00", 2500, 50], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0xd7cf4ea8fafbdbdbe01a090867cd65c308987bca", "0xc5a90b067ea7535c0be245fb0d52a8b9ae7f6adf", "BEPE", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-07-11T07:01:17+00:00", 2500, 50], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0xa2368f4d2d7400a7f08297e29414c8d52f730f76", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xc5a90b067ea7535c0be245fb0d52a8b9ae7f6adf", "BEPE", 18, "2026-07-09T21:40:05+00:00", 2500, 50], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0xf70434be24519e6dd196e4c192c127749336099e", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x962a4859b3195d5218f9d5cc85adf17a3dc66593", "P\u00e2\u0085\u00a1P", 18, "2026-06-28T19:56:11+00:00", 10000, 200], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0x71d7ff92d88f83d313a3e5e66b5ad8d12dbe5efc", "0x4087ff5f00daafdd24f93b72a4bfdc3e6b5c1fa8", "wDIG", 18, "0x962a4859b3195d5218f9d5cc85adf17a3dc66593", "P\u00e2\u0085\u00a1P", 18, "2026-06-28T19:22:41+00:00", 10000, 200], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0xa97ba40d6f060bcc28f9c03adf06b1e975e386f7", "0x4087ff5f00daafdd24f93b72a4bfdc3e6b5c1fa8", "wDIG", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-06-28T17:33:05+00:00", 10000, 200], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0xdfccc2fed71ad8d6f22e33d2817c2486a68edba6", "0x39916e508e389fbb4ddc3d1a38a5801f4ee253c7", "\u00f0\u009f\u00a7\u0099\u00e2\u0080\u008d\u00e2\u0099\u0082\u00ef\u00b8\u008f\u00f0\u009f\u0092\u00b8", 18, "0x817cab331aaa4c24b4e32024fca093ad40cba208", "\u00e2\u009d\u00a4\u00ef\u00b8\u008f", 18, "2026-06-27T01:59:23+00:00", 10000, 200], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0x8d642cdec519b5cf4b25eac520b3db682890d718", "0x817cab331aaa4c24b4e32024fca093ad40cba208", "\u00e2\u009d\u00a4\u00ef\u00b8\u008f", 18, "0xbb5cbdae23c5368557cc9a32337863eecf03cf9f", "wBEPE", 18, "2026-06-27T01:51:33+00:00", 10000, 200], [8453, "0xe6da85feb3b4e0d6aed95c41a125fba859bb9d24", "Thick", "0x368c1367c098ec6d2b3588c1020ecbc5f00b7c8f", "0x6be0745b111839d58609b09818cac71e47023e92", "TRASH", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-06-24T05:52:57+00:00", 500, 10], [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0x5108390ef7d79d863c3f1fac5c62c5bad40abfbe", "0x09aa909eea859f712f2ae3dd1872671d2363f6f4", "\u00e2\u009c\u00a8\u00e2\u009d\u00a4\u00ef\u00b8\u008f\u00e2\u0080\u008d\u00f0\u009f\u0094\u00a5\u00f0\u009f\u00a7\u0099\u00e2\u0080\u008d\u00e2\u0099\u0082\u00ef\u00b8\u008f", 18, "0x801003cccd1a4c6079c71d18c7dbe8375589b2ed", "$BITCOIN", 18, "2026-06-23T04:50:03+00:00", 10000, 200] ], "rows": 100 } ] ``` The response is capped to the first 10 rows for documentation purposes; the actual result set for this query contained 100 rows (as reported by `rows`). Pools are returned across multiple DEXs (9mm, Thick) and span a range of fee tiers and tick spacings, ordered by most recent creation time by default. ### 2. Find All Pools Containing a Specific Token Filter pools to only those that include cbBTC (`0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf`) as one of the pair tokens, limited to 5 results. ```bash curl -X GET "https://api.cambrian.org/evm/clones/v3/pools?chain_id=8453&token_address=0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf&limit=5" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "0xd7cf4ea8fafbdbdbe01a090867cd65c308987bca", "0xc5a90b067ea7535c0be245fb0d52a8b9ae7f6adf", "BEPE", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-07-11T07:01:17+00:00", 2500, 50], [8453, "0xe6da85feb3b4e0d6aed95c41a125fba859bb9d24", "Thick", "0x42818c1fb1353f077b99a9744466a474dc0c2e7e", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-05-17T11:31:39+00:00", 500, 10], [8453, "0xe6da85feb3b4e0d6aed95c41a125fba859bb9d24", "Thick", "0x8e92a2140ab2829ad1cc529becf46d6ddcdd8c82", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-05-04T14:18:13+00:00", 3000, 60], [8453, "0xe6da85feb3b4e0d6aed95c41a125fba859bb9d24", "Thick", "0x03c34b09c28896b3ef4d059385e3e3162ef5ee2d", "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "0xecac9c5f704e954931349da37f60e39f515c11c1", "LBTC", 8, "2026-04-23T08:10:05+00:00", 500, 10], [8453, "0x70fe4a44ea505cfa3a57b95cf2862d4fd5f0f687", "Solidly", "0xf4214e4ab39ddfdb0556fcf692998067a2af1dfe", "0x311935cd80b76769bf2ecc9d8ab7635b2139cf82", "SOL", 9, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-04-17T15:15:03+00:00", 1, 100] ], "rows": 5 } ] ``` All 5 requested rows are returned. cbBTC appears as either token0 or token1 across pools on three different DEXs (9mm, Thick, Solidly), paired against BEPE, USDC, WETH, LBTC, and SOL, with fee tiers ranging from 1 (0.0001%) to 3000 (0.3%). ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/clones/v3/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/clones/v3/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/clones/v3/pool` - Returns current pool TVL, swap volume, fees APR, price volatility, tick pressure, swap count, and unique users for recent time ranges. - `/evm/uniswap/v3/pools` - Returns a list of all Uniswap V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/aero/v3/pools` - Returns a list of all Aerodrome V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/sushi/v3/pools` - Returns a list of all SushiSwap V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/price-current` - Returns current price of a token calculated based on Uniswap V3 and clones liquidity pools. --- ## Cambrian API: List DEXes **Endpoint:** /api/v1/evm/dexes # List DEXes (EVM) ## Overview Returns the list of decentralized exchanges (DEXes) indexed by Cambrian on supported EVM-compatible chains. Each entry includes the DEX's on-chain factory/router address, display name, and the AMM algorithm it implements (e.g., Uniswap V3-style concentrated liquidity, algebra, or other custom logic). ## Business Value - **DEX Discovery**: Easily discover all DEXes operating across different EVM chains in one request - **Integration Planning**: Get comprehensive DEX information needed for multi-chain DeFi integrations - **Algorithm Analysis**: Understand the distribution of different AMM algorithms (Uniswap V3, Algebra, etc.) across chains - **Chain Coverage**: See which DEXes operate on specific chains like Base (chainId: 8453) - **Contract Verification**: Access verified DEX contract addresses for secure integrations ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/dexes ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. Currently only `8453` (Base) is supported. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the DEX is deployed on. | | address | FixedString(42) | On-chain factory/router contract address for the DEX. | | name | String | Human-readable name of the DEX. | | algorithm | LowCardinality(FixedString(10)) | AMM algorithm type used by the DEX (e.g., `univ3`, `algb`, `na`). | ## Examples ### 1. List all DEXes on Base Retrieve the full list of DEXes indexed on Base (chain ID 8453), the default and only currently supported chain. ```bash curl -X GET "https://api.cambrian.org/evm/dexes" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** > Note: The result collection is limited to the first 10 rows for display purposes. The `rows` field reflects the true total count returned by the API (38). ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "address", "type": "FixedString(42)" }, { "name": "name", "type": "String" }, { "name": "algorithm", "type": "LowCardinality(FixedString(10))" } ], "data": [ [ 8453, "0x7b72c4002ea7c276dd717b96b20f4956c5c904e7", "9mm", "univ3" ], [ 8453, "0x420dd381b31aef6683db6b902084cb0ffece40da", "Aerodrome", "na" ], [ 8453, "0x9592cd9b267748cbfbde90ac9f7df3c437a6d51b", "Aerodrome", "univ3" ], [ 8453, "0x5e7bb104d84c7cb9b682aac2f3d509f5f406809a", "Aerodrome ICL", "univ3" ], [ 8453, "0x0fd83557b2be93617c9c1c1b6fd549401c74558c", "AlienBase", "univ3" ], [ 8453, "0xfaa5f5f4a3c6ed4446f7b6014322c954d218690c", "Bagelswap", "univ3" ], [ 8453, "0x38015d05f4fec8afe15d7cc0386a126574e8077b", "BaseSwap", "univ3" ], [ 8453, "0xdc323d16c451819890805737997f4ede96b95e3e", "Basex", "univ3" ], [ 8453, "0x3774bbad02ebd18a49919e1ed473163d83882dae", "Candswap", "na" ], [ 8453, "0x3539da2adb3f8311d203d334f25f7bee604a5c50", "Crescent", "univ3" ] ], "rows": 38 } ] ``` This example shows the columnar table response format: `columns` describes each field's name and ClickHouse type, `data` contains one array per DEX row (in the same order as `columns`), and `rows` reports the total number of DEXes available (38 total on Base, with the first 10 shown here). Notable entries include Aerodrome (both `na` and `univ3` algorithm variants), UniswapV3, SushiSwap, PancakeV3, and KyberSwap. ### 2. Explicitly specify chain_id Same request, explicitly passing the `chain_id` query parameter instead of relying on the default. ```bash curl -X GET "https://api.cambrian.org/evm/dexes?chain_id=8453" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** Identical to Example 1: passing `chain_id=8453` explicitly returns the same 38-row DEX list for Base, since 8453 is both the default and currently the only supported chain ID. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), letting you pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/dexes" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/dexes") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/tokens` - Returns a list of all erc20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - `/evm/price-current` - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - `/evm/uniswap/v3/pools` - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/aero/v2/pools` - Returns liquidity pools with summary metrics for the previous 7 completed UTC days. - `/evm/sushi/v3/pools` - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. --- ## Cambrian API: Lending protocols endpoint **Endpoint:** /api/v1/evm/lending/protocols # Lending Protocols ## Overview This endpoint lists the lending protocols supported on EVM-compatible chains, returning each protocol's identifier, human-readable name, and number of active pools. ## Business Value - **Protocol Discovery**: Quickly identify which lending protocols are supported before querying protocol-specific endpoints. - **Coverage Insight**: The `poolCount` field indicates the breadth of data available for each protocol, helping prioritize integration efforts. - **Cross-Protocol Comparison**: Enables side-by-side comparison of protocol adoption and pool counts on a given chain. - **Integration Planning**: Serves as an entry point for building dashboards or tools that aggregate lending data across multiple protocols. ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/lending/protocols ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offsets the results, letting you skip a number of rows before rows are returned. | | order_asc | array | No | - | List of column names to order by in ascending order divided by comma. Leave empty items to combine with descending order. Allowed values: chainId, protocolId, protocolName, poolCount. | | order_desc | array | No | - | List of column names to order by in descending order divided by comma. Leave empty items to combine with ascending order. Allowed values: chainId, protocolId, protocolName, poolCount. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the protocol is deployed on. | | protocolId | FixedString(50) | Unique identifier for the lending protocol. | | protocolName | FixedString(50) | Human-readable name of the lending protocol. | | poolCount | UInt64 | Number of lending pools available for the protocol. | ## Examples ### 1. List Lending Protocols on Base Retrieve all supported lending protocols on the Base chain. ```bash curl -X GET "https://api.cambrian.org/evm/lending/protocols" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "protocolId", "type": "FixedString(50)" }, { "name": "protocolName", "type": "FixedString(50)" }, { "name": "poolCount", "type": "UInt64" } ], "data": [ [ 8453, "aave-v3", "Aave V3", 15 ], [ 8453, "euler-lend", "Euler Lend", 354 ], [ 8453, "morpho-v1", "Morpho V1", 498 ], [ 8453, "morpho-v2", "Morpho V2", 2945 ] ], "rows": 4 } ] ``` Note: Result collections are limited to 10 items. This response lists the 4 lending protocols supported on Base (chain ID 8453); Morpho V2 has the most pools (2945). ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), letting you pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/lending/protocols" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/lending/protocols") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: V3 - Pool Info **Endpoint:** /api/v1/evm/pancake/v3/pool # PancakeSwap V3 Pool Info ## Overview Returns current pool state and performance metrics for a PancakeSwap V3 liquidity pool on Base, including TVL, swap volume, fee APR, price volatility, tick pressure, swap count, and unique user count across multiple recent time ranges (5 minutes, 1 hour, 1 day, 1 week, 1 month, and 1 year). ## Business Value - **Pool Performance Monitoring**: Track key metrics like TVL, volume, and fees to assess pool health and profitability - **Liquidity Analysis**: Monitor price tick utilization to understand how efficiently liquidity is being used - **User Activity Insights**: Analyze swap counts and unique user metrics across different time periods for activity trends - **APR Calculations**: Access fees APR data for yield farming and liquidity provision decision making - **Historical Context**: Compare performance across multiple time ranges from 5 minutes to 1 year for trend analysis ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/pancake/v3/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. Only 8453 (Base) is currently supported. | | pool_address | string | Yes | - | Pool address with 0x prefix (e.g., `0xC211e1f853A898Bd1302385CCdE55f33a8C4B3f3`) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | String | Contract address of token0 in the pool | | token0Symbol | String | Symbol of token0 | | token0Decimals | UInt8 | Decimal precision of token0 | | token1Address | String | Contract address of token1 in the pool | | token1Symbol | String | Symbol of token1 | | token1Decimals | UInt8 | Decimal precision of token1 | | feeTier | UInt32 | Pool fee tier in hundredths of a basis point (e.g., 100 = 0.01%) | | tickSpacing | Int32 | Minimum tick spacing allowed for the pool's fee tier | | currentLiquidity | Nullable(Int256) | Current in-range liquidity of the pool | | currentSqrtPriceX96 | Nullable(UInt256) | Current pool price expressed as sqrt(price) * 2^96 | | currentTick | Nullable(Int32) | Current tick of the pool | | currentPoolPrice | Nullable(Float64) | Current pool price of token1 in terms of token0 | | poolTvlUsd | Nullable(Float64) | Current total value locked in the pool, in USD | | swapVolumeUsd | Map(String,Nullable(Float64)) | Swap volume in USD, keyed by time range (5 minute, 1 hour, 1 day, 1 week, 1 month, 1 year) | | feeApr | Map(String,Nullable(Float64)) | Annualized fee APR, keyed by time range | | priceVolatilityPct | Map(String,Float64) | Price volatility percentage, keyed by time range | | priceVolatilityAdjustedPct | Map(String,Float64) | Mean-adjusted price volatility percentage, keyed by time range | | tickPressurePer1MUsd | Map(String,Nullable(Float64)) | Tick movement pressure per $1M of swap volume, keyed by time range | | swapCount | Map(String,UInt64) | Number of swaps, keyed by time range | | uniqueUserCount | Map(String,UInt64) | Number of unique users who swapped, keyed by time range | ## Examples ### 1. WETH/cbBTC Pool Info Fetch current metrics for the WETH/cbBTC pool on Base, a high-volume, low-fee-tier pool. ```bash curl -X GET "https://api.cambrian.org/evm/pancake/v3/pool?pool_address=0xC211e1f853A898Bd1302385CCdE55f33a8C4B3f3&chain_id=8453" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2024-09-13T06:45:47+00:00", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, 100, 1, "183379827491988582", "135353135126901401813605", -265613, 0.02918619445882321, 5570127.537101628, { "1 day": 45386421.69582063, "1 hour": 1046296.7716726399, "1 month": 1167595215.148688, "1 week": 298708324.39242345, "1 year": 16634739479.090212, "5 minute": 27645.496733862878 }, { "1 day": 0.2974087004046328, "1 hour": 0.1645484714452616, "1 month": 0.25154078588790885, "1 week": 0.2788595550989557, "1 year": 0.29864198563298905, "5 minute": 0.05217285595898275 }, { "1 day": 0.006165682666121917, "1 hour": 0.000828430427998967, "1 month": 0.047890380137098024, "1 week": 0.018637632675020162, "1 year": 0.32084449215406996, "5 minute": 0.00010840403858738094 }, { "1 day": 0.00004879570381228392, "1 hour": 0.00004239785360524167, "1 month": 0.000058885738322169586, "1 week": 0.00005356623642117787, "1 year": 0.0000986476371848453, "5 minute": 0.00002050277335630321 }, { "1 day": 108.5126303414555, "1 hour": 96.53092959327257, "1 month": 190.95487640518232, "1 week": 132.82857141897043, "1 year": 280.37331187918795, "5 minute": 108.51676961641675 }, { "1 day": 15966, "1 hour": 381, "1 month": 661418, "1 week": 121057, "1 year": 10578298, "5 minute": 10 }, { "1 day": 99, "1 hour": 33, "5 minute": 6 } ] ], "rows": 1 } ] ``` This pool shows strong sustained activity: ~$45.4M in 1-day swap volume, a 1-day fee APR of ~29.7%, and 99 unique users trading over the past day, reflecting a deep, actively-traded WETH/cbBTC market. Note that some time-range keys (e.g. "1 month", "1 week", "1 year") are absent from `uniqueUserCount` in this response, indicating no data was available for that range. ### 2. QUID/USDC Pool Info Fetch current metrics for a lower-volume, wider fee-tier pool (QUID/USDC) to illustrate a pool with minimal recent activity. ```bash curl -X GET "https://api.cambrian.org/evm/pancake/v3/pool?pool_address=0xac84c1ddb3af32261dce60d040b0ff9c812d2cb3&chain_id=8453" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2026-08-04T12:59:03+00:00", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, 2500, 50, "341700416721311060", "29120682046261131917882", -296343, 0.13509644396215864, 32.90854723892649, { "1 day": 40810.47115018515, "1 hour": 0, "1 month": 40810.47115018515, "1 week": 40810.47115018515, "1 year": 40810.47115018515, "5 minute": 0 }, { "1 day": 1, "1 hour": 0, "1 month": 1, "1 week": 1, "1 year": 1, "5 minute": 0 }, { "1 day": 0.059949635246689253, "1 hour": 0, "1 month": 0.059949635246689253, "1 week": 0.059949635246689253, "1 year": 0.059949635246689253, "5 minute": 0 }, { "1 day": 0.0035954549356848144, "1 hour": 0, "1 month": 0.0035954549356848144, "1 week": 0.0035954549356848144, "1 year": 0.0035954549356848144, "5 minute": 0 }, { "1 day": 3215.351264069018, "1 hour": 0, "1 month": 3215.351264069018, "1 week": 3215.351264069018, "1 year": 3215.351264069018, "5 minute": 0 }, { "1 day": 278, "1 hour": 0, "1 month": 278, "1 week": 278, "1 year": 278, "5 minute": 0 }, { "1 day": 27, "1 hour": 0, "5 minute": 0 } ] ], "rows": 1 } ] ``` This pool was created on the same day as the query, so all longer time-range windows (1 week, 1 month, 1 year) show identical values equal to the 1-day figures, and the 1-hour/5-minute windows show zero activity, reflecting a newly-created pool with limited trading history. TVL is only ~$33, indicating this pool has negligible liquidity. *Note: Each result collection in the example responses above is limited to its first 10 items for documentation purposes.* ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/pancake/v3/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/pancake/v3/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/pancake/v3/pools` - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/uniswap/v3/pool` - Returns current pool TVL, swap volume, fee APR, price volatility, tick pressure, swap count, and unique users for a Uniswap V3 pool. - `/evm/sushi/v3/pool` - Returns current pool TVL, swap volume, fee APR, price volatility, tick pressure, swap count, and unique users for a Sushi V3 pool. - `/evm/aero/v3/pool` - Returns current pool TVL, swap volume, price volatility, tick pressure, swap count, and unique users for an Aerodrome V3 pool. - `/evm/alien/v3/pool` - Returns current pool TVL, swap volume, fee APR, price volatility, tick pressure, swap count, and unique users for an Alien V3 pool. --- ## Cambrian API: V3 - List Pools **Endpoint:** /api/v1/evm/pancake/v3/pools # PancakeSwap V3 Pool List ## Overview Returns a list of all PancakeSwap V3 liquidity pools on the specified EVM chain, including token pairs, fee tiers, and creation timestamps. Results can be filtered by a specific token address and sorted by any of the available columns. ## Business Value - **Pool Discovery**: Identify all available liquidity pools for trading and liquidity provision strategies - **Market Analysis**: Analyze pool distribution, fee structures, and token pair availability across chains - **Portfolio Management**: Track and monitor multiple pools for yield farming and LP position management - **DeFi Integration**: Build applications that require comprehensive pool data for routing and analytics - **Risk Assessment**: Evaluate pool diversity and concentration for informed investment decisions ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/pancake/v3/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | No | - | Pool token address. See tokens for valid addresses. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | | order_asc | array | No | - | List of column names to order by in ascending order divided by comma. Leave empty items to combine with descending order. | | order_desc | array | No | - | List of column names to order by in descending order divided by comma. Leave empty items to combine with ascending order. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the pool exists on. | | dexAddress | FixedString(42) | Contract address of the DEX factory/deployment. | | dexName | String | Name of the DEX (e.g., PancakeV3). | | poolAddress | FixedString(42) | Contract address of the liquidity pool. | | token0Address | String | Contract address of the pool's first token. | | token0Symbol | String | Symbol of the pool's first token. | | token0Decimals | UInt8 | Decimal places of the pool's first token. | | token1Address | String | Contract address of the pool's second token. | | token1Symbol | String | Symbol of the pool's second token. | | token1Decimals | UInt8 | Decimal places of the pool's second token. | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | fee | UInt32 | Pool fee tier, in hundredths of a basis point. | | tickSpacing | Int32 | Minimum tick spacing for the pool. | ## Examples ### 1. List Recent Pools Retrieve the most recently created PancakeSwap V3 pools on Base (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/pancake/v3/pools?chain_id=8453&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** Note: This response has been truncated to the first 10 items per collection for documentation purposes; the `rows` field reflects the truncated count. ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0xab6254061c6a382f04ba8d40ddf5f5c8a4766132", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T13:06:49+00:00", 500, 10 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0xac84c1ddb3af32261dce60d040b0ff9c812d2cb3", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-08-04T12:59:03+00:00", 2500, 50 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0xbc3bb9735c675a579182e6a198c2982222ff5763", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T11:17:39+00:00", 2500, 50 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x07ddac89189821ff7ce8fb3c0ba36b7e0b0487ec", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T10:26:35+00:00", 10000, 200 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x735937e28a89b8f48e36bb61d03fdfd5f3d7a337", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-08-04T08:54:11+00:00", 10000, 200 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0xbc9165c93a050941ca6b11b60540a9bfdd26265a", "0x584fbca587e2bbea9bec6cac60370f6ed20a49c4", "USDC", 18, "0x715324e1567bf6c59d917edca0dea2f235a6320f", "ZEC", 18, "2026-08-04T07:04:51+00:00", 2500, 50 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0xb8a4fffdbf061fd80cc9c780d4ac466cb40bdeb4", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xc3de830ea07524a0761646a6a4e4be0e114a3c83", "UNI", 18, "2026-08-03T22:04:53+00:00", 2500, 50 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x07c4bc0f5fb6cb069124df3e1ae0b8fd8148ccc4", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-08-03T15:39:01+00:00", 100, 1 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x2205fe810ad4c3cb07bff00afa6dc9c3b9a02af6", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xef8e8032a3730a7f3516359524dbf97f67e3ac6d", "b3m", 18, "2026-08-01T18:12:29+00:00", 100, 1 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x8d737d1304ab90e4c81b0528e33f385511596c0b", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xeb25035e8b481115145892a3f5e42455b7642302", "ANDY", 18, "2026-07-31T22:48:09+00:00", 500, 10 ] ], "rows": 10 } ] ``` This returns the 10 most recently created PancakeSwap V3 pools on Base, showing a mix of token pairs (e.g., QUID/WETH, QUID/USDC, USDC/ZEC) along with their fee tiers ranging from 0.01% (100) to 1% (10000) and corresponding tick spacings. ### 2. Filter Pools by Token Address Find all PancakeSwap V3 pools that include a specific token, such as USDC on Base. ```bash curl -X GET "https://api.cambrian.org/evm/pancake/v3/pools?chain_id=8453&token_address=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&limit=5" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** Note: This response has been truncated to the first 10 items per collection for documentation purposes; the `rows` field reflects the truncated count. ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0xac84c1ddb3af32261dce60d040b0ff9c812d2cb3", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-08-04T12:59:03+00:00", 2500, 50 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x735937e28a89b8f48e36bb61d03fdfd5f3d7a337", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-08-04T08:54:11+00:00", 10000, 200 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0xb8a4fffdbf061fd80cc9c780d4ac466cb40bdeb4", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xc3de830ea07524a0761646a6a4e4be0e114a3c83", "UNI", 18, "2026-08-03T22:04:53+00:00", 2500, 50 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x07c4bc0f5fb6cb069124df3e1ae0b8fd8148ccc4", "0x1a44233fae8d50f1aeb3a5d58dd426ff4814cb53", "QUID", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-08-03T15:39:01+00:00", 100, 1 ], [ 8453, "0x0bfbcf9fa4f9c56b0f40a671ad40e0805a091865", "PancakeV3", "0x2205fe810ad4c3cb07bff00afa6dc9c3b9a02af6", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xef8e8032a3730a7f3516359524dbf97f67e3ac6d", "b3m", 18, "2026-08-01T18:12:29+00:00", 100, 1 ] ], "rows": 5 } ] ``` This returns all pools where USDC (`0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`) is one of the paired tokens, useful for identifying every fee tier and counterpart token available for USDC trading on PancakeSwap V3. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2). Pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/pancake/v3/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/pancake/v3/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/pancake/v3/pool` - Returns current pool TVL, swap volume, fees APR, price volatility, tick pressure, swap count, and unique users for a specific PancakeSwap V3 pool. - `/evm/uniswap/v3/pools` - Returns a list of all Uniswap V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/aero/v3/pools` - Returns a list of all Aerodrome V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/tokens` - Returns a list of all ERC20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - `/evm/price-current` - Returns current price of a token calculated based on Uniswap V3 and clones liquidity pools. --- ## Cambrian API: Token Price (Current) **Endpoint:** /api/v1/evm/price-current # Token Price (Current) ## Overview Returns the current USD price of a token on Base, computed from the live state of its Uniswap V3 and clone liquidity pools. The price is derived from current pool reserves rather than the last trade, so it reflects what the pools imply the token is worth right now, and refreshes roughly once a minute. ## Business Value - **No Price Feed to Maintain**: Get a token's USD price without reading pool contracts or running your own pricing pipeline. ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/price-current ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | No | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 | Address of the token prefixed with 0x. See white listed tokens | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the token was queried on | | tokenAddress | String | Contract address of the token | | symbol | String | Token symbol | | priceUsd | Float64 | Current price of the token in USD | ## Examples ### 1. Get Current Price of USDC on Base This example retrieves the current USD price for USDC on the Base chain (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/price-current?chain_id=8453&token_address=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "priceUsd", "type": "Float64" } ], "data": [ [8453, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 1] ], "rows": 1 } ] ``` USDC, a stablecoin, returns a `priceUsd` of `1`, as expected. ### 2. Get Current Price of WETH on Base This example demonstrates fetching the current price of a volatile asset (Wrapped ETH) instead of a stablecoin. ```bash curl -X GET "https://api.cambrian.org/evm/price-current?chain_id=8453&token_address=0x4200000000000000000000000000000000000006" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "priceUsd", "type": "Float64" } ], "data": [ [8453, "0x4200000000000000000000000000000000000006", "WETH", 1873.0114249392152] ], "rows": 1 } ] ``` The response returns WETH's current market price (~$1,873.01 USD at time of query), reflecting live DEX liquidity pool pricing. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/price-current" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/price-current") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/price-hour` - Returns historical hourly price data for a specified EVM token. - `/evm/tokens` - Returns a list of all erc20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - `/evm/tvl/top-owners` - Returns top token holders for a given token address. - `/evm/tvl/status` - Returns the tokens held by an address. - `/evm/dexes` - List of DEXes on EVM compatible chains. --- ## Cambrian API: Token Price (Hourly) **Endpoint:** /api/v1/evm/price-hour # Token Price (Hourly) ## Overview Returns historical hourly price data for a specified EVM token, expressed in USD. Prices are aggregated per UTC hour, which supports building price charts, computing historical returns, and analyzing intraday volatility for tokens on supported EVM chains. ## Business Value - **Historical Price Analysis**: Track price movements and trends over specific hourly intervals for investment research - **Trading Strategy Development**: Access precise historical data points for backtesting and algorithm development - **Market Research**: Analyze price volatility patterns and market behavior during specific time periods - **Portfolio Performance**: Monitor historical value changes of token holdings with granular hour-by-hour precision - **Risk Management**: Identify price patterns and volatility metrics for better risk assessment ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/price-hour ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | Yes | - | Token address. See tokens for valid address for a chain. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the price data belongs to. | | tokenAddress | String | Contract address of the token (lowercase). | | tokenSymbol | String | Ticker symbol of the token. | | blockHour | DateTime('UTC') | UTC timestamp representing the hour bucket for this price point. | | priceUsd | Float64 | Token price in USD at the given hour. | ## Examples ### 1. Fetch Recent Hourly Prices for cbBTC Retrieves the 10 most recent hourly price points for cbBTC on Base (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/price-hour?chain_id=8453&token_address=0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "tokenAddress", "type": "String" }, { "name": "tokenSymbol", "type": "String" }, { "name": "blockHour", "type": "DateTime('UTC')" }, { "name": "priceUsd", "type": "Float64" } ], "data": [ [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T22:00:00+00:00", 64177.215778131795], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T21:00:00+00:00", 64208.167037659805], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T20:00:00+00:00", 64174.28249007726], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T19:00:00+00:00", 64279.17095921872], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T18:00:00+00:00", 64220.04673331491], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T17:00:00+00:00", 64027.284264131915], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T16:00:00+00:00", 63983.050204851424], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T15:00:00+00:00", 64010.97871050138], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T14:00:00+00:00", 63832.20059783007], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T13:00:00+00:00", 63862.37962062325] ], "rows": 10 } ] ``` *Note: The result collection above is limited to its first 10 items for documentation purposes; the full response may contain more rows depending on the requested `limit`.* The response shows cbBTC's hourly USD price from 13:00 to 22:00 UTC on 2026-08-04, moving from roughly $63,862 to $64,177. Each row represents one hourly `blockHour` bucket. ### 2. Paginate Through Older Price History Uses `offset` to skip the 10 most recent hours and fetch the next 5 hourly price points further back in time. ```bash curl -X GET "https://api.cambrian.org/evm/price-hour?chain_id=8453&token_address=0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf&limit=5&offset=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "tokenAddress", "type": "String" }, { "name": "tokenSymbol", "type": "String" }, { "name": "blockHour", "type": "DateTime('UTC')" }, { "name": "priceUsd", "type": "Float64" } ], "data": [ [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T12:00:00+00:00", 63844.36432815222], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T11:00:00+00:00", 63744.43386940641], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T10:00:00+00:00", 63577.698540319114], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T09:00:00+00:00", 63516.873793780076], [8453, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", "2026-08-04T08:00:00+00:00", 63588.41214804222] ], "rows": 5 } ] ``` *Note: The result collection above is limited to its first 10 items for documentation purposes; this example returned 5 rows because `limit=5` was requested.* This demonstrates pagination: with `offset=10`, the response starts at hour `12:00:00 UTC`, i.e. the hour immediately preceding the last row returned in Example 1. This confirms continuous, non-overlapping hourly coverage. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/price-hour" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/price-hour") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/price-current` - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - `/evm/tokens` - Returns a list of all erc20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - `/evm/tvl/top-owners` - Returns top token holders for a given token address. - `/evm/tvl/status` - Returns the tokens held by an address - `/evm/dexes` - List of DEXes on EVM compatible chains --- ## Cambrian API: V3 - Pool Info **Endpoint:** /api/v1/evm/sushi/v3/pool # Sushi V3 Pool Info ## Overview Returns real-time and historical metrics for a specific Sushi V3 liquidity pool on an EVM chain, including TVL, swap volume, fee APR, price volatility, tick pressure, swap counts, and unique users across multiple time ranges (5 minutes, 1 hour, 1 day, 1 week, 1 month, and 1 year). ## Business Value - **Pool Performance Analysis**: Track key metrics like TVL, volume, and fees APR to evaluate individual pool performance across different timeframes - **Liquidity Provider Insights**: Monitor tick utilization and fee generation to optimize liquidity provision strategies and assess pool efficiency - **Trading Activity Monitoring**: Analyze swap counts and unique user metrics to understand pool usage patterns and market activity levels - **Risk Assessment**: Compare metrics across different time periods to identify trends, volatility patterns, and potential risks in specific pools - **Portfolio Management**: Make informed decisions about liquidity allocation by comparing performance metrics across different Sushi V3 pools ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/sushi/v3/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | pool_address | string | Yes | - | Pool address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | token0Address | String | Contract address of the pool's token0. | | token0Symbol | String | Symbol of token0. | | token0Decimals | UInt8 | Decimal precision of token0. | | token1Address | String | Contract address of the pool's token1. | | token1Symbol | String | Symbol of token1. | | token1Decimals | UInt8 | Decimal precision of token1. | | feeTier | UInt32 | Pool fee tier in hundredths of a basis point (e.g. 500 = 0.05%). | | tickSpacing | Int32 | Minimum tick spacing configured for the pool. | | currentLiquidity | Nullable(Int256) | Current in-range liquidity of the pool. | | currentSqrtPriceX96 | Nullable(UInt256) | Current pool price expressed as sqrt(price) * 2^96. | | currentTick | Nullable(Int32) | Current tick of the pool. | | currentPoolPrice | Nullable(Float64) | Current pool price of token0 in terms of token1 (or vice versa, decimal-adjusted). | | poolTvlUsd | Nullable(Float64) | Current Total Value Locked in the pool, in USD. Null when a required token price is unavailable. | | swapVolumeUsd | Map(String,Nullable(Float64)) | Swap volume in USD, keyed by time range (5 minute, 1 hour, 1 day, 1 week, 1 month, 1 year). | | feeApr | Map(String,Nullable(Float64)) | Annualized fee APR, keyed by time range. | | priceVolatilityPct | Map(String,Float64) | Price volatility (percentage) over each time range. | | priceVolatilityAdjustedPct | Map(String,Float64) | Mean-adjusted price volatility (percentage) over each time range. | | tickPressurePer1MUsd | Map(String,Nullable(Float64)) | Tick movement pressure per $1M of volume, keyed by time range. | | swapCount | Map(String,UInt64) | Number of swaps executed in the pool, keyed by time range. | | uniqueUserCount | Map(String,UInt64) | Number of unique addresses that swapped in the pool, keyed by time range. | ## Examples ### 1. Established WETH/USDC Pool Metrics This example fetches metrics for a mature, high-volume WETH/USDC pool on Base, showing populated TVL, volume, and APR data across all time ranges. ```bash curl -X GET "https://api.cambrian.org/evm/sushi/v3/pool?chain_id=8453&pool_address=0x57713f7716e0b0f65ec116912f834e49805480d2" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2023-12-23T13:09:57+00:00", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, 500, 10, "12168291628959629", "3429390148551778643869805", -200965, 1873.5902788836208, 133085.05823142148, { "1 day": 84784.81064076404, "1 hour": 1672.4626284147264, "1 month": 2859603.0993273193, "1 week": 612322.8090306392, "1 year": 106096654.54211769, "5 minute": 16.26196159475969 }, { "1 day": 0.11626570366023403, "1 hour": 0.05504289068813716, "1 month": 0.12892220076372923, "1 week": 0.11962569837939782, "1 year": 0.39860468166766816, "5 minute": 0.006422424220863941 }, { "1 day": 0.007793798241932551, "1 hour": 0.00096295770573279, "1 month": 0.05946016418751398, "1 week": 0.02136517147094936, "1 year": 0.3729483301702738, "5 minute": 6.174395700693347e-05 }, { "1 day": 0.00016239576284365244, "1 hour": 0.00012815107552587344, "1 month": 0.00021172025419513254, "1 week": 0.00016551055173691904, "1 year": 0.00023320572177512342, "5 minute": 0 }, { "1 day": 3781.3376898179617, "1 hour": 3766.9003139230485, "1 month": 4146.099856581147, "1 week": 3736.591167691605, "1 year": 2822.4122739056443, "5 minute": 0 }, { "1 day": 2302, "1 hour": 52, "1 month": 78872, "1 week": 16662, "1 year": 2557516, "5 minute": 1 }, { "1 day": 37, "1 hour": 10, "5 minute": 1 } ] ], "rows": 1 } ] ``` This pool (WETH/USDC, 0.05% fee tier) shows a healthy ~$133K TVL with strong recent activity: 2,302 swaps and 37 unique users in the last day, and a 1-day fee APR of ~11.6%. ### 2. Newer Pool with Sparse Trading History This example queries a much newer, lower-activity USDC/AXONE pool, illustrating how USD-denominated fields (TVL, swap volume, fee APR, tick pressure) return `null` when a required token price is unavailable, while non-USD fields like swap counts remain populated. ```bash curl -X GET "https://api.cambrian.org/evm/sushi/v3/pool?chain_id=8453&pool_address=0xeb0d1bae8d3d9f4f877d292fa8c30feecbb1cb0c" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2026-07-21T09:36:57+00:00", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xd15609adafa9edae304c0b8ae26935ed468468c5", "AXONE", 18, 100, 1, "13416023159057683", "50935946474403620283368423458634800", 267488, 0.4133230195421529, null, { "1 day": null, "1 hour": null, "1 month": null, "1 week": null, "1 year": null, "5 minute": null }, { "1 day": null, "1 hour": null, "1 month": null, "1 week": null, "1 year": null, "5 minute": null }, { "1 day": 0, "1 hour": 0, "1 month": 0.6196535853661563, "1 week": 0, "1 year": 0.6196535853661563, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "1 month": 0.005472061116799801, "1 week": 0, "1 year": 0.005472061116799801, "5 minute": 0 }, { "1 day": null, "1 hour": null, "1 month": null, "1 week": null, "1 year": null, "5 minute": null }, { "1 day": 0, "1 hour": 0, "1 month": 12820, "1 week": 0, "1 year": 12820, "5 minute": 0 }, { "1 day": 0, "1 hour": 0, "5 minute": 0 } ] ], "rows": 1 } ] ``` This 0.01% fee tier USDC/AXONE pool has had no trading activity in the last day, week, or hour (all zero swap counts), so `poolTvlUsd`, `swapVolumeUsd`, `feeApr`, and `tickPressurePer1MUsd` are `null` since no recent priced trades exist to compute them, while price volatility and 1-month swap count (12,820) remain available. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/sushi/v3/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/sushi/v3/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/sushi/v3/pools` - Returns a list of all Sushi V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/uniswap/v3/pool` - Returns the same set of pool metrics (TVL, volume, fee APR, volatility) for a Uniswap V3 pool. - `/evm/aero/v3/pool` - Returns the same set of pool metrics for an Aerodrome V3 pool. - `/evm/pancake/v3/pool` - Returns the same set of pool metrics for a PancakeSwap V3 pool. - `/evm/price-current` - Returns current price of a token calculated based on Uniswap V3 and clones liquidity pools. --- ## Cambrian API: V3 - List Pools **Endpoint:** /api/v1/evm/sushi/v3/pools # Sushi V3 Pools List ## Overview Returns a list of all Sushi V3 liquidity pools on the specified EVM chain, including token pair details, pool fee tiers, tick spacing, and pool creation timestamps. ## Business Value - **DEX Analytics**: Access comprehensive pool data for Sushi V3 across multiple EVM chains for trading analysis and liquidity monitoring - **Token Research**: Identify all pools containing specific tokens to understand trading venues and liquidity distribution - **Pool Discovery**: Find new and existing pools with detailed metadata including fees, tick spacing, and creation dates - **Cross-Chain Visibility**: Monitor Sushi V3 pools across different EVM networks from a single API endpoint - **Historical Tracking**: Track pool creation patterns and growth over time with timestamp data ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/sushi/v3/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | No | - | Pool token address. See tokens for valid addresses. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | | order_asc | array | No | - | List of column names to order by in ascending order divided by comma. Leave empty items to combine with descending order. | | order_desc | array | No | - | List of column names to order by in descending order divided by comma. Leave empty items to combine with ascending order. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the pool resides on. | | dexAddress | FixedString(42) | Contract address of the Sushi DEX factory/router. | | dexName | String | Name of the DEX (e.g., "Sushi"). | | poolAddress | FixedString(42) | Contract address of the liquidity pool. | | token0Address | String | Contract address of the pool's first token. | | token0Symbol | String | Symbol of the pool's first token. | | token0Decimals | UInt8 | Decimal precision of the first token. | | token1Address | String | Contract address of the pool's second token. | | token1Symbol | String | Symbol of the pool's second token. | | token1Decimals | UInt8 | Decimal precision of the second token. | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | fee | UInt32 | Pool fee tier (in hundredths of a basis point). | | tickSpacing | Int32 | Minimum tick spacing configured for the pool. | ## Examples ### 1. List Recent Sushi V3 Pools on Base Retrieves the 10 most recently created Sushi V3 pools on Base (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/sushi/v3/pools?chain_id=8453&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x9ae052f3ded98d49b4335ded6ebfb011faa48ba2", "0x465bef0eafc41ca394cc34fb4b93f6ed7ab0651f", "LOAMD", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-07-28T14:10:49+00:00", 100, 1], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x7644ecc6291fe415c2f93a5ec8b48daa377ec773", "0x3190efd462af7c31d1fbd9e11dba48d5ba19a1d3", "AXONE", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-07-28T10:41:19+00:00", 100, 1], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0xeb0d1bae8d3d9f4f877d292fa8c30feecbb1cb0c", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xd15609adafa9edae304c0b8ae26935ed468468c5", "AXONE", 18, "2026-07-21T09:36:57+00:00", 100, 1], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x40ea7063aa0b439f68d2eb2127ca6fa5ce73291a", "0x50626097a780881d3dff1ff97579e6daf965366b", "MTP", 18, "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2", "USDT", 6, "2026-07-21T04:07:59+00:00", 100, 1], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0xfb545b9b3f17b4b0e0557ec485b224a023741cf1", "0x915ce8b817cb7f73961c26e4e8f8cad8f055b2e7", "VELP", 18, "0xd28d45d98693518fb30f5164d17c3046d4345f92", "VPR", 18, "2026-07-12T05:57:17+00:00", 500, 10], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0xf2a1c64f05c01ed6b97734a209c8014736527f0a", "0xb19d62d612b7bfd03de4ea59531694f85d7e2b07", "SpaceX", 18, "0xf43eb8de897fbc7f2502483b2bef7bb9ea179229", "ZEN", 18, "2026-07-09T21:22:17+00:00", 10000, 200], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x32c14c2a566438c7b17307fb8ccb15cfa3b49605", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xb200000000000000000000a775a213683f1fa301", "BASE", 18, "2026-07-09T17:50:55+00:00", 10000, 200], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0xc616051e007baaa5c7f27e0732ec43d618af3dea", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x7428eb1bf1cc91a93532029948c4813e9a15159c", "VPRU", 18, "2026-07-07T17:51:49+00:00", 10000, 200], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x2beff8b42ab06bd50bf22dec75fb2694ac0a9469", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xd28d45d98693518fb30f5164d17c3046d4345f92", "VPR", 18, "2026-07-07T16:01:15+00:00", 10000, 200], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x282c51f1875876b44b571261aa34b5cd29a17b72", "0x7428eb1bf1cc91a93532029948c4813e9a15159c", "VPRU", 18, "0xd28d45d98693518fb30f5164d17c3046d4345f92", "VPR", 18, "2026-07-06T05:09:13+00:00", 10000, 200] ], "rows": 10 } ] ``` *Note: The `data` array shown above is limited to the first 10 rows returned by the API for this documentation example.* This example shows the 10 most recently created Sushi V3 pools on Base. All are operated by the same DEX factory address, with fee tiers of 100, 500, and 10000. ### 2. Filter Pools by Token Address Retrieves Sushi V3 pools that include USDC (`0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`) as one of the pool tokens on Base. ```bash curl -X GET "https://api.cambrian.org/evm/sushi/v3/pools?chain_id=8453&token_address=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&limit=5" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x9ae052f3ded98d49b4335ded6ebfb011faa48ba2", "0x465bef0eafc41ca394cc34fb4b93f6ed7ab0651f", "LOAMD", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-07-28T14:10:49+00:00", 100, 1], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x7644ecc6291fe415c2f93a5ec8b48daa377ec773", "0x3190efd462af7c31d1fbd9e11dba48d5ba19a1d3", "AXONE", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-07-28T10:41:19+00:00", 100, 1], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0xeb0d1bae8d3d9f4f877d292fa8c30feecbb1cb0c", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xd15609adafa9edae304c0b8ae26935ed468468c5", "AXONE", 18, "2026-07-21T09:36:57+00:00", 100, 1], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x32c14c2a566438c7b17307fb8ccb15cfa3b49605", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "0xb200000000000000000000a775a213683f1fa301", "BASE", 18, "2026-07-09T17:50:55+00:00", 10000, 200], [8453, "0xc35dadb65012ec5796536bd9864ed8773abc74c4", "Sushi", "0x69f135ee4945f38b09cbbe5e240a39eec0f3d302", "0x729f75aff28c726e32403e80cef2afb518cfbfa7", "waBasEURC", 6, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-06-19T13:07:23+00:00", 3000, 60] ], "rows": 5 } ] ``` *Note: The `data` array shown above is limited to the first 10 rows returned by the API for this documentation example (5 rows returned in this case due to the `limit=5` parameter).* This example filters pools that contain USDC as a token. It returns 5 pools where USDC pairs with tokens such as LOAMD, AXONE, BASE, and waBasEURC. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/sushi/v3/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/sushi/v3/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/sushi/v3/pool` - Returns current pool TVL, swap volume, fees APR, price volatility, tick pressure, swap count, and unique users for a recent time range. - `/evm/uniswap/v3/pools` - Returns a list of all Uniswap V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/pancake/v3/pools` - Returns a list of all PancakeSwap V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/aero/v3/pools` - Returns a list of all Aerodrome V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/price-current` - Returns current price of a token calculated based on Uniswap V3 and clones liquidity pools. --- ## Cambrian API: All Tokens **Endpoint:** /api/v1/evm/tokens # All Tokens ## Overview Returns a list of all ERC20 tokens for a specified EVM chain, including their contract addresses, symbols, names, decimal places, and stablecoin classification. You can filter by symbol/name and paginate results using limit and offset. ## Business Value - **Token Discovery**: Access a comprehensive catalog of verified tokens across EVM chains for integration purposes - **Contract Verification**: Get validated contract addresses to avoid interaction with malicious or fake tokens - **Metadata Standardization**: Retrieve standardized token information including symbols, names, and decimal precision - **Chain Compatibility**: Support for multiple EVM-compatible networks through a single endpoint - **Application Development**: Essential data for wallets, DEXs, and portfolio tracking applications ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/tokens ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | filter | string | No | - | Search symbol or name of the token | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the token belongs to | | tokenAddress | String | ERC20 token contract address | | tokenSymbol | String | Token symbol | | tokenName | String | Token name | | tokenDecimals | UInt8 | Number of decimal places for the token | | isStable | UInt8 | Indicates whether the token is a stablecoin (1) or not (0) | ## Examples ### 1. List All Tokens on Base Retrieve all ERC20 tokens registered on the Base chain (default `chain_id=8453`) using default pagination. ```bash curl -X GET "https://api.cambrian.org/evm/tokens" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "tokenAddress", "type": "String" }, { "name": "tokenSymbol", "type": "String" }, { "name": "tokenName", "type": "String" }, { "name": "tokenDecimals", "type": "UInt8" }, { "name": "isStable", "type": "UInt8" } ], "data": [ [ 8453, "0xa18bfe67e90afb6146934eda5bab47e039a240a4", "AAA", "AA", 18, 0 ], [ 8453, "0x307a0926d788d9d43ca6a70d28bd617abaa3bd9d", "AAA", "AAA", 18, 0 ], [ 8453, "0x54c7c54599f652bd697a9bdbd7b5b18266bad268", "AAA", "AAA", 18, 0 ], [ 8453, "0xf8bade2c5820d6710c16a95c6cc4dc4e77bf23ad", "AAA", "AAA", 18, 0 ], [ 8453, "0x1cc57891b33f0b4731a553aca20a5beb8fc4efc7", "AAA", "AAA token", 18, 0 ], [ 8453, "0x7075017fcb2a7d7361b7917f44553db7645a55cd", "AAA", "AAA", 18, 0 ], [ 8453, "0x5ecbbca9beedc7a18996b6955fb1348b1ac612a9", "AAA", "AAA", 18, 0 ], [ 8453, "0x26257946eb6fe23972a9a99d7976539ddb202fad", "AAA", "AAA CAT", 18, 0 ], [ 8453, "0x90d15b7349d9e077cbe3be8982aba2a33600e500", "AAA", "aaa", 18, 0 ], [ 8453, "0x8352e40f4a9e38a3049f1ee094a5c516adb2a623", "AAA", "aaa", 18, 0 ] ], "rows": 100 } ] ``` Note: result collections are limited to 10 items in this documentation example. The `rows` field reflects the total number of matching tokens available (100 for this query), while `data` shows the returned page. This example returns tokens on the Base chain whose symbol/name begins with "AAA", each including its contract address, symbol, name, decimals, and stablecoin flag. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/tokens" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/tokens") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /evm/price-current - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - /evm/price-hour - Returns historical hourly price data for a specified EVM token. - /evm/chains - Returns information about supported EVM blockchain networks - /evm/dexes - List of DEXes on EVM compatible chains - /evm/tvl/top-owners - Returns top token holders for a given token address. --- ## Cambrian API: Total Value Locked **Endpoint:** /api/v1/evm/tvl/status # Total Value Locked (Token Holdings by Address) ## Overview Returns all tokens held by a given EVM wallet address on a specified chain, including token amount and USD value for each holding. This endpoint is useful for portfolio tracking, wallet analysis, and computing an address's total value locked (TVL) across ERC-20 tokens. ## Business Value - **Portfolio Analytics**: Track complete token holdings across EVM wallets for investment monitoring - **Risk Assessment**: Analyze wallet token diversification and concentration risks for due diligence - **Balance Verification**: Confirm token holdings for audit, compliance, and verification purposes - **Value Tracking**: Monitor USD values of all token positions in real-time - **Token Discovery**: Identify all tokens held by a wallet including lesser-known or new tokens ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/tvl/status ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | wallet_address | string | Yes | - | Address that holds tokens, prefixed with 0x. | | hasprice | boolean | No | false | If true, only tokens with a USD price will be returned. | | limit | integer | No | 1000 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the token holding was retrieved from. | | ownerAddress | FixedString(42) | Wallet address that owns the tokens. | | tokenAddress | FixedString(42) | Contract address of the held token. | | tokenSymbol | String | Symbol/ticker of the held token. | | tokenAmount | Float64 | Raw amount of the token held by the wallet. | | valueUsd | Float64 | Current USD value of the token holding. | ## Examples ### 1. Retrieve All Token Holdings for a Wallet This example retrieves every token held by a wallet on Base (chain ID 8453), including tokens with no known USD price. ```bash curl -X GET "https://api.cambrian.org/evm/tvl/status?wallet_address=0xfBB6Eed8e7aa03B138556eeDaF5D271A5E1e43ef&chain_id=8453" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "ownerAddress", "type": "FixedString(42)" }, { "name": "tokenAddress", "type": "FixedString(42)" }, { "name": "tokenSymbol", "type": "String" }, { "name": "tokenAmount", "type": "Float64" }, { "name": "valueUsd", "type": "Float64" } ], "data": [ [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 72.85335663, 4677512.761858977], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 3417014.646363, 3417014.646363], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x745e91e6db835646f790799e46afb73c459f5af7", "DIGITAL", 301, 565.0151144228093], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x3b9efc6f8165812c033618f45a5145cb07548712", "USGR", 75, 0.03814443055110924], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x94f68febe9b81e6f44aff39bad8ffaa712879471", "TRUMP", 151.7421, 0.028506361532441616], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xc6b4444073f4ee01f707253e6d915b3ff337711b", "ZORA", 100, 0.028099397009084374], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xccdc31173d897319bcdd0376b4f64e1819652b57", "CABASE", 1000, 0.01876144236069653], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x75618e57ed8c1da6894d0bda2974f1bd96d8c63b", "SROS", 45, 0.01685367157566115], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x23a23b6e57d4e35f1584e584d37586b490878763", "USXR", 25, 0.012715165232135998], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x68f61fdfbfb72e38341a0ec2ca15043d98294274", "BASEMATE", 25, 0.009419502203740935] ], "rows": 521 } ] ``` *Note: This wallet holds 521 total tokens; the `data` array above has been truncated to the first 10 rows for brevity. The `rows` field reflects the true total count.* This wallet's largest holding is `cbBTC` (~$4.68M USD), followed by `USDC` (~$3.42M USD), with the remaining 519 tokens holding comparatively negligible USD value — many with a `valueUsd` of `0` because no price feed is available for them. ### 2. Filter to Only Priced Tokens with a Result Limit This example uses `hasprice=true` combined with `limit=10` to return only tokens that have a known USD price, capped at 10 results — useful for quickly computing a wallet's meaningful TVL without noise from unpriced/illiquid tokens. ```bash curl -X GET "https://api.cambrian.org/evm/tvl/status?wallet_address=0xfBB6Eed8e7aa03B138556eeDaF5D271A5E1e43ef&chain_id=8453&hasprice=true&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "ownerAddress", "type": "FixedString(42)" }, { "name": "tokenAddress", "type": "FixedString(42)" }, { "name": "tokenSymbol", "type": "String" }, { "name": "tokenAmount", "type": "Float64" }, { "name": "valueUsd", "type": "Float64" } ], "data": [ [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 72.85335663, 4677512.761858977], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 3417014.646363, 3417014.646363], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x745e91e6db835646f790799e46afb73c459f5af7", "DIGITAL", 301, 565.0151144228093], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x3b9efc6f8165812c033618f45a5145cb07548712", "USGR", 75, 0.03814443055110924], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x94f68febe9b81e6f44aff39bad8ffaa712879471", "TRUMP", 151.7421, 0.028506361532441616], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xc6b4444073f4ee01f707253e6d915b3ff337711b", "ZORA", 100, 0.028099397009084374], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xccdc31173d897319bcdd0376b4f64e1819652b57", "CABASE", 1000, 0.01876144236069653], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x75618e57ed8c1da6894d0bda2974f1bd96d8c63b", "SROS", 45, 0.01685367157566115], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x23a23b6e57d4e35f1584e584d37586b490878763", "USXR", 25, 0.012715165232135998], [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x68f61fdfbfb72e38341a0ec2ca15043d98294274", "BASEMATE", 25, 0.009419502203740935] ], "rows": 10 } ] ``` With `limit=10` applied, the API returns exactly 10 rows (`rows: 10`), ordered by descending USD value — showing `cbBTC` and `USDC` as by far the dominant holdings in this wallet. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/tvl/status" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/tvl/status") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/tvl/top-owners` - Returns top token holders for a given token address. - `/evm/aero/v3/pool` - Returns current pool TVL (Total Value Locked), Swap Volume, Price volatility and other pool metrics. - `/evm/uniswap/v3/pool` - Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR and other pool metrics. - `/evm/aero/v2/provider-summary` - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics. - `/evm/dexes` - List of DEXes on EVM compatible chains. --- ## Cambrian API: Top token holders **Endpoint:** /api/v1/evm/tvl/top-owners # Top Token Holders ## Overview Returns the top token holders (owners) for a given ERC-20 token address on a supported EVM chain, ranked by their current token balance. This is useful for identifying whale wallets, assessing token distribution, and monitoring concentration risk for a specific token. ## Business Value - **Portfolio Analysis**: Identify whale wallets and major token holders for investment research and risk assessment - **Token Distribution**: Analyze token concentration and decentralization metrics for due diligence - **Market Intelligence**: Track large holder movements to anticipate potential market impacts - **Risk Management**: Monitor concentration risk by identifying addresses holding significant portions of token supply - **Competitive Analysis**: Research major stakeholders and institutional holders across different tokens ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/tvl/top-owners ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | Yes | - | Token address (pattern: `^0x[a-fA-F0-9]{40}$`). | | limit | integer | No | 20 | Limit the number of results (min 1, max 1000). | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows (min 0, max 100000). | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the token resides on. | | ownerAddress | FixedString(42) | Wallet address holding the token. | | tokenAddress | FixedString(42) | Contract address of the token. | | tokenSymbol | String | Symbol of the token. | | tokenAmount | Float64 | Raw token amount held by the owner. | | valueUsd | Float64 | USD value of the held token amount. | ## Examples ### 1. Get Top Token Holders Retrieves the top 20 holders (default limit) of the ODOS token on Base (chain ID 8453). ```bash curl -X GET "https://api.cambrian.org/evm/tvl/top-owners?chain_id=8453&token_address=0xca73ed1815e5915489570014e024b7ebe65de679&limit=20" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "ownerAddress", "type": "FixedString(42)" }, { "name": "tokenAddress", "type": "FixedString(42)" }, { "name": "tokenSymbol", "type": "String" }, { "name": "tokenAmount", "type": "Float64" }, { "name": "valueUsd", "type": "Float64" } ], "data": [ [ 8453, "0xae82febe00a21257ee813cfe2f913dcaa973d33b", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 3587949734.7407737, 3106119.09692773 ], [ 8453, "0x9d1e93bbc148fe7b19eb9ec22a5be4b75b57239f", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 2666692701.38885, 2308578.920495983 ], [ 8453, "0x32235fe0b39849ddff11bce74d93bf981c9fe5ea", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 723197383.5800779, 626078.2257443037 ], [ 8453, "0xe12be6d836bba65f1f91b61fb49fb109fba57e72", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 638144699.6775, 552447.3821578503 ], [ 8453, "0x7ec74ce1ff4c7c2b0bc2bc2f64ac8481db616b34", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 458315000, 396767.25683317997 ], [ 8453, "0xc80afd311c9626528de66d86814770361fe92416", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 378073521.4869109, 327301.5153368796 ], [ 8453, "0xc3681709ee476308b45812eabe0eb22f3b816880", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 366912550.6162723, 317639.3663870562 ], [ 8453, "0x2ef73b65a9033c2e9707b0372f382a14d0d71252", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 253350055.77781546, 219327.33305586112 ], [ 8453, "0x4c8f8055d88705f52c9994969dde61ab574895a3", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 229230686.5125222, 198446.9866130501 ], [ 8453, "0x56939b55d3a69ca79a556110a1a2e98cdc4c9fd6", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 92599680, 80164.34333859962 ] ], "rows": 20 } ] ``` Note: This example response is truncated to the first 10 rows for documentation purposes; the actual `rows` field reflects the true row count (20) returned by the API for this request. The largest ODOS holder on Base holds over 3.58 billion tokens, worth approximately $3.1M USD at the time of the request. ### 2. Paginate Through Holders with Offset Retrieves a smaller page of holders (limit=5) starting after the first 10 results (offset=10), useful for paginating through large holder lists. ```bash curl -X GET "https://api.cambrian.org/evm/tvl/top-owners?chain_id=8453&token_address=0xca73ed1815e5915489570014e024b7ebe65de679&limit=5&offset=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "ownerAddress", "type": "FixedString(42)" }, { "name": "tokenAddress", "type": "FixedString(42)" }, { "name": "tokenSymbol", "type": "String" }, { "name": "tokenAmount", "type": "Float64" }, { "name": "valueUsd", "type": "Float64" } ], "data": [ [ 8453, "0x85af237da23d6cf6f2a2cd9d936f0ae09bd1adcf", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 79200000, 68564.12454575533 ], [ 8453, "0xb4dc0ae16db607778e7fb4951ec0889852403f2c", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 60851602.706388004, 52679.758418808204 ], [ 8453, "0xbd146d2ee341b74d2825f8ab07e068e9449deb81", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 56374304, 48803.722230255975 ], [ 8453, "0xb7068556049df8fb3ae77ccbb9611fe0e85b2641", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 20157129.02579334, 17450.200820825183 ], [ 8453, "0x4c3159f83eb4e6ff6b93efae4229c0b8a4095e65", "0xca73ed1815e5915489570014e024b7ebe65de679", "ODOS", 18750000, 16232.037061021623 ] ], "rows": 5 } ] ``` This demonstrates ranks 11-15 of ODOS token holders on Base, showing how `offset` and `limit` can be combined to page through the full holder list. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/tvl/top-owners" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/tvl/top-owners") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/tvl/status` - Returns the tokens held by an address - `/evm/tokens` - Returns a list of all erc20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - `/evm/price-current` - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - `/evm/price-hour` - Returns historical hourly price data for a specified EVM token. --- ## Cambrian API: V3 - Pool Info **Endpoint:** /api/v1/evm/uniswap/v3/pool # Uniswap V3 Pool Info ## Overview Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR (Annual Percentage Rate), Price volatility and mean adjusted volatility (percentage), Tick Pressure Per 1M$ Volume, Number of Swaps and Unique users for recent time range (5 minutes, 1 hour, 1 day, 1 week, 1 month and 1 year). This endpoint provides a single-snapshot view of a specific Uniswap V3 pool's real-time health and trading activity. ## Business Value - **Real-time Pool Analytics**: Access live pool data including current price, liquidity, and tick information for trading decisions - **Historical Performance Metrics**: Track swap volume, fee APR, and utilization across multiple timeframes (5min to 1 year) - **Risk Assessment**: Monitor pool TVL and tick utilization to evaluate investment opportunities and market conditions - **Trading Optimization**: Use current tick and price data to optimize position management and entry/exit strategies - **Portfolio Management**: Track pool performance metrics to make informed liquidity provision decisions ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/uniswap/v3/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | pool_address | string | Yes | - | Pool address with 0x prefix | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | String | Contract address of the pool's first token | | token0Symbol | String | Symbol of the pool's first token | | token0Decimals | UInt8 | Decimal precision of the first token | | token1Address | String | Contract address of the pool's second token | | token1Symbol | String | Symbol of the pool's second token | | token1Decimals | UInt8 | Decimal precision of the second token | | feeTier | UInt32 | Pool fee tier in hundredths of a basis point (e.g., 500 = 0.05%) | | tickSpacing | Int32 | Minimum tick spacing configured for the pool | | currentLiquidity | Nullable(Int256) | Current in-range liquidity of the pool | | currentSqrtPriceX96 | Nullable(UInt256) | Current pool price expressed as sqrt(price) * 2^96 | | currentTick | Nullable(Int32) | Current active tick of the pool | | currentPoolPrice | Nullable(Float64) | Current pool price of token1 in terms of token0 | | poolTvlUsd | Nullable(Float64) | Current Total Value Locked in the pool, denominated in USD | | swapVolumeUsd | Map(String,Nullable(Float64)) | Swap volume in USD, keyed by time range (5 minute, 1 hour, 1 day, 1 week, 1 month, 1 year) | | feeApr | Map(String,Nullable(Float64)) | Annualized fee yield, keyed by time range | | priceVolatilityPct | Map(String,Float64) | Price volatility percentage, keyed by time range | | priceVolatilityAdjustedPct | Map(String,Float64) | Mean-adjusted price volatility percentage, keyed by time range | | tickPressurePer1MUsd | Map(String,Nullable(Float64)) | Tick movement pressure per $1M of volume, keyed by time range | | swapCount | Map(String,UInt64) | Number of swaps, keyed by time range | | uniqueUserCount | Map(String,UInt64) | Number of unique users who swapped, keyed by time range | ## Examples ### 1. Get Current Pool Stats Fetch the latest TVL, price, and fee APR snapshot for a specific Uniswap V3 pool on Base. ```bash curl -X GET "https://api.cambrian.org/evm/uniswap/v3/pool?chain_id=8453&pool_address=0xd0b53D9277642d899DF5C87A3966A349A798F224" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "currentLiquidity", "type": "Nullable(Int256)" }, { "name": "currentSqrtPriceX96", "type": "Nullable(UInt256)" }, { "name": "currentTick", "type": "Nullable(Int32)" }, { "name": "currentPoolPrice", "type": "Nullable(Float64)" }, { "name": "poolTvlUsd", "type": "Nullable(Float64)" }, { "name": "swapVolumeUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "feeApr", "type": "Map(String,Nullable(Float64))" }, { "name": "priceVolatilityPct", "type": "Map(String,Float64)" }, { "name": "priceVolatilityAdjustedPct", "type": "Map(String,Float64)" }, { "name": "tickPressurePer1MUsd", "type": "Map(String,Nullable(Float64))" }, { "name": "swapCount", "type": "Map(String,UInt64)" }, { "name": "uniqueUserCount", "type": "Map(String,UInt64)" } ], "data": [ [ "2023-09-06T19:56:01+00:00", "0x4200000000000000000000000000000000000006", "WETH", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, 500, 10, "991726704338392184", "3428744645824812288411310", -200968, 1872.8850259025005, 10002170.758111214, { "1 day": 8637888.126135757, "1 hour": 164187.9928407463, "1 month": 394763457.2762599, "1 week": 69866358.45587051, "1 year": 13219076749.482317, "5 minute": 11786.534257243828 }, { "1 day": 0.15760724558130437, "1 hour": 0.071898733388378, "1 month": 0.23680666936592437, "1 week": 0.18161310817249648, "1 year": 0.6608103915223786, "5 minute": 0.06193657912292236 }, { "1 day": 0.008116542821101125, "1 hour": 0.0008060294385758055, "1 month": 0.06720830697285504, "1 week": 0.02587604698072535, "1 year": 0.5287534195200911, "5 minute": 0.0001674742828701315 }, { "1 day": 0.00007114041957131817, "1 hour": 0.000040313092635245285, "1 month": 0.00009286426995078103, "1 week": 0.00008599352304466857, "1 year": 0.00012806056995650882, "5 minute": 0.000026263223771013654 }, { "1 day": 46.28446145190519, "1 hour": 45.67934518375289, "1 month": 42.67517595533307, "1 week": 44.334642143349505, "1 year": 30.7130450707081, "5 minute": 33.93703282660601 }, { "1 day": 13016, "1 hour": 390, "1 month": 523779, "1 week": 90544, "1 year": 17048080, "5 minute": 33 }, { "1 day": 127, "1 hour": 26, "5 minute": 10 } ] ], "rows": 1 } ] ``` Note: Result collections in this response are capped to the first 10 items; this pool query returns a single row so no truncation occurred here. This example queries the WETH/USDC 0.05% fee tier pool on Base. The response shows a pool TVL of ~$10M, a current price of ~1872.9 USDC per WETH, and fee APRs ranging from ~7.2% (1 hour) up to ~66% (1 year); recent trading activity has been elevated. ### 2. Assess Recent Trading Activity and Risk Use the same pool snapshot to evaluate short-term trading intensity and price risk before sizing a trade. ```bash curl -X GET "https://api.cambrian.org/evm/uniswap/v3/pool?chain_id=8453&pool_address=0xd0b53D9277642d899DF5C87A3966A349A798F224" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** (see full response above) From the same result set, the `swapCount` and `uniqueUserCount` maps show 33 swaps by 10 unique users in the last 5 minutes, and 13,016 swaps by 127 unique users over the last day. The `priceVolatilityPct` for "1 hour" is ~7.2%, while `tickPressurePer1MUsd` for "1 hour" is ~0.0000403, which is a relatively low price impact per $1M traded in that window. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2). Pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/uniswap/v3/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/uniswap/v3/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/uniswap/v3/pools` - Returns a list of all liquidity pools, including token pairs, fee tiers, and creation timestamps. - `/evm/price-current` - Returns current price of a token calculated based on uniswap v3 and clones liquidity pools. - `/evm/price-hour` - Returns historical hourly price data for a specified EVM token. - `/evm/tokens` - Returns a list of all erc20 tokens for the specified EVM chain, including their contract addresses, symbols, names, and decimal places. - `/evm/dexes` - List of DEXes on EVM compatible chains --- ## Cambrian API: V3 - List Pools **Endpoint:** /api/v1/evm/uniswap/v3/pools # Uniswap V3 Pools ## Overview Returns a list of all Uniswap V3 liquidity pools on a supported EVM chain, including token pair addresses/symbols, fee tiers, tick spacing, and pool creation timestamps. Results can be filtered by token address and paginated with `limit`/`offset`. ## Business Value - **Pool Discovery**: Find available liquidity pools for specific token pairs on Uniswap V3 - **Market Analysis**: Analyze liquidity distribution and fee structures across different pools - **DeFi Integration**: Access pool addresses and metadata for smart contract interactions - **Token Research**: Discover new token pairs and their associated liquidity pools - **Historical Tracking**: Monitor pool creation patterns and market evolution over time ## Endpoint Details **URL**: ``` https://api.cambrian.org/evm/uniswap/v3/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | chain_id | integer | No | 8453 | EVM chain ID. | | token_address | string | No | - | Pool token address. See tokens for valid addresses. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | | order_asc | array | No | - | List of column names to order by in ascending order divided by comma. Leave empty items to combine with descending order. | | order_desc | array | No | - | List of column names to order by in descending order divided by comma. Leave empty items to combine with ascending order. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | EVM chain ID the pool is deployed on. | | dexAddress | FixedString(42) | Contract address of the DEX factory/router associated with the pool. | | dexName | String | Name of the DEX (e.g., UniswapV3). | | poolAddress | FixedString(42) | Contract address of the liquidity pool. | | token0Address | String | Contract address of the pool's token0. | | token0Symbol | String | Symbol of token0. | | token0Decimals | UInt8 | Decimal precision of token0. | | token1Address | String | Contract address of the pool's token1. | | token1Symbol | String | Symbol of token1. | | token1Decimals | UInt8 | Decimal precision of token1. | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | fee | UInt32 | Pool fee tier (in hundredths of a basis point, e.g., 3000 = 0.3%). | | tickSpacing | Int32 | Minimum tick spacing enforced by the pool's fee tier. | ## Examples ### 1. List Recent Pools Retrieve the most recently created Uniswap V3 pools on Base (chain ID 8453) using default parameters. ```bash curl -X GET "https://api.cambrian.org/evm/uniswap/v3/pools" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xf08c67fbde69c85bc692cb69f84be248024ac0a1", "0x3e963bb1911b36d119a6a97f845f298a123e2db0", "CRW", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T21:53:11+00:00", 3000, 60], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xa0cd362130319f4c088fb5d6c7d509355e8f0729", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xdfc48bcdd2f3f66679762a768742b713f726026d", "DEX", 18, "2026-08-04T19:07:07+00:00", 100, 1], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0x110eb5a59450d9930192c85940c4cd7daabb6842", "0x205bf9f807f2a2a490314dacf19acd40a7b9efe1", "Pools.Trade", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T19:02:17+00:00", 10000, 200], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xeff83dc39600f257a35a6c287769de1db043e91f", "0x3de062d50dcee4521dd9287ebc85194748bb309b", "TIBIR", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T18:22:51+00:00", 3000, 60], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0x70985f6a4a763f8fe5f83a46e237ea2ff119912a", "0x29c96b861c717828b6c5c54c063608ebe4fcd2e3", "ErickTrumpp", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T18:04:45+00:00", 10000, 200], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xdc6e08d4c0637ee1d143e0a98927117be57f6ca0", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xb243d7173b73d8e6c670616e1111c49f2796d89d", "test", 18, "2026-08-04T17:58:39+00:00", 10000, 200], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0x079de00ce92e175e29813b9b986f4dc2fa072d68", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xd728f035a851b34947d7a2d40ea1372ed93be5cd", "AnsemAi", 18, "2026-08-04T16:43:47+00:00", 10000, 200], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0x49994a7c5ef5ee8d40562a0fc04df8aa331fef63", "0x4200000000000000000000000000000000000006", "WETH", 18, "0xe66700df197f16285e627f01b2947aa8b12d6b86", "Base O²", 18, "2026-08-04T16:37:51+00:00", 10000, 200], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0x42fc9f6a07d1f7af729678353e804862a342c2d0", "0x072d20c83a22fa24c56b245dec1f3f03aefa5adf", "Ansem", 18, "0x4200000000000000000000000000000000000006", "WETH", 18, "2026-08-04T16:37:49+00:00", 10000, 200], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xf07dc82e229299748af35118d3a3427faa18ecb1", "0x50985fd74efbab073eb20b5ff2a7d55c9d5e3cca", "HYPERNET", 18, "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 6, "2026-08-04T16:35:39+00:00", 3000, 60] ], "rows": 100 } ] ``` The API returned 100 pools (the requested `limit` default), ordered by most recent `createdAt` first. Note: the response shown above is truncated to the first 10 rows for documentation purposes; the actual `rows` field reflects the true count returned by the API. ### 2. Filter Pools by Token Address Retrieve all Uniswap V3 pools that include a specific token (`cbBTC`) as one of the pair assets, limited to 5 results. ```bash curl -X GET "https://api.cambrian.org/evm/uniswap/v3/pools?token_address=0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf&limit=5" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(42)" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(42)" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "Int32" } ], "data": [ [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xb5fd575f35a72bcce1d5aea16f5562129c36c92a", "0x30457a1ab7cd796d6e55e4e5ba12e09f2283e856", "DUB", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-08-03T06:14:19+00:00", 3000, 60], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0x89261e8b4acb7884c784bd412d7fd69b8e314562", "0x63706e401c06ac8513145b7687a14804d17f814b", "AAVE", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-07-31T18:28:29+00:00", 100, 1], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xba4dff8eaa91ec7fc4deef98e593f035895aa107", "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-07-10T17:36:17+00:00", 500, 10], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0xf7b681d2f89bfff22b79809e28108733f5d62cc8", "0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 18, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-07-10T17:20:19+00:00", 10000, 200], [8453, "0x33128a8fc17869897dce68ed026d694621f6fdfd", "UniswapV3", "0x7a635f8c66b93eb7f3e9ec45abdcc6a8fc6f6eca", "0x839baa00734f319c11f2869bc155c6b5fe35a283", "BTC-T", 8, "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 8, "2026-07-07T23:01:17+00:00", 100, 1] ], "rows": 5 } ] ``` All 5 returned pools pair a different token0 against `cbBTC` as token1, confirming the `token_address` filter matches pools where the token appears in either position. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), paying **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/evm/uniswap/v3/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/evm/uniswap/v3/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/evm/uniswap/v3/pool` - Returns current pool TVL, swap volume, fees APR, price volatility, and other metrics for a specific pool. - `/evm/tokens` - Returns a list of all ERC-20 tokens for the specified EVM chain, including contract addresses, symbols, names, and decimal places. - `/evm/dexes` - List of DEXes on EVM compatible chains. - `/evm/price-current` - Returns current price of a token calculated based on Uniswap V3 and clones liquidity pools. - `/evm/aero/v3/pools` - Returns a list of all Aerodrome V3 liquidity pools, including token pairs, fee tiers, and creation timestamps. --- ## Cambrian API: Calculate Risk **Endpoint:** /api/v1/perp-risk-engine # GET /risk/perp-risk-engine ## Overview The Perp Risk Engine endpoint calculates the liquidation risk probability for a leveraged cryptocurrency futures position. It uses Monte Carlo simulations driven by historical price data to model future price paths and estimate the likelihood that a given position would be liquidated within the specified risk horizon. Internal simulation parameters (lookback window, simulation count, time steps) are automatically derived from the requested risk horizon, so callers only need to supply position-level inputs. ## Business Value - **Risk Management**: Quantify exact liquidation probabilities before entering leveraged positions to prevent unexpected losses - **Position Sizing**: Optimize leverage levels based on statistical risk assessments and personal risk tolerance - **Market Intelligence**: Understand volatility dynamics and price drift patterns for different tokens across various timeframes - **Trading Strategy**: Make data-driven decisions on entry points, stop losses, and position duration based on probabilistic outcomes - **Capital Preservation**: Avoid overleveraging by visualizing risk distributions and understanding sigma-based safety margins ## Endpoint Details **URL**: ``` https://api.cambrian.org/risk/perp-risk-engine ``` **Method**: GET **Authentication**: Required via `X-API-Key` by external API management, or pay per request with x402. The backend does not inspect caller credentials, and x402 does not require an API key. ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | Solana token address | | entry_price | number | Yes | - | Entry price in USD | | leverage | number | Yes | - | Leverage multiplier (maximum 1000) | | direction | string | Yes | - | Position direction (`long` or `short`) | | risk_horizon | string | Yes | - | Risk time horizon (`1h`, `1d`, `1w`, or `1mo`) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | riskProbability | number | Estimated probability (0-1) that the position is liquidated within the risk horizon | | liquidationPrice | number | Price level at which the position would be liquidated | | entryPrice | number | Entry price used for the calculation, echoed back from the request | | volatility | number | Estimated volatility of the token's price used in the simulation | | drift | number | Estimated drift (directional trend) of the token's price used in the simulation | | priceChangeNeeded | number | Price change (in %) required to reach the liquidation price from the entry price | | sigmasAway | number | Number of standard deviations the liquidation price is away from the entry price | | simulationDetails | object | Metadata describing the Monte Carlo simulation run | | simulationDetails.totalSimulations | integer | Total number of simulated price paths | | simulationDetails.liquidatedPaths | integer | Number of simulated paths that resulted in liquidation | | simulationDetails.dataPointsUsed | integer | Number of historical price data points used to calibrate the simulation | | simulationDetails.dataInterval | string | Interval type of the historical data used | | simulationDetails.riskHorizon | string | Risk horizon used for the calculation, echoed back from the request | | visualizationData | object | Data supporting visualization of the simulation results | | visualizationData.histogram | object | Histogram of simulated final price outcomes | | visualizationData.histogram.bins | array | Bin edges (as price ratios) for the histogram | | visualizationData.histogram.counts | array | Count of simulated paths falling into each histogram bin | | visualizationData.histogram.finalPrices | array | Sample of simulated final price ratios (relative to entry price) | | visualizationData.liquidationThreshold | number | Price level marking the liquidation threshold, for plotting alongside the histogram | ## Examples ### 1. Long Position Liquidation Risk Check This example checks the 1-day liquidation risk for a 10x long position on a token entered at $2800. ```bash curl -X GET "https://api.cambrian.org/risk/perp-risk-engine?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&entry_price=2800&leverage=10&direction=long&risk_horizon=1d" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json { "riskProbability": 1, "liquidationPrice": 2519.8038627038927, "entryPrice": 2800, "volatility": 0.1001591277873362, "drift": -0.015741567419845347, "priceChangeNeeded": 0, "sigmasAway": 0, "simulationDetails": { "totalSimulations": 10000, "liquidatedPaths": 10000, "dataPointsUsed": 669, "dataInterval": "variable", "riskHorizon": "1d" }, "visualizationData": { "histogram": { "bins": [ 0.9820649027824402, 0.9828762412071228, 0.9836876392364502, 0.9844989776611328, 0.9853103160858154, 0.986121654510498, 0.9869330525398254, 0.9877443909645081, 0.9885557293891907, 0.9893671274185181 ], "counts": [ 3, 0, 2, 7, 16, 11, 20, 34, 55, 78 ], "finalPrices": [ 1.0012284517288208, 0.996128261089325, 0.995649516582489, 0.9971165657043457, 1.0045466423034668, 1.0007438659667969, 0.9913668036460876, 1.004259467124939, 1.0026304721832275, 1.0033494234085083 ] }, "liquidationThreshold": 2519.8038627038927 } } ``` Note that `histogram.bins`, `histogram.counts`, and `histogram.finalPrices` are limited to their first 10 items in this example response; the live endpoint may return more. For this position, the simulation returned a `riskProbability` of 1, indicating that under current volatility and drift conditions, all 10,000 simulated paths resulted in liquidation before the liquidation price of ~$2519.80 was avoided within the 1-day horizon. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) - pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment("https://x402.cambrian.org/risk/perp-risk-engine?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&entry_price=2800&leverage=10&direction=long&risk_horizon=1d"); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio import os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/risk/perp-risk-engine?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&entry_price=2800&leverage=10&direction=long&risk_horizon=1d") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint without an API key. 2. Server returns `402 Payment Required` with payment details. 3. The x402 SDK signs a payment authorization with your wallet. 4. The SDK resubmits the request with the signed payment. 5. Server verifies payment and returns the API response. The x402 SDK handles steps 2-5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Cambrian API: Holder Token Balances (USD) **Endpoint:** /api/v1/solana/holder-token-balances # Holder Token Balances (USD) ## Overview This endpoint returns the SPL token balances held by a specific Solana wallet, valued in USD and sorted by balance descending. It provides both raw on-chain balances and their USD equivalents, so you can see a wallet's largest holdings at a glance. ## Business Value - **Portfolio Management**: Track the complete token portfolio value across different assets for investment analysis - **Risk Assessment**: Monitor token concentration and diversification for risk management purposes - **Financial Reporting**: Generate accurate USD valuations for accounting and tax reporting requirements - **Trading Decisions**: Make informed trading decisions based on current holdings and their market values - **Wealth Tracking**: Monitor overall portfolio performance and changes in token values over time ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/holder-token-balances ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | wallet_address | string | Yes | - | Wallet address | | limit | integer | No | 10 | Limit the number of results. (min: 1, max: 1000) | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. (min: 0, max: 100000) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | FixedString(44) | The SPL token mint address held by the wallet | | balanceRaw | UInt64 | The raw token balance, in the token's smallest unit (not adjusted for decimals) | | balanceUSD | Float64 | The USD value of the held balance for this token | ## Examples ### 1. Retrieve Top Token Holdings for a Wallet This example fetches the top 10 token balances (by USD value) held by a specific Solana wallet. ```bash curl -X GET "https://api.cambrian.org/solana/holder-token-balances?wallet_address=7VHUFJHWu2CuExkJcJrzhQPJ2oygupTWkL2A2For4BmE&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "FixedString(44)" }, { "name": "balanceRaw", "type": "UInt64" }, { "name": "balanceUSD", "type": "Float64" } ], "data": [ [ "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 34685245, 34.685245 ], [ "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN", 33386592, 6.121212995604027 ], [ "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", 2000000, 2 ], [ "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN", 280000, 0.41285158642784164 ], [ "AQCq97gywgAvsUVMr1SMYCq1pu541evPEPUcXfG8tWsn", 50000000000000000, 0 ], [ "DfD3zArdh5GGUaZQJbCw9SHDGTrFSvqpqA4xFQk7qJhu", 300000000000000, 0 ], [ "DRvPqvmHhcSSNbgGvjjquntKuucceVRWxsxRDEuyBqT3", 198022663070078, 0 ], [ "Cmn4v2wipYV41dkakDvCgFJpxhtaaKt11NyWV8pjSE8A", 4000000, 0 ], [ "CeHgUXeNbdhLbKTyMVsRLw2eMvH5rFy4jZ4YS1q43QZB", 30000000000000, 0 ], [ "C7EwzBzTwoRrkorimxjgkWiSnkaaZuNavVAgn3hqt9Pd", 77000000000, 0 ] ], "rows": 10 } ] ``` Note: Result collections are limited to 10 items. The response shows this wallet's largest holding by USD value is USDC (`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`) at roughly $34.69, followed by Jupiter (JUP) worth about $6.12. Several tokens in the list have a `balanceUSD` of `0`, usually because the token has no current price data or is effectively worthless despite a large raw balance. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/holder-token-balances" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/holder-token-balances") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Latest Block Number and Time **Endpoint:** /api/v1/solana/latest-block # Latest Block Number and Time ## Overview This endpoint returns the latest block number and block time for the Solana blockchain, including the Unix timestamp and UTC timestamp of the most recently processed block. ## Business Value - **Real-time Monitoring**: Track the current state of the Solana blockchain with up-to-date block information - **Synchronization**: Ensure applications are synchronized with the latest blockchain state - **Latency Measurement**: Calculate blockchain processing delays by comparing block times with current time - **Health Checks**: Monitor blockchain network health and block production rates - **Data Pipeline**: Use as a reference point for blockchain data processing and ETL operations ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/latest-block ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | - | - | - | - | No parameters required | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | blockNumber | UInt64 | The latest block number on Solana | | blockUnixTime | UInt32 | Unix timestamp of the latest block | | blockUTCTime | String | UTC timestamp of the latest block in ISO 8601 format | ## Examples ### 1. Get Latest Block Information This example retrieves the current latest block information from Solana. ```bash curl -X GET "https://api.cambrian.org/solana/latest-block" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "blockNumber", "type": "UInt64" }, { "name": "blockUnixTime", "type": "UInt32" }, { "name": "blockUTCTime", "type": "String" } ], "data": [ [ 437259914, 1785882554, "2026-08-04T22:29:14Z" ] ], "rows": 1 } ] ``` The response returns block number `437259914`, processed at Unix timestamp `1785882554` (`2026-08-04T22:29:14Z`). ### 2. Monitor Blockchain Health This example uses the latest block endpoint for health monitoring, polling it and comparing the returned block time against the current wall-clock time. ```bash curl -X GET "https://api.cambrian.org/solana/latest-block" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "blockNumber", "type": "UInt64" }, { "name": "blockUnixTime", "type": "UInt32" }, { "name": "blockUTCTime", "type": "String" } ], "data": [ [ 437259914, 1785882554, "2026-08-04T22:29:14Z" ] ], "rows": 1 } ] ``` Comparing `blockUnixTime` to the current time lets you measure processing latency and confirm the network is producing blocks as expected. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/latest-block" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/latest-block") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/solana/price-current` - Retrieves the latest available USD price for a given Solana token program address - `/solana/price-multi` - Retrieves the latest available USD prices for multiple Solana token program addresses (comma-separated) - `/solana/price-unix` - Retrieve historical price data for a specified Solana token at the nearest hour to a specific Unix timestamp - `/solana/pool-transactions-time-bounded` - Get detailed transaction data for any SPL token across major Solana DEXs with precise Unix timestamp filtering - `/solana/ohlcv/token` - Retrieve Open, High, Low, Close, and Volume data for any SPL token --- ## Cambrian API: Pool Info **Endpoint:** /api/v1/solana/meteora-dlmm/pool # Meteora DLMM Pool Info ## Overview Returns basic pool information for a Meteora DLMM (Dynamic Liquidity Market Maker) pool on Solana. This includes token pair details, current price and active bin, liquidity (TVL), fees, volume, and APR metrics for the specified pool. ## Business Value - **Pool Analysis**: Get comprehensive metrics for any Meteora DLMM pool including liquidity, fees, and volume data - **Trading Intelligence**: Access real-time pricing, volatility metrics, and active bin information for informed trading decisions - **Liquidity Provider Insights**: Monitor pool utilization, APR, and fee generation to optimize liquidity provision strategies - **Market Research**: Track pool creation dates, token pairs, and trading activity for market analysis - **Risk Assessment**: Evaluate price volatility and utilization metrics for risk management ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/meteora-dlmm/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | Pool identifier | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | Numeric identifier of the blockchain the pool resides on | | dexName | String | Name of the DEX the pool belongs to | | poolAddress | FixedString(44) | On-chain address of the pool | | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | FixedString(44) | Mint address of the first token in the pair | | token0Symbol | String | Symbol of the first token in the pair | | token0Decimals | UInt8 | Decimal precision of the first token | | token1Address | FixedString(44) | Mint address of the second token in the pair | | token1Symbol | String | Symbol of the second token in the pair | | token1Decimals | UInt8 | Decimal precision of the second token | | activeBinId | Int32 | Identifier of the currently active liquidity bin | | currentPrice | Float64 | Current price of token0 denominated in token1 | | lastSwapTime | DateTime('UTC') | Timestamp of the most recent swap in the pool | | reserve0Address | FixedString(44) | Address of the reserve account holding token0 | | reserve1Address | FixedString(44) | Address of the reserve account holding token1 | | token0PriceUSD | Float64 | USD price of token0 | | token1PriceUSD | Float64 | USD price of token1 | | tvlToken0 | Float64 | Total value locked in the pool denominated in token0 | | tvlToken1 | Float64 | Total value locked in the pool denominated in token1 | | tvlUSD | Float64 | Total value locked in the pool denominated in USD | | feesToken0 | Float64 | Accumulated fees earned in token0 | | feesToken1 | Float64 | Accumulated fees earned in token1 | | fees24h | Float64 | Fees earned in USD over the last 24 hours | | volumeToken0 | Float64 | Trading volume in token0 | | volumeToken1 | Float64 | Trading volume in token1 | | volume24h | Float64 | Trading volume in USD over the last 24 hours | | apr24h | Float64 | Annualized percentage return based on the last 24 hours of fees | | swaps24h | UInt64 | Number of swaps executed in the pool over the last 24 hours | | binsUsed24h | UInt64 | Number of distinct liquidity bins used in swaps over the last 24 hours | | priceVolatility | Float64 | Measure of price volatility for the pool | | utilization24h | Float64 | Percentage of pool liquidity utilized over the last 24 hours | ## Examples ### 1. Retrieve Pool Info for a Meteora DLMM Pool Fetches current metrics for a specific Meteora DLMM pool by its pool address, including TVL, price, fees, and volume data. ```bash curl -X GET "https://api.cambrian.org/solana/meteora-dlmm/pool?pool_address=5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "FixedString(44)" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "FixedString(44)" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "activeBinId", "type": "Int32" }, { "name": "currentPrice", "type": "Float64" }, { "name": "lastSwapTime", "type": "DateTime('UTC')" }, { "name": "reserve0Address", "type": "FixedString(44)" }, { "name": "reserve1Address", "type": "FixedString(44)" }, { "name": "token0PriceUSD", "type": "Float64" }, { "name": "token1PriceUSD", "type": "Float64" }, { "name": "tvlToken0", "type": "Float64" }, { "name": "tvlToken1", "type": "Float64" }, { "name": "tvlUSD", "type": "Float64" }, { "name": "feesToken0", "type": "Float64" }, { "name": "feesToken1", "type": "Float64" }, { "name": "fees24h", "type": "Float64" }, { "name": "volumeToken0", "type": "Float64" }, { "name": "volumeToken1", "type": "Float64" }, { "name": "volume24h", "type": "Float64" }, { "name": "apr24h", "type": "Float64" }, { "name": "swaps24h", "type": "UInt64" }, { "name": "binsUsed24h", "type": "UInt64" }, { "name": "priceVolatility", "type": "Float64" }, { "name": "utilization24h", "type": "Float64" } ], "data": [ [ 900, "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2024-03-30T02:47:42+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, -6516, 73.83821529558917, "2026-08-05T14:28:20+00:00", "EYj9xKw6ZszwpyNibHY7JD5o3QgTVrSdcBp1fMJhrR9o", "CoaxzEh8p5YyGLcj36Eo3cUThVJxeKCs7qvLAGDYwBcz", 73.91874180865007, 1, 42733.28429748, 1671728.788151, 4830519.396772064, 58.649693757, 4450.452905, 8785.764474980078, 288296.775414579, 21309752.208249, 21310534.906136643, 66.38631935751333, 10317, 41, 7.569795866792804, 82 ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. This example returns the SOL/USDC Meteora DLMM pool, showing a current price of ~73.84 USDC per SOL, a TVL of ~$4.83M, and a 24h APR of ~66.4%. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/meteora-dlmm/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/meteora-dlmm/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/meteora-dlmm/pool-multi - Get overview metrics for multiple pools/pairs within the same DEX at once - /solana/meteora-dlmm/pools - This endpoint lists meteora pools - /solana/orca/pool - Retrieves detailed metrics and information for a specific Solana pool using the pre-calculated orca_pool_details_view - /solana/raydium-clmm/pool - This endpoint returns pool info for a specific raydium clmm pool - /solana/orca/pools - Retrieves a list of all Orca pools registered in the backend database --- ## Cambrian API: Meteora Pool Info (Multi) **Endpoint:** /api/v1/solana/meteora-dlmm/pool-multi # Meteora Pool Info (Multi) ## Overview Retrieve overview metrics for multiple Meteora DLMM pools in a single request. Returns pool details including price, volume, fees, TVL, and token information for each specified pool address. ## Business Value - **Multi-Pool Analytics**: Query multiple pools simultaneously to compare performance metrics across different trading pairs within the same DEX - **Portfolio Monitoring**: Track all relevant pools in your DeFi portfolio with a single API call, reducing latency and API usage - **Liquidity Analysis**: Analyze TVL, volume, and utilization across multiple pools to identify the most liquid and profitable opportunities - **Risk Assessment**: Monitor price volatility and swap activity across multiple pools to assess market risk and trading conditions - **Performance Comparison**: Compare APR, fees, and trading metrics across different pools to optimize yield farming strategies ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/meteora-dlmm/pool-multi ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_addresses | string | Yes | - | Comma-separated pool addresses within the same DEX. Example: addr1,addr2,addr3 | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | Numeric identifier of the blockchain (Solana) | | dexName | String | Name of the DEX (Meteora) | | poolAddress | FixedString(44) | Address of the pool | | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | FixedString(44) | Address of the first token in the pool | | token0Symbol | String | Symbol of the first token | | token0Decimals | UInt8 | Decimal precision of the first token | | token1Address | FixedString(44) | Address of the second token in the pool | | token1Symbol | String | Symbol of the second token | | token1Decimals | UInt8 | Decimal precision of the second token | | binStep | UInt16 | Bin step size configured for the DLMM pool | | feeTier | UInt32 | Fee tier of the pool | | activeBinId | Int32 | Identifier of the currently active liquidity bin | | currentPrice | Nullable(Float64) | Current price of token0 in terms of token1 | | lastSwapTime | DateTime('UTC') | Timestamp of the most recent swap in the pool | | reserve0Address | FixedString(44) | Address of the reserve account for token0 | | reserve1Address | FixedString(44) | Address of the reserve account for token1 | | token0PriceUSD | Float64 | USD price of token0 | | token1PriceUSD | Float64 | USD price of token1 | | tvlToken0 | Nullable(Float64) | Total value locked denominated in token0 | | tvlToken1 | Nullable(Float64) | Total value locked denominated in token1 | | tvlUSD | Nullable(Float64) | Total value locked in USD | | feesToken0 | Nullable(Float64) | Cumulative fees collected in token0 | | feesToken1 | Nullable(Float64) | Cumulative fees collected in token1 | | fees24h | Nullable(Float64) | Fees collected in USD over the last 24 hours | | volumeToken0 | Nullable(Float64) | Cumulative trading volume in token0 | | volumeToken1 | Nullable(Float64) | Cumulative trading volume in token1 | | volume24h | Nullable(Float64) | Trading volume in USD over the last 24 hours | | apr24h | Float64 | Annualized percentage rate based on 24h fees | | swaps24h | UInt64 | Number of swaps executed in the last 24 hours | | binsUsed24h | UInt64 | Number of distinct liquidity bins used in the last 24 hours | | priceVolatility | Nullable(Float64) | Measure of price volatility over the observed period | | utilization24h | Nullable(Float64) | Percentage of liquidity utilized in the last 24 hours | ## Examples ### 1. Retrieve metrics for a Meteora DLMM pool Fetch overview metrics for a single Meteora DLMM pool by its address. ```bash curl -X GET "https://api.cambrian.org/solana/meteora-dlmm/pool-multi?pool_addresses=5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "FixedString(44)" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "FixedString(44)" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "binStep", "type": "UInt16" }, { "name": "feeTier", "type": "UInt32" }, { "name": "activeBinId", "type": "Int32" }, { "name": "currentPrice", "type": "Nullable(Float64)" }, { "name": "lastSwapTime", "type": "DateTime('UTC')" }, { "name": "reserve0Address", "type": "FixedString(44)" }, { "name": "reserve1Address", "type": "FixedString(44)" }, { "name": "token0PriceUSD", "type": "Float64" }, { "name": "token1PriceUSD", "type": "Float64" }, { "name": "tvlToken0", "type": "Nullable(Float64)" }, { "name": "tvlToken1", "type": "Nullable(Float64)" }, { "name": "tvlUSD", "type": "Nullable(Float64)" }, { "name": "feesToken0", "type": "Nullable(Float64)" }, { "name": "feesToken1", "type": "Nullable(Float64)" }, { "name": "fees24h", "type": "Nullable(Float64)" }, { "name": "volumeToken0", "type": "Nullable(Float64)" }, { "name": "volumeToken1", "type": "Nullable(Float64)" }, { "name": "volume24h", "type": "Nullable(Float64)" }, { "name": "apr24h", "type": "Float64" }, { "name": "swaps24h", "type": "UInt64" }, { "name": "binsUsed24h", "type": "UInt64" }, { "name": "priceVolatility", "type": "Nullable(Float64)" }, { "name": "utilization24h", "type": "Nullable(Float64)" } ], "data": [ [ 900, "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2024-03-30T02:47:42+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, 4, 400, -6520, 73.7201921978139, "2026-08-05T14:35:21+00:00", "EYj9xKw6ZszwpyNibHY7JD5o3QgTVrSdcBp1fMJhrR9o", "CoaxzEh8p5YyGLcj36Eo3cUThVJxeKCs7qvLAGDYwBcz", 73.74421529071996, 1, 43967.981229085, 1580702.660992, 4823086.934647978, 59.363339155, 4454.169591, 8831.872454022345, 290105.186765195, 21443505.549247, 21393579.349767063, 66.83755630777239, 10364, 41, 7.531516098496878, 82 ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. This example shows a single SOL/USDC Meteora DLMM pool with a TVL of approximately $4.82M, 24h volume of ~$21.4M, and a 24h APR of ~66.8%. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/meteora-dlmm/pool-multi" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/meteora-dlmm/pool-multi") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/meteora-dlmm/pool - This endpoint returns basic pool information for a meteora pool. - /solana/meteora-dlmm/pools - This endpoint lists meteora pools - /solana/orca/pool-multi - Get overview metrics for multiple pools/pairs simultaneously within the same DEX. Returns pool details including price, volume, trades, and token information. - /solana/raydium-clmm/pool-multi - Get overview metrics for multiple pools/pairs simultaneously within the same DEX. Returns pool details including price, volume, trades, and token information. --- ## Cambrian API: List Pools **Endpoint:** /api/v1/solana/meteora-dlmm/pools # Meteora DLMM Pools ## Overview This endpoint retrieves information about Meteora Dynamic Liquidity Market Maker (DLMM) pools on Solana. It returns a paginated list of pools with token pair details, DEX metadata, fee structures, and creation timestamps. ## Business Value - **Pool Discovery**: Find and analyze available Meteora DLMM pools for trading opportunities - **Token Pair Analysis**: Access detailed information about token pairs and their pool configurations - **Fee Structure Insights**: Understand fee rates and tick spacing for optimal trading strategies - **Market Monitoring**: Track pool creation dates and monitor new liquidity additions - **DeFi Integration**: Essential data for building DeFi applications and trading bots on Solana ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/meteora-dlmm/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | limit | integer | No | 100 | Limit the number of results (1-1000) | | offset | integer | No | 0 | Offset the results (0-100000) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolAddress | FixedString(44) | Unique address of the Meteora DLMM pool | | chainId | UInt16 | Blockchain chain identifier (900 for Solana) | | dexAddress | FixedString(44) | Address of the Meteora DEX program | | dexName | String | Name of the decentralized exchange (Meteora) | | token0Address | FixedString(44) | Contract address of the first token in the pair | | token0Symbol | String | Symbol of the first token | | token0Decimals | UInt8 | Number of decimal places for the first token | | token1Address | FixedString(44) | Contract address of the second token in the pair | | token1Symbol | String | Symbol of the second token | | token1Decimals | UInt8 | Number of decimal places for the second token | | createdAt | DateTime('UTC') | Timestamp when the pool was created | | fee | UInt32 | Pool fee rate (in basis points, e.g., 25000 = 2.5%) | | tickSpacing | UInt16 | Tick spacing for the pool's price ranges (derived from bin step) | ## Examples ### 1. Get All Meteora DLMM Pools Retrieve the most recently created Meteora DLMM pools with default pagination (limit=100, offset=0). ```bash curl -X GET "https://api.cambrian.org/solana/meteora-dlmm/pools" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** The API returned 100 total rows; the first 10 are shown below for brevity. ```json [ { "columns": [ { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(44)" }, { "name": "dexName", "type": "String" }, { "name": "token0Address", "type": "FixedString(44)" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "FixedString(44)" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "UInt16" } ], "data": [ [ "8pZhpZrGtaLksLq1m1yZ333TChxmRAW7K4DxnfyetsUj", 900, "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo", "Meteora", "Gihwz9Dj89Lt9bByouPEdD3bT37y2hamwDdxMuPWAVz", "CLAI", 6, "So11111111111111111111111111111111111111112", "SOL", 9, "2026-04-29T18:10:26+00:00", 10000, 100 ] ], "rows": 100 } ] ``` *Note: The response above has been truncated to the first 10 rows of `data` for documentation purposes; `rows` reflects the total count returned by the query, not the truncated array length.* This response shows the most recently created Meteora DLMM pools on Solana. Each row contains the pool address, the DEX program address, the token pair (token0/token1) with symbols and decimals, the fee rate, tick spacing, and the pool's creation timestamp. ### 2. Paginate Through Results Retrieve a smaller page of results using `limit` and `offset` to skip earlier records. ```bash curl -X GET "https://api.cambrian.org/solana/meteora-dlmm/pools?limit=5&offset=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(44)" }, { "name": "dexName", "type": "String" }, { "name": "token0Address", "type": "FixedString(44)" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "FixedString(44)" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "UInt16" } ], "data": [ [ "GpMMWCAG4Z43nJxwCR814aR6jNAKTCGeJ2ErTE8NesPb", 900, "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo", "Meteora", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "GnmnE79bvPkBNgkS2dq6HN5ozXj2RqgMeHHzHN8AskFJ", "TESTDEV", 9, "2026-01-12T15:29:08+00:00", 25000, 250 ], [ "GGsV5EqGL1oTWAUAYF69kRe1zmP7VqiSgWUGbxiqGnfL", 900, "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo", "Meteora", "BXPnGr88CyavdAnjvyXhKW2QBMpAhGuGjrWkU9wA8PP2", "TESTDEV", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-01-12T15:28:13+00:00", 25000, 250 ], [ "7QCoARdjsN1jT47df5fTaGGZvimqNVDagtKLzD5mzKbD", 900, "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo", "Meteora", "APuczAKpEey4zkT7qdqmkpCqJVsK38UDgTsRv5vZsHMo", "N", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-01-11T17:33:57+00:00", 25000, 250 ], [ "2hqWq2VHiZxv5JtckNzF4WZyJMK4SgN7UxVV6YbGqGVW", 900, "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo", "Meteora", "Wd2TsHUoQxaLjmbWCeYU8fBMoje4R8UYj86JTbXBK5Z", "N", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-01-11T01:27:22+00:00", 25000, 250 ], [ "7yBfVUTRygLmpBMVGPiKmZHGepWvEA6hYXdruZDPrgyY", 900, "LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo", "Meteora", "AYFkbXHpfgBvLPms75ssGKGZp8QQDCFDHY5XfR6aXrgL", "N", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2025-12-31T00:10:45+00:00", 25000, 250 ] ], "rows": 5 } ] ``` This call skips the first 10 pools and returns the next 5, demonstrating how `limit` and `offset` can be combined to page through the full result set. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/meteora-dlmm/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/meteora-dlmm/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/solana/meteora-dlmm/pool` - Returns basic pool information for a single Meteora pool - `/solana/meteora-dlmm/pool-multi` - Get comprehensive overview metrics for multiple Meteora pools simultaneously, including price, volume, and trade data - `/solana/tokens` - Returns a paginated list of known tokens for the Solana chain - `/solana/tokens/holders` - Returns a list of accounts currently holding a specific Solana token, sorted by balance - `/solana/pool-transactions` - Retrieve a paginated list of trades/transactions for a specified Solana pool address --- ## Cambrian API: OHLCV (Base/Quote) **Endpoint:** /api/v1/solana/ohlcv/base-quote # OHLCV (Base/Quote) ## Overview Retrieve granular OHLCV data with separate base and quote token volumes for detailed trading analysis between any two SPL tokens. This is the most detailed view available of a trading relationship, with individual token flow tracked on each side for advanced analytics. Use it when you need to see how volume splits between the base and quote sides of a trading pair. ## Business Value - **Granular Trading Analysis** - Get separate volume metrics for both base and quote tokens to understand directional flow in trading pairs - **Advanced Analytics Support** - Enable sophisticated trading strategy development with detailed OHLCV breakdowns by token direction - **Cross-Pool Aggregation** - Analyze trading activity across multiple liquidity pools and providers for comprehensive market insights - **Time-Series Analysis** - Support backtesting and trend analysis with configurable time intervals from 1 minute to 1 week - **Trading Performance Metrics** - Access trade counts, pool participation, and provider diversity metrics alongside traditional OHLCV data ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/ohlcv/base-quote ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | base_address | string | Yes | - | Base token mint address (base58 format) | | quote_address | string | Yes | - | Quote token mint address (base58 format) | | after_time | integer | Yes | - | Unix timestamp - start time for data range | | before_time | integer | Yes | - | Unix timestamp - end time for data range | | interval | string | Yes | - | Time interval for OHLCV data aggregation. One of: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `6h`, `8h`, `12h`, `1d`, `3d`, `1w` | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | openPrice | Nullable(Float64) | Opening price for the interval | | highPrice | Nullable(Float64) | Highest price during the interval | | lowPrice | Nullable(Float64) | Lowest price during the interval | | closePrice | Nullable(Float64) | Closing price for the interval | | volume | Nullable(Float64) | Total trading volume for the interval | | volumeBase | Nullable(Float64) | Trading volume denominated in the base token for the interval | | unixTime | Nullable(Int64) | Unix timestamp marking the start of the interval | | interval | String | Time interval used for aggregation (e.g. `1h`) | | baseTokenAddress | String | Base token mint address (base58 format) | | quoteTokenAddress | String | Quote token mint address (base58 format) | | tradeCount | UInt64 | Number of trades recorded during the interval | | poolCount | UInt64 | Number of distinct pools contributing to the interval's data | | providerCount | UInt64 | Number of distinct liquidity providers/venues contributing to the interval's data | ## Examples ### 1. Retrieve hourly OHLCV data for a SOL/USDC pair This example fetches hourly OHLCV data for the SOL/USDC pair over a specified time range. Each interval includes separate base and quote volume metrics. ```bash curl -X GET "https://api.cambrian.org/solana/ohlcv/base-quote?base_address=So11111111111111111111111111111111111111112"e_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&after_time=1735689600&before_time=1735776000&interval=1h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "openPrice", "type": "Nullable(Float64)" }, { "name": "highPrice", "type": "Nullable(Float64)" }, { "name": "lowPrice", "type": "Nullable(Float64)" }, { "name": "closePrice", "type": "Nullable(Float64)" }, { "name": "volume", "type": "Nullable(Float64)" }, { "name": "volumeBase", "type": "Nullable(Float64)" }, { "name": "unixTime", "type": "Nullable(Int64)" }, { "name": "interval", "type": "String" }, { "name": "baseTokenAddress", "type": "String" }, { "name": "quoteTokenAddress", "type": "String" }, { "name": "tradeCount", "type": "UInt64" }, { "name": "poolCount", "type": "UInt64" }, { "name": "providerCount", "type": "UInt64" } ], "data": [ [ 189.6625243484793, 191.695717169467, 189.51810429757174, 190.14084507042253, 21410089.416325193, 112342.39220576087, 1735689600, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 32391, 37, 4 ], [ 191.1272048166425, 191.6285651350636, 190.3136686537508, 190.89813708021254, 17247066.059550855, 90314.1759343398, 1735693200, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 27985, 35, 3 ], [ 190.3021719786612, 191.26610199990643, 190.26828564932876, 191.14794361550693, 17686310.04413288, 92758.91703103311, 1735696800, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 23762, 32, 3 ], [ 190.77370333885284, 190.84877516598925, 189.97734164925717, 190.02427516753872, 12383865.196407959, 65042.30334346957, 1735700400, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 20926, 33, 3 ], [ 189.41637, 189.81096002077487, 189.07539859510078, 189.0830825089519, 15068663.568698956, 79550.80894114784, 1735704000, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 24144, 35, 3 ], [ 189.9223938441478, 190.0489466975094, 189.26210239321418, 189.74888458101702, 14201329.27261292, 74850.07611125475, 1735707600, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 23280, 27, 4 ], [ 189.7160209783157, 189.7794947553121, 189.193703, 189.74209811906147, 12991105.70199395, 68572.05439734722, 1735711200, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 21721, 24, 3 ], [ 189.78531011158185, 189.7948884840379, 189.37686735413732, 189.64019776006458, 11790684.978162955, 62188.13235922013, 1735714800, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 21449, 19, 3 ], [ 189.6654225921158, 190.175179400185, 189.0953685809023, 189.11411684309033, 16512894.902367944, 87089.9436624573, 1735718400, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 25899, 32, 3 ], [ 189.02400110133593, 189.10101838931757, 187.8698621608887, 188.92087759356696, 19406301.78602204, 103046.51770799233, 1735722000, "1h", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 29708, 35, 3 ] ], "rows": 24 } ] ``` Result collections are limited to 10 items. Each row represents one hourly interval and includes separate `volume` (quote-denominated) and `volumeBase` (base-denominated) figures, plus trade, pool, and provider counts for the SOL/USDC pair. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/ohlcv/base-quote" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/ohlcv/base-quote") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/ohlcv/pool - Retrieve OHLCV data for individual pool contracts for pair-specific price analysis and liquidity venue performance tracking. - /solana/ohlcv/token - Retrieve Open, High, Low, Close, and Volume data for any SPL token. - /solana/price-volume/multi - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token. - /solana/trade-statistics - Get instant trade analytics and performance metrics for any SPL tokens. - /solana/token-pool-search - Find pools containing a specific token and retrieve comprehensive trading statistics. --- ## Cambrian API: OHLCV (Pool) **Endpoint:** /api/v1/solana/ohlcv/pool # OHLCV (Pool) ## Overview Retrieve OHLCV (Open, High, Low, Close, Volume) data for a specific Solana pool contract to support pair-specific price analysis and liquidity venue performance tracking. This endpoint returns time-bucketed price and volume data for a single pool over a specified time range and interval. ## Business Value - **Pool-Specific Analytics**: Track price movements and trading activity for specific liquidity pools to understand venue performance - **Liquidity Provider Insights**: Monitor OHLCV metrics for pools where you provide liquidity to optimize returns and assess risk - **Venue Comparison**: Compare trading patterns across different pools for the same token pair to identify optimal trading venues - **Historical Price Analysis**: Access granular time-series price data with customizable intervals for technical analysis and backtesting - **Volume Tracking**: Monitor both base and quote token volumes to understand trading intensity and market depth dynamics ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/ohlcv/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | Pool/pair contract address (base58 format) | | after_time | integer | Yes | - | Unix timestamp - start time for data range | | before_time | integer | Yes | - | Unix timestamp - end time for data range | | interval | string | Yes | - | Time interval for OHLCV data aggregation. Enum: `1m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `6h`, `8h`, `12h`, `1d`, `3d`, `1w` | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | openPrice | Nullable(Float64) | Opening price for the interval | | highPrice | Float64 | Highest price during the interval | | lowPrice | Float64 | Lowest price during the interval | | closePrice | Nullable(Float64) | Closing price for the interval | | volumeQuote | Float64 | Trading volume denominated in the quote token | | volumeBase | Float64 | Trading volume denominated in the base token | | unixTime | Nullable(Int64) | Unix timestamp marking the start of the interval | | interval | String | Time interval for this data point (e.g. "1h") | | poolAddress | String | Pool/pair contract address (base58 format) | | baseTokenAddress | Nullable(String) | Contract address of the base token in the pair | | quoteTokenAddress | Nullable(String) | Contract address of the quote token in the pair | ## Examples ### 1. Retrieve hourly OHLCV data for a Solana pool This example fetches hourly OHLCV data for a specific pool over a one-day window, useful for short-term price and volume analysis of a single liquidity venue. ```bash curl -X GET "https://api.cambrian.org/solana/ohlcv/pool?pool_address=5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6&after_time=1735689600&before_time=1735776000&interval=1h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "openPrice", "type": "Nullable(Float64)" }, { "name": "highPrice", "type": "Float64" }, { "name": "lowPrice", "type": "Float64" }, { "name": "closePrice", "type": "Nullable(Float64)" }, { "name": "volumeQuote", "type": "Float64" }, { "name": "volumeBase", "type": "Float64" }, { "name": "unixTime", "type": "Nullable(Int64)" }, { "name": "interval", "type": "String" }, { "name": "poolAddress", "type": "String" }, { "name": "baseTokenAddress", "type": "Nullable(String)" }, { "name": "quoteTokenAddress", "type": "Nullable(String)" } ], "data": [ [ 188.91000369631612, 192.27155639417393, 188.75311778120638, 192.03411242234174, 406283.84986, 2129.8661412570023, 1735689600, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 192.03412720298522, 192.1959156621166, 189.9735973570173, 190.18832858249917, 451140.73497299966, 2362.969263186, 1735693200, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 190.18832802245518, 191.5766668691956, 190.04950427631093, 191.1935695373037, 879581.7627479993, 4612.637865910996, 1735696800, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 191.04063318392232, 191.0406341282193, 189.61195276700667, 190.12644541964147, 604837.0177970004, 3176.215211069999, 1735700400, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 189.9739863001899, 189.97400341153914, 188.98306775870205, 189.0641139332444, 644987.2130740001, 3404.7818689140017, 1735704000, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 188.98834548025786, 190.126997275962, 188.98834548025786, 189.7479113043496, 779107.6320560005, 4106.191289562003, 1735707600, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 189.59440160023175, 189.9043887377066, 188.98853949074328, 189.84927258573907, 888871.904823, 4691.795723701002, 1735711200, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 189.89839027144353, 189.97447643932955, 189.28804959162153, 189.5945163320466, 544177.454244, 2870.2106599879985, 1735714800, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 189.5945169093682, 190.27919913160966, 188.90660183483112, 188.98887404540355, 1024084.2185279999, 5403.363581164996, 1735718400, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ], [ 189.1401892478719, 189.36765803490573, 187.6222526066206, 188.90947709868874, 845770.9815419995, 4489.710143661002, 1735722000, "1h", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" ] ], "rows": 24 } ] ``` Note: result collections are limited to 10 items. The response shows hourly OHLCV data for the pool `5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6` (a SOL/USDC pair, identified by `baseTokenAddress` and `quoteTokenAddress`). The `rows` field shows 24 total intervals were available over the requested 24-hour window. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), which lets you pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/ohlcv/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/ohlcv/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/ohlcv/base-quote - Retrieve granular OHLCV data with separate base and quote token volumes for detailed trading analysis between any two SPL tokens. - /solana/ohlcv/token - Retrieve Open, High, Low, Close, and Volume data for any SPL token. - /solana/pool-transactions - Retrieve a paginated list of trades/transactions for a specified Solana pool address including swaps, add liquidity, and remove liquidity events. - /solana/token-pool-search - Find pools containing a specific token and retrieve comprehensive trading statistics including 24h volume, trade counts, and buy/sell ratios. - /solana/orca/pool - Retrieves detailed metrics and information for a specific Solana pool (identified by its program ID/address) using the pre-calculated orca_pool_details_view. --- ## Cambrian API: OHLCV (Token) **Endpoint:** /api/v1/solana/ohlcv/token # Token OHLCV Data ## Overview Retrieve Open, High, Low, Close, and Volume (OHLCV) data for any SPL token across specified time intervals. This endpoint provides comprehensive price and trading volume metrics essential for technical analysis and trading strategy development on Solana. ## Business Value - **Technical Analysis**: Access OHLCV candlestick data for comprehensive price pattern analysis and trend identification - **Trading Strategy Development**: Historical price and volume data enables backtesting and strategy optimization - **Market Research**: Volume metrics provide insights into token liquidity and market activity patterns - **Portfolio Management**: Track token performance over time with standardized financial market data formats - **Risk Assessment**: Historical volatility analysis through high/low price ranges supports risk management decisions ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/ohlcv/token ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | SPL token mint address (base58 format) | | after_time | integer | Yes | - | Unix timestamp - start time for data range | | before_time | integer | Yes | - | Unix timestamp - end time for data range | | interval | string | Yes | - | Time interval for OHLCV data aggregation (1m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | openPrice | Nullable(Float64) | Opening price at the start of the interval | | highPrice | Nullable(Float64) | Highest price reached during the interval | | lowPrice | Nullable(Float64) | Lowest price reached during the interval | | closePrice | Nullable(Float64) | Closing price at the end of the interval | | volume | Nullable(Float64) | Total USD volume traded during the interval | | volumeToken | Nullable(Float64) | Total token volume traded during the interval | | unixTime | Nullable(Int64) | Unix timestamp for the start of the interval | | interval | String | Time interval used for aggregation | | tokenAddress | String | SPL token mint address | ## Examples ### 1. Hourly OHLCV Data for SOL Token Get hourly OHLCV data for Wrapped SOL over a 24-hour period to analyze short-term price movements and trading volumes. ```bash curl -X GET "https://api.cambrian.org/solana/ohlcv/token?token_address=So11111111111111111111111111111111111111112&after_time=1735689600&before_time=1735776000&interval=1h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "openPrice", "type": "Nullable(Float64)" }, { "name": "highPrice", "type": "Nullable(Float64)" }, { "name": "lowPrice", "type": "Nullable(Float64)" }, { "name": "closePrice", "type": "Nullable(Float64)" }, { "name": "volume", "type": "Nullable(Float64)" }, { "name": "volumeToken", "type": "Nullable(Float64)" }, { "name": "unixTime", "type": "Nullable(Int64)" }, { "name": "interval", "type": "String" }, { "name": "tokenAddress", "type": "String" } ], "data": [ [ 190.02896429484457, 191.46123775723134, 189.93454611861705, 190.14084507042253, 18336881.84702409, 96152.88098244628, 1735689600, "1h", "So11111111111111111111111111111111111111112" ], [ 191.1272048166425, 191.47069941197873, 190.65040801684015, 190.89813708021254, 14820073.972368002, 77582.02503583477, 1735693200, "1h", "So11111111111111111111111111111111111111112" ], [ 190.7510665087174, 191.15446510806973, 190.41341361640804, 191.14176965009318, 15147530.53400096, 79424.70777417776, 1735696800, "1h", "So11111111111111111111111111111111111111112" ], [ 190.77370333885284, 190.83896467848294, 190.08646348496325, 190.44006524274295, 10935944.62225898, 57407.6305247706, 1735700400, "1h", "So11111111111111111111111111111111111111112" ], [ 189.41637, 189.800143706478, 189.2359063825013, 189.4499725170332, 13504379.410405014, 71266.28414577786, 1735704000, "1h", "So11111111111111111111111111111111111111112" ], [ 189.86046156817085, 190.09403051275774, 189.590976, 189.80453305785124, 12826478.285232937, 67567.45013128487, 1735707600, "1h", "So11111111111111111111111111111111111111112" ], [ 189.7160209783157, 189.82147361798832, 189.3138999329921, 189.79999999999998, 11567187.100701973, 61032.001700627974, 1735711200, "1h", "So11111111111111111111111111111111111111112" ], [ 189.8693038721531, 189.908447, 189.49643291819925, 189.84637033006047, 11115165.199889978, 58604.48739789844, 1735714800, "1h", "So11111111111111111111111111111111111111112" ], [ 189.62699129495397, 190.16950354851585, 189.318549197926, 189.43089278372233, 14157638.143593896, 74613.4871102127, 1735718400, "1h", "So11111111111111111111111111111111111111112" ], [ 188.61736502544898, 188.8860650288014, 188.03831735111763, 188.80736664274005, 16185241.416632997, 85906.51899640434, 1735722000, "1h", "So11111111111111111111111111111111111111112" ] ], "rows": 24 } ] ``` The full result contained 24 hourly rows; only the first 10 are shown above. The response shows hourly OHLCV data for Wrapped SOL with prices around $190 USD and significant trading volume exceeding $10M USD per hour. Each data row represents one hour of trading activity with opening, high, low, and closing prices plus volume metrics. ### 2. Daily OHLCV Data Analysis Retrieve daily OHLCV data for a full week to support longer-term trend analysis with reduced data granularity. ```bash curl -X GET "https://api.cambrian.org/solana/ohlcv/token?token_address=So11111111111111111111111111111111111111112&after_time=1735689600&before_time=1736294400&interval=1d" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "openPrice", "type": "Nullable(Float64)" }, { "name": "highPrice", "type": "Nullable(Float64)" }, { "name": "lowPrice", "type": "Nullable(Float64)" }, { "name": "closePrice", "type": "Nullable(Float64)" }, { "name": "volume", "type": "Nullable(Float64)" }, { "name": "volumeToken", "type": "Nullable(Float64)" }, { "name": "unixTime", "type": "Nullable(Int64)" }, { "name": "interval", "type": "String" }, { "name": "tokenAddress", "type": "String" } ], "data": [ [ 189.65782030428116, 191.19771269291377, 189.58437185046847, 190.00000000000003, 282545393.3481766, 1484786.4934918114, 1735689600, "1d", "So11111111111111111111111111111111111111112" ], [ 205.95993992290852, 208.07949378793484, 205.8853442021006, 207.90320000000003, 402311189.4337393, 1943426.4228084276, 1735776000, "1d", "So11111111111111111111111111111111111111112" ], [ 208.02620046741387, 216.34037107799142, 206.73117908701826, 215.6642832245662, 93295132.31347863, 447081.33486659755, 1735862400, "1d", "So11111111111111111111111111111111111111112" ], [ 216.93213236976655, 216.99026674175798, 215.39225422045678, 216.6632428457716, 29157258.552583814, 134891.08379508962, 1735948800, "1d", "So11111111111111111111111111111111111111112" ], [ 212.832906441929, 214.16558989838015, 212.73748647845593, 213.4164972681658, 225194163.00528666, 1054759.4801058057, 1736035200, "1d", "So11111111111111111111111111111111111111112" ], [ 213.3476856835307, 218.33239419940801, 213.07537303596683, 218.1433434538596, 141540307.9812308, 657090.9383419061, 1736121600, "1d", "So11111111111111111111111111111111111111112" ], [ 212.0663999414671, 216.39604367789576, 204.34945631796026, 204.58701227454648, 60940467.61426936, 289884.51315699256, 1736208000, "1d", "So11111111111111111111111111111111111111112" ], [ 202.13072878400698, 202.13072878400698, 202.13072878400698, 202.13072878400698, 3.300586, 0.016328967, 1736294400, "1d", "So11111111111111111111111111111111111111112" ] ], "rows": 8 } ] ``` This daily aggregation shows 8 days of price action for Wrapped SOL, including a notable rally from roughly $190 to over $215 mid-week, followed by a pullback. Daily granularity is well suited for swing trading and position analysis. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/ohlcv/token" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/ohlcv/token") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/solana/ohlcv/base-quote` - Retrieve granular OHLCV data with separate base and quote token volumes for detailed trading analysis between any two SPL tokens - `/solana/ohlcv/pool` - Retrieve OHLCV data for individual pool contracts enabling pair-specific price analysis and liquidity venue performance tracking - `/solana/tokens` - Returns a paginated list of known tokens for the Solana chain - `/solana/tokens/holder-distribution-over-time` - Returns the distribution of token holders over a certain block range, at a certain interval, grouped by USD value tiers - `/solana/tokens/security` - Provides comprehensive security analysis for a token on Solana, including ownership concentration, holder distribution, and transaction metrics --- ## Cambrian API: Pool Info **Endpoint:** /api/v1/solana/orca/pool # Orca Pool Info ## Overview Retrieves detailed metrics and information for a specific Solana Orca Whirlpool, identified by its program ID (pool address). Data is sourced from the pre-calculated `orca_pool_details_view`, providing token pair details, pricing, liquidity, volume, fees, and APR in a single call. ## Business Value - **Pool Analysis**: Access comprehensive pool data for liquidity providers and traders - **Trading Intelligence**: Monitor pool state and configuration for informed trading decisions - **Portfolio Management**: Track pool performance and composition for investment strategies - **DeFi Integration**: Enable seamless integration with Orca DEX functionality - **Risk Assessment**: Evaluate pool parameters and liquidity for risk management ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/orca/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | The program ID (address) of the Solana pool. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolAddress | String | The program ID (address) of the Orca pool. | | createdAt | DateTime('UTC') | Timestamp when the pool was created. | | token0Address | String | Mint address of the pool's first token. | | token0Symbol | String | Symbol of the pool's first token. | | token0Decimals | UInt8 | Decimal precision of the first token. | | token1Address | String | Mint address of the pool's second token. | | token1Symbol | String | Symbol of the pool's second token. | | token1Decimals | UInt8 | Decimal precision of the second token. | | tickSpacing | Int32 | Tick spacing configured for the Whirlpool. | | tokenVaultA | String | Address of the vault holding token0 reserves. | | tokenVaultB | String | Address of the vault holding token1 reserves. | | sqrtPriceX64 | UInt128 | Current pool price expressed as sqrt price in X64 fixed-point format. | | currentTick | Nullable(Float64) | Current tick index of the pool. | | price | Nullable(Float64) | Current price of token0 denominated in token1. | | tvlToken0 | Nullable(Float64) | Total value locked, denominated in token0 units. | | tvlToken1 | Nullable(Float64) | Total value locked, denominated in token1 units. | | tvl | Nullable(Float64) | Total value locked in USD. | | volume24h | Nullable(Float64) | Trading volume in USD over the last 24 hours. | | fees24hToken0 | Nullable(Float64) | Fees collected in token0 over the last 24 hours. | | fees24hToken1 | Nullable(Float64) | Fees collected in token1 over the last 24 hours. | | fees24h | Nullable(Float64) | Total fees collected in USD over the last 24 hours. | | apr24h | Nullable(Float64) | Annualized fee return based on the last 24 hours, as a percentage. | | priceVolatility | Nullable(Float64) | Measure of price volatility for the pool. | | utilization24h | Nullable(Float64) | Capital utilization rate over the last 24 hours, as a percentage. | | factoryAddress | String | Address of the Whirlpool program/factory that deployed the pool. | | factoryName | String | Name of the DEX factory (e.g., "Orca"). | ## Examples ### 1. Retrieve Pool Details by Address Fetch detailed metrics for a specific Orca Whirlpool using its pool address. ```bash curl -X GET "https://api.cambrian.org/solana/orca/pool?pool_address=C9U2Ksk6KKWvLEeo5yUQ7Xu46X7NzeBJtd9PBfuXaUSM" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolAddress", "type": "String" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "tokenVaultA", "type": "String" }, { "name": "tokenVaultB", "type": "String" }, { "name": "sqrtPriceX64", "type": "UInt128" }, { "name": "currentTick", "type": "Nullable(Float64)" }, { "name": "price", "type": "Nullable(Float64)" }, { "name": "tvlToken0", "type": "Nullable(Float64)" }, { "name": "tvlToken1", "type": "Nullable(Float64)" }, { "name": "tvl", "type": "Nullable(Float64)" }, { "name": "volume24h", "type": "Nullable(Float64)" }, { "name": "fees24hToken0", "type": "Nullable(Float64)" }, { "name": "fees24hToken1", "type": "Nullable(Float64)" }, { "name": "fees24h", "type": "Nullable(Float64)" }, { "name": "apr24h", "type": "Nullable(Float64)" }, { "name": "priceVolatility", "type": "Nullable(Float64)" }, { "name": "utilization24h", "type": "Nullable(Float64)" }, { "name": "factoryAddress", "type": "String" }, { "name": "factoryName", "type": "String" } ], "data": [ [ "C9U2Ksk6KKWvLEeo5yUQ7Xu46X7NzeBJtd9PBfuXaUSM", "2024-11-05T15:28:26+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump", "Fartcoin ", 6, 16, "2z2dj8yyRmXP8bwP8LqmxeZGVtuAGv4g2wgzp2Rz1QmJ", "5ex8weR6VjuwTrE4aP7juXcGWPTiD9PJeMZiwZZderqc", 13735471750913987000, -5899, 554.4312681473452, 513.063738712, 3026275.207763, 442518.7406462651, 183687.0133043752, 2.034516841, 1071.825864, 293.8993353164525, 24.241517372539, 8.233664334234783, 8.329166666666667, "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc", "Orca" ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. This example returns the SOL/Fartcoin Orca Whirlpool, with a TVL of approximately $3.03M, 24h volume of ~$442.5K, and a 24h fee APR of ~24.24%. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/orca/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/orca/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Pool Info (Multi) **Endpoint:** /api/v1/solana/orca/pool-multi # Pool Info (Multi) ## Overview Retrieves overview metrics for multiple Orca pools in a single request, returning price, TVL, volume, fees, APR, and token metadata for each requested pool address. ## Business Value - **Multi-Pool Analysis**: Query multiple pools in a single request to reduce API calls and improve performance - **Real-Time Metrics**: Access up-to-date price, volume, and liquidity data for portfolio monitoring - **TVL Tracking**: Monitor total value locked across multiple pools for investment analysis - **Fee Analytics**: Track 24-hour fees and APR calculations for yield farming strategies - **Market Intelligence**: Compare pool performance and volatility metrics across different trading pairs ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/orca/pool-multi ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_addresses | string | Yes | - | Comma-separated pool addresses within the same DEX. Example: addr1,addr2,addr3 | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolAddress | String | Pool contract address | | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | String | Mint address of token 0 | | token0Symbol | String | Symbol of token 0 | | token0Decimals | UInt8 | Decimal places for token 0 | | token1Address | String | Mint address of token 1 | | token1Symbol | String | Symbol of token 1 | | token1Decimals | UInt8 | Decimal places for token 1 | | tickSpacing | Int32 | Tick spacing configured for the pool | | tokenVaultA | String | Address of the vault holding token 0 | | tokenVaultB | String | Address of the vault holding token 1 | | sqrtPriceX64 | UInt128 | Current square-root price in X64 fixed-point format | | currentTick | Nullable(Float64) | Current tick index of the pool | | price | Nullable(Float64) | Current price of token 0 in terms of token 1 | | tvlToken0 | Nullable(Float64) | Total value locked denominated in token 0 | | tvlToken1 | Nullable(Float64) | Total value locked denominated in token 1 | | tvl | Nullable(Float64) | Total value locked in USD | | volume24h | Nullable(Float64) | Trading volume in USD over the last 24 hours | | fees24hToken0 | Nullable(Float64) | Fees collected in token 0 over the last 24 hours | | fees24hToken1 | Nullable(Float64) | Fees collected in token 1 over the last 24 hours | | fees24h | Nullable(Float64) | Total fees collected in USD over the last 24 hours | | apr24h | Nullable(Float64) | Annualized fee APR based on the last 24 hours | | priceVolatility | Nullable(Float64) | Price volatility measure over the recent period | | utilization24h | Nullable(Float64) | Capital utilization ratio over the last 24 hours | | factoryAddress | String | Address of the Whirlpool program/factory | | factoryName | String | Name of the DEX factory (e.g., Orca) | ## Examples ### 1. Retrieve metrics for a single Orca pool Fetch metrics for the SOL/USDC Orca Whirlpool by passing its pool address. ```bash curl -X GET "https://api.cambrian.org/solana/orca/pool-multi?pool_addresses=Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolAddress", "type": "String" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "tokenVaultA", "type": "String" }, { "name": "tokenVaultB", "type": "String" }, { "name": "sqrtPriceX64", "type": "UInt128" }, { "name": "currentTick", "type": "Nullable(Float64)" }, { "name": "price", "type": "Nullable(Float64)" }, { "name": "tvlToken0", "type": "Nullable(Float64)" }, { "name": "tvlToken1", "type": "Nullable(Float64)" }, { "name": "tvl", "type": "Nullable(Float64)" }, { "name": "volume24h", "type": "Nullable(Float64)" }, { "name": "fees24hToken0", "type": "Nullable(Float64)" }, { "name": "fees24hToken1", "type": "Nullable(Float64)" }, { "name": "fees24h", "type": "Nullable(Float64)" }, { "name": "apr24h", "type": "Nullable(Float64)" }, { "name": "priceVolatility", "type": "Nullable(Float64)" }, { "name": "utilization24h", "type": "Nullable(Float64)" }, { "name": "factoryAddress", "type": "String" }, { "name": "factoryName", "type": "String" } ], "data": [ [ "Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE", "2023-06-30T06:20:58+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, 4, "EUuUbDcafPrmVTD5M6qoJAoyyNbihBhugADAxRMn5he9", "2WLWEuKDgkDUccTpbwYp1GToYktiSB1cXvreHUwiSUVP", 5021970198956167000, -26023, 74.11546154274731, 224778.616667182, 9388870.572549, 26029285.209932618, 74632696.36542091, 200.20386387, 15032.595722, 29853.085751549406, 41.86198818535955, 0.21357800188961495, 25.6225, "whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc", "Orca" ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. This example returns the SOL/USDC Whirlpool with a TVL of ~$26M, 24h volume of ~$74.6M, and a 24h fee APR of ~41.86%. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), letting you pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/orca/pool-multi" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/orca/pool-multi") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: List Pools **Endpoint:** /api/v1/solana/orca/pools # List Pools (Orca) ## Overview Retrieves a list of all Orca pools registered in the backend database (`orca_pool_registry_target`). It provides essential static information about each pool, including the token pair, decimals, tick spacing, and vault addresses. ## Business Value - **Pool Discovery**: Access a complete registry of all available Orca liquidity pools for market analysis and trading strategy development - **Token Pair Analysis**: Identify trading pairs and their configurations to understand market opportunities and liquidity distribution - **Integration Support**: Obtain essential pool metadata needed for DeFi applications, trading bots, and portfolio management tools - **Market Research**: Analyze the Orca ecosystem structure and track pool creation patterns over time - **Risk Assessment**: Evaluate pool characteristics and token configurations for informed investment decisions ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/orca/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | dex | string (enum: `orca`) | Yes | - | The Decentralized Exchange (DEX) name. Must be `orca` for this endpoint. | | limit | integer | No | 100 | Limit the number of results. Minimum 1, maximum 1000. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. Minimum 0, maximum 100000. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolAddress | String | The address (public key) of the Orca Whirlpool. | | createdAt | DateTime('UTC') | Timestamp of when the pool was created, in UTC. | | token0Address | String | Mint address of the pool's first token (token0). | | token0Symbol | String | Symbol of token0. | | token0Decimals | UInt8 | Number of decimals for token0. | | token1Address | String | Mint address of the pool's second token (token1). | | token1Symbol | String | Symbol of token1. | | token1Decimals | UInt8 | Number of decimals for token1. | | tickSpacing | Int32 | The tick spacing configured for this Whirlpool, which determines granularity of price ranges. | | tokenVaultA | String | Address of the vault account holding token0 reserves. | | tokenVaultB | String | Address of the vault account holding token1 reserves. | ## Examples ### 1. List Orca Pools Retrieve a list of Orca pools, limited to 10 results. ```bash curl -X GET "https://api.cambrian.org/solana/orca/pools?dex=orca&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolAddress", "type": "String" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "String" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "String" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "tickSpacing", "type": "Int32" }, { "name": "tokenVaultA", "type": "String" }, { "name": "tokenVaultB", "type": "String" } ], "data": [ [ "122FD4qsy8zkKqW9J2cZmjTN9hPjP8aE6D2GowFURr71", "2024-04-19T12:30:25+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "7XhEZLWYfJmShx3f2gJTTwFvWFmbgVpZHAp2fozqUg8E", "FONG", 9, 2, "2W6e7m3FKUEKVyuWa86GNgVRbjKAqypQSmXxW7HWTQm3", "DsFL1aHUWBUedEXcNfV8BzLmi94GYw6VxSkdWTGNZerc" ], [ "126kcp6vLs176v9DkU2q1iBy5jUEMGZRzxpkJeQdcmDo", "2026-07-21T09:21:40+00:00", "BetPYFm1iEEPNsYeBXQiCae3cKALa9a1RnEK6bniBMDv", "Ash", 9, "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", "USDT", 6, 32896, "2y1rKeq4p1UbTdCC8ZEuUebmkDFKs7i7YqAXfcQFENYh", "8UHpHM4McFNMxgLqEXQ2uCyzSJTvPY959826uSFQ25iN" ], [ "12BgjwjLMbodFq3gCYW9cMeyRy9z3eL86kcQ7PiPfUyb", "2024-03-12T22:24:39+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "4fvS25Zyq9di8VgQtH4o8MrNzDnKuma3Z8fTgwXd1VMx", "OPPY", 6, 128, "36q2sHd31tPYuL8Yhm3wYMwX5cEBpHJYbhhZ5i5TLJjT", "7tN6zCdNotfmpY2mKDhgMLVibKvbbyUqcLsjvvqbvotw" ], [ "12SgZ1auKJgtyLXgW4Nc5wVzstVStfoQxe6ZXFi5gb3W", "2024-05-13T08:55:47+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "AXNg5aNK3jkJCiMn5Av6yCRrULfwFjvHCBxC27KESxma", "Hello", 6, 1, "GNFjDNoQrGZSZS77KZKicrdnc6Wn5H1hAFFqdWTcdGeq", "E8YBCrGfFVXEwam9wEAJMvd49eCGKHtewDmK6xnMWZnE" ], [ "12aGZp2Q3TaPMouLXGYVZWKUUJdCth2wxS1NVMDRFj8k", "2024-06-02T23:14:05+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "7gbEP2TAy5wM3TmMp5utCrRvdJ3FFqYjgN5KDpXiWPmo", "DEVIN", 6, 128, "ATZpzBQPdMpPnwXhWxJJU4ALWVLFjJAc4zwzAk8kazmr", "DoyucsR2wV9U8UZMcDJikZ5JFY2R3aXvdnLG8M34mzwB" ], [ "12bDxpetQ7E1NCn2HQzby2eX6tUYaBFwBh2X5RL4XkBA", "2024-05-11T04:26:25+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "7RoVuYRxfBeH9fwHrx8LeLte4uJLBM52UmF4nyh4tNiQ", "$smiski", 6, 128, "513tz7Vu847pd4EbezPmMN8uPy4WdgTSMXefvmBF4T7o", "H9u5JGqqcijw3vtka9Fz3mTSwRBs2CsAmWe8TxtanjcT" ], [ "12eDHn6LTCP78UuhLb3fHRhEnHDoJzccLoixdefkFNtf", "2024-02-26T15:20:01+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "D8c8hnr9rWgJZX9QntWHTpw8gkreW24MzLCGbBiHg2JK", "SNOOPY", 9, 1, "7fWfS68VrJoMaqf2VnfWC6Frr4MVQ6oVkc5PSrPr5pR", "5MRdJQXH4MD2527faFJ894Mz1m5rwdmTrcQwHNAhszST" ], [ "12k7ovnF5gSre7eVtWtz8tqKBRGdJdipYqGLM3aHfpsN", "2024-03-16T12:57:58+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "c2sFwnTrVYbjM4ku6TgNk5Egavmh8GEQaLaWMsbUH7h", "JIJIDoge", 2, 256, "CBzgMGgvNfuMqivRtMtkHPmUUnWu2Zh1oN8nwsMJgCza", "41rLTh8ZJrZCuWw2XHwS7HZzddAb6L38X1BGkoxjwJZX" ], [ "12mFQfKgHknzDZTNPPGxpLcWRYh9hjUpYC1hPiWdvFwz", "2024-01-31T16:01:28+00:00", "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN", "JUP", 6, "JxxWsvm9jHt4ah7DT9NuLyVLYZcZLUdPD93PcPQ71Ka", "mockJUP", 9, 256, "FFhGPFyH3ZCeYX8moDwcqJib1Q17sXVWWzmoa7fBKKvE", "3QJRsTrPCFKHrtJ1irtt8JTwgK4RXcJBbRnrrRzkzebC" ], [ "12xeYhezRrpc5fg1t8sUV1bZ94rS6gx8yHgKvB1FF1By", "2024-06-12T04:30:22+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "8vCzsdoss5g9naVRtuVD34jfSmLwM28ucWujrWyppump", "FATHER", 6, 256, "2QSTBtCpu9WJgNswWNoDt7ZxVHCqmNd4fHpQgRv2nkeA", "GAcdA8A42QFZMLZCne9zNG48fVQCyF8hxKSj5o3MRT7B" ] ], "rows": 10 } ] ``` Result collections are limited to 10 items. The response returns pools in a columnar table format: `columns` describes each field's name and ClickHouse type, and `data` contains one array per pool with values in the same order as `columns`. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), letting you pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/orca/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/orca/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Pool Core Metrics **Endpoint:** /api/v1/solana/orca/pools/fee-metrics # Pool Core Metrics ## Overview Retrieves core metrics like fees (total, token0, token1, USD), volume (token0, token1, USD), Total Value Locked (TVL) in USD, and calculated Fee APR for a specific Orca Whirlpool over a given timeframe. ## Business Value - **Portfolio Performance**: Track fee earnings from your liquidity provider positions to understand profitability - **Pool Analytics**: Compare fee APR across different pools to identify high-yield opportunities - **Risk Assessment**: Monitor volume ratios and TVL changes to evaluate pool health and impermanent loss risks - **Strategy Optimization**: Analyze fee collection trends to optimize entry/exit timing for LP positions - **Yield Farming**: Identify pools with consistently high fee generation for maximized returns ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/orca/pools/fee-metrics ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | The public key address of the Orca Whirlpool. | | days | integer | Yes | - | The number of past days to include in the analysis (e.g., 1, 7, 30). | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolId | String | The public key address of the Orca Whirlpool. | | timeframe | String | The timeframe of the analysis, expressed in days (e.g., "7d"). | | feeTier | Float64 | The fee tier of the pool, in basis points. | | feesToken0 | Float64 | Total fees collected in token0 over the timeframe. | | feesToken1 | Float64 | Total fees collected in token1 over the timeframe. | | feesUSD | Float64 | Total fees collected, converted to USD, over the timeframe. | | feeAPR | Float64 | Calculated annualized fee yield (APR) based on fees and TVL. | | feeVolumeRatio | Float64 | Ratio of fees generated to trading volume over the timeframe. | | volumeToken0 | Float64 | Total trading volume in token0 over the timeframe. | | volumeToken1 | Float64 | Total trading volume in token1 over the timeframe. | | volumeUSD | Float64 | Total trading volume, converted to USD, over the timeframe. | | tvlUSD | Float64 | Total Value Locked in the pool, in USD, at time of the query. | | updatedAt | DateTime('UTC') | Timestamp of when the metrics were last updated. | ## Examples ### 1. Retrieve 7-day fee metrics for an Orca Whirlpool Fetches fee, volume, TVL, and APR metrics for a specific Orca Whirlpool over the trailing 7 days. ```bash curl -X GET "https://api.cambrian.org/solana/orca/pools/fee-metrics?pool_address=Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE&days=7" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolId", "type": "String" }, { "name": "timeframe", "type": "String" }, { "name": "feeTier", "type": "Float64" }, { "name": "feesToken0", "type": "Float64" }, { "name": "feesToken1", "type": "Float64" }, { "name": "feesUSD", "type": "Float64" }, { "name": "feeAPR", "type": "Float64" }, { "name": "feeVolumeRatio", "type": "Float64" }, { "name": "volumeToken0", "type": "Float64" }, { "name": "volumeToken1", "type": "Float64" }, { "name": "volumeUSD", "type": "Float64" }, { "name": "tvlUSD", "type": "Float64" }, { "name": "updatedAt", "type": "DateTime('UTC')" } ], "data": [ [ "Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE", "7d", 200, 1148.593060639, 85205.761891, 170240.90812355877, 34.120364239580255, 0.00040000010831539264, 2871482.557460238, 213014296.50264, 425602155.0607356, 26016273.712165374, "2026-08-05T16:03:36+00:00" ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. In this example, the pool `Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE` earned approximately $170,240.91 in fees on ~$425.6M of volume over the trailing 7 days, with a Fee APR of ~34.12% against a TVL of ~$26M. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), paying **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/orca/pools/fee-metrics" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/orca/pools/fee-metrics") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Pool Fee Range Analysis **Endpoint:** /api/v1/solana/orca/pools/fee-ranges # Pool Fee Range Analysis ## Overview Retrieves fee APR and swap utilization data, categorized by price ranges relative to the current price, for a specific Orca Whirlpool. Results are grouped into symmetric percentage bands (e.g. ±5%, ±10%, ±20%) around the current price and include the corresponding tick range and swap utilization for each band. ## Business Value - **Liquidity Optimization**: Understand which price ranges are most actively utilized for better capital allocation - **Risk Assessment**: Analyze concentration risk by seeing how fees and activity are distributed across price tiers - **Performance Analysis**: Track fee generation efficiency across different price ranges relative to current market price - **Strategic Planning**: Use utilization patterns to inform liquidity provision strategies in concentrated liquidity pools - **Market Intelligence**: Gain insights into trading patterns and price movement expectations within the pool ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/orca/pools/fee-ranges ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | The public key address of the Orca Whirlpool. | | days | integer | Yes | - | The number of past days to include in the analysis. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | rangeLabel | String | Label describing the price range band relative to the current price (e.g. "+/- 5%"). | | priceRangeLower | Float64 | Lower bound of the price range for this band. | | priceRangeUpper | Float64 | Upper bound of the price range for this band. | | tickRangeLower | Float64 | Lower tick index corresponding to the price range lower bound. | | tickRangeUpper | Float64 | Upper tick index corresponding to the price range upper bound. | | utilization | Float64 | Percentage of the analysis period during which the pool price stayed within this range. | | updatedAt | DateTime('UTC') | Timestamp (UTC) when this data was last updated. | ## Examples ### 1. Analyzing Fee Range Utilization for an Orca Whirlpool This example retrieves fee range analysis for a specific Orca Whirlpool over the past 7 days, showing utilization across three price bands (±5%, ±10%, ±20%) around the current price. ```bash curl -X GET "https://api.cambrian.org/solana/orca/pools/fee-ranges?pool_address=Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE&days=7" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "rangeLabel", "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%", 70.25833723551439, 77.65395168135801, -26558, -25557, 100, "2026-08-05T15:58:54+00:00" ], [ "+/- 10%", 66.56053001259258, 81.35175890427982, -27098, -25091, 100, "2026-08-05T15:58:54+00:00" ], [ "+/- 20%", 59.16491556674896, 88.74737335012344, -28276, -24221, 100, "2026-08-05T15:58:54+00:00" ] ], "rows": 3 } ] ``` Note: result collections are limited to 10 items. This result shows three price range bands for the pool over the trailing 7-day window. All three bands (±5%, ±10%, ±20%) report 100% utilization: the pool price stayed within each of these ranges for the entire analysis period. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/orca/pools/fee-ranges" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/orca/pools/fee-ranges") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Pool Historical Daily Data **Endpoint:** /api/v1/solana/orca/pools/historical-data # Pool Historical Daily Data ## Overview Retrieves historical daily fee and volume data (in USD) for a specific Orca Whirlpool over a specified timeframe. Each row represents a single day and includes total fees, trading volume, and the fee-to-volume ratio, which supports trend analysis of pool activity over time. ## Business Value - **Pool Performance Analysis**: Track fee generation and trading volume trends over time to assess pool profitability - **Liquidity Strategy Optimization**: Analyze historical data to optimize liquidity provision timing and amounts - **Investment Decision Making**: Use historical volume and fee data to inform decisions about which pools to participate in - **Risk Management**: Monitor pool activity patterns to identify potential risks or opportunities - **Portfolio Tracking**: Track the historical performance of pools in your liquidity portfolio ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/orca/pools/historical-data ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | The public key address of the Orca Whirlpool. | | days | integer | Yes | - | The number of past days to include in the analysis. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | timestamp | UInt32 | Unix timestamp (seconds) representing the start of the day for this data row. | | feesUSD | Nullable(Float64) | Total fees generated by the pool for the day, denominated in USD. | | volumeUSD | Nullable(Float64) | Total trading volume for the pool for the day, denominated in USD. | | feeVolumeRatio | Nullable(Float64) | Ratio of fees to volume for the day, representing the effective fee rate. | | updatedAt | DateTime('UTC') | Timestamp indicating when this record was last updated, in UTC. | ## Examples ### 1. Retrieve 7-Day Historical Data for a Pool This example fetches the past 7 days of fee and volume history for a specific Orca Whirlpool, useful for a quick weekly performance snapshot. ```bash curl -X GET "https://api.cambrian.org/solana/orca/pools/historical-data?pool_address=Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE&days=7" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "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": [ [ 1785283200, 20844.159300246247, 52110387.08494674, 0.0004000000857078176, "2026-08-05T16:03:30+00:00" ], [ 1785369600, 24087.9758500228, 60219923.70983283, 0.00040000010571401086, "2026-08-05T16:03:30+00:00" ], [ 1785456000, 27193.92486284585, 67984794.10235493, 0.0004000001062282232, "2026-08-05T16:03:30+00:00" ], [ 1785542400, 10675.020383373696, 26687539.511153404, 0.00040000017157491543, "2026-08-05T16:03:30+00:00" ], [ 1785628800, 14401.911409827982, 36004767.66202655, 0.00040000012067894467, "2026-08-05T16:03:30+00:00" ], [ 1785715200, 24215.889979202446, 60539706.92858328, 0.0004000001190585402, "2026-08-05T16:03:30+00:00" ], [ 1785801600, 28861.18167505007, 72152935.9149223, 0.00040000010129984397, "2026-08-05T16:03:30+00:00" ], [ 1785888000, 19960.8446639901, 49902100.14864973, 0.00040000009227127105, "2026-08-05T16:03:30+00:00" ] ], "rows": 8 } ] ``` Note: result collections are limited to 10 items. The response returns 8 daily rows for the requested Orca Whirlpool, each with fees, volume, and the resulting fee-to-volume ratio. The fee rate stays consistent at about 0.04% across days even as volume varies. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), letting you pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/orca/pools/historical-data" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/orca/pools/historical-data") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Pool Liquidity Map **Endpoint:** /api/v1/solana/orca/pools/liquidity-map # Pool Liquidity Map ## Overview Retrieves the distribution of net liquidity across price ticks for a specific Orca Whirlpool. Returns liquidity values at representative tick intervals based on the specified resolution, so you can see how liquidity is concentrated across the price curve. Note: the pool must have been created after 2025-02-27. ## Business Value - **Liquidity Analysis**: Understand where liquidity is concentrated in Orca pools to identify optimal trading ranges - **Price Impact Assessment**: Evaluate potential price impact of trades by analyzing liquidity depth at different price levels - **Pool Health Monitoring**: Monitor the distribution and concentration of liquidity to assess pool efficiency - **Trading Strategy Optimization**: Identify price ranges with high liquidity for reduced slippage trading - **Market Making Insights**: Determine optimal price ranges for providing liquidity based on current distribution patterns ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/orca/pools/liquidity-map ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | The public key address of the Orca Whirlpool. | | resolution | integer | Yes | - | The approximate number of data points (tick intervals) desired in the output map. Higher values mean finer granularity. Minimum 10, maximum 1000. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | mapTick | Int64 | The representative tick index for this liquidity data point. | | liquidity | Int256 | The net liquidity value active at this tick interval. | ## Examples ### 1. Retrieve the liquidity map for an Orca Whirlpool This example fetches the liquidity distribution for a specific pool with a resolution of 200 tick intervals, useful for rendering a liquidity depth chart. ```bash curl -X GET "https://api.cambrian.org/solana/orca/pools/liquidity-map?pool_address=DYFk5yvux4mkuQcxkA7H6FWgRQHc1Z7JUb42SJVxnhgG&resolution=200" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "mapTick", "type": "Int64" }, { "name": "liquidity", "type": "Int256" } ], "data": [ [ -443632, "1388308015" ], [ -439200, "1388308015" ], [ -434768, "1388308015" ], [ -430336, "1388308015" ], [ -425904, "1388308015" ], [ -421472, "1388308015" ], [ -417040, "1388308015" ], [ -412608, "1388308015" ], [ -408176, "1388308015" ], [ -403744, "1388308015" ] ], "rows": 201 } ] ``` Result collections are limited to 10 items. The `rows` field reports the total number of tick intervals available (201 in this case), even though the `data` array shown here is capped at 10 entries. Each entry pairs a `mapTick` with its corresponding `liquidity` value; in this range of deeply out-of-the-money ticks, liquidity stays constant at `1388308015`. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/orca/pools/liquidity-map" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/orca/pools/liquidity-map") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Pool Transaction Feed **Endpoint:** /api/v1/solana/pool-transactions # Pool Transaction Feed ## Overview Retrieve a paginated list of trades/transactions for a specified Solana pool address, including swaps, add liquidity, and remove liquidity events. Results are ordered by recency and can be filtered by a configurable lookback window, so you can monitor recent trading activity for any pool. ## Business Value - **Pool Activity Monitoring**: Track all trading activity and liquidity events for specific pools to understand usage patterns and volume trends - **Liquidity Analysis**: Monitor add/remove liquidity events to analyze pool health and provider behavior patterns - **Trade Analytics**: Access detailed swap transaction data including amounts, tokens, and timing for market analysis - **DEX Integration**: Support for multiple DEX protocols (Meteora, Orca, Raydium) provides comprehensive Solana ecosystem coverage - **Historical Research**: Paginated results enable deep historical analysis of pool performance and market dynamics ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/pool-transactions ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | Pool address (base58-44 string) to get transaction history for | | days | integer | Yes | - | Number of days to look back for transactions. Default is 1 day. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | signature | String | Transaction signature uniquely identifying the on-chain transaction | | slot | UInt64 | Solana slot number in which the transaction was processed | | txType | LowCardinality(String) | Type of transaction (e.g., trade) | | amountIn | Float64 | Human-readable amount of the input token | | amountOut | Float64 | Human-readable amount of the output token | | amountInRaw | UInt128 | Raw (unscaled) amount of the input token, in base units | | amountOutRaw | UInt128 | Raw (unscaled) amount of the output token, in base units | | tokenInSymbol | String | Symbol of the input token | | tokenOutSymbol | String | Symbol of the output token | | tokenInAddress | String | Mint address of the input token | | tokenOutAddress | String | Mint address of the output token | | dex | LowCardinality(String) | DEX on which the transaction occurred (e.g., Meteora) | | poolAddress | String | Pool address the transaction occurred in | | blockTime | DateTime('UTC') | UTC timestamp of the block containing the transaction | ## Examples ### 1. Retrieve Recent Pool Transactions This example retrieves the most recent transactions for a specific Solana pool over the last day, limited to 10 results. ```bash curl -X GET "https://api.cambrian.org/solana/pool-transactions?pool_address=5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6&days=1&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "signature", "type": "String" }, { "name": "slot", "type": "UInt64" }, { "name": "txType", "type": "LowCardinality(String)" }, { "name": "amountIn", "type": "Float64" }, { "name": "amountOut", "type": "Float64" }, { "name": "amountInRaw", "type": "UInt128" }, { "name": "amountOutRaw", "type": "UInt128" }, { "name": "tokenInSymbol", "type": "String" }, { "name": "tokenOutSymbol", "type": "String" }, { "name": "tokenInAddress", "type": "String" }, { "name": "tokenOutAddress", "type": "String" }, { "name": "dex", "type": "LowCardinality(String)" }, { "name": "poolAddress", "type": "String" }, { "name": "blockTime", "type": "DateTime('UTC')" } ], "data": [ [ "3C7Rs4RS2np8ZDBnZEdWRviEd9JMQRtcxoEnwnvXqPXmHtb3aQJb1dXH2hNVBBiGXxvXWeP9RvoUAmEp1Wx3eYAU", 437799941, "trade", 0.002546339, 0.188997, 2546339, 188997, "SOL", "USDC", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:51:12+00:00" ], [ "5Gfx1CKYtnXFvFkxLu4KmoV1irgDEd98UfQqqfwVT2vDig4zUbpDAtQkHKkcZMJQq9AHeSM1yqemx1sfegqvfun3", 437799917, "trade", 0.003702573, 0.274815, 3702573, 274815, "SOL", "USDC", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:51:01+00:00" ], [ "5x24BkFvADDNaKL34sJ6Mo4hAcG8W9rusWW2TunxzSqck2qU9uwcjiL89nXTRaxy1jK6kJYqPDABZYHMkmQTrgBb", 437799851, "trade", 4.970724, 0.066915872, 4970724, 66915872, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:34+00:00" ], [ "23fuJNawJKszGrJ7EKHEzjbFaAQrtxic9f9oxovNmdDT7opmFG9vrLp2dWnvXVxwvKFUdhRhuUDpG4euaEkRydAB", 437799834, "trade", 14.700044, 0.197897883, 14700044, 197897883, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:26+00:00" ], [ "kjMruLpfCCTDyue8a4s2wX3bPhqpySP9iBExKtrkyBkmFF1vxaZzNDFKWGqLqujcJJf7X1FzD5aeXJfZZYEXscn", 437799832, "trade", 13.801479, 0.18587101, 13801479, 185871010, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:25+00:00" ], [ "51nfAJQxogQbxecaf9kkqXxwDwdGdhBTU11UYGUJoHbFBTX2Xnq8Lbc8NUe254YC5PnPbSUcRQPogoEgyHQija4w", 437799831, "trade", 13.726801, 0.184865285, 13726801, 184865285, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:25+00:00" ], [ "5zKbJc1g8As4inpCrbJPorhFkTTspk1ezbQ8opUHkmpfeX4FohhSZMJNm6nRs12pHF7M8wpjH5pvGsXgNVUTFfZz", 437799830, "trade", 59.406488, 0.800055116, 59406488, 800055116, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:24+00:00" ], [ "5ZsgSwVNud8yNPzzvSqZX1RJwfUa6QtrGjQgE7kdFabzo95gaXxYT5JAjtHsKoL9Dm3frKCfmeL2i32rK4sr2etK", 437799829, "trade", 899.76645, 12.117578125, 899766450, 12117578125, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:24+00:00" ], [ "31EPigxJ65PHXNrBSdZw6oLfEy4CLkHsZ6Wt8eAKRb7293rG8sVRoU6tgPcKPa6HnHNX6s8MacFrNFZHcexFyEVP", 437799828, "trade", 17285.643154, 232.793889353, 17285643154, 232793889353, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:24+00:00" ], [ "61BmXR2NjRe4hrUTLoa8ase2kUCf7xyKfsdhKHbPdHpLecMuExtdQr5Rx8DiXvnYyJFWG6eJUF87Q9tqJ2cn8Ey2", 437799828, "trade", 1644.241275, 22.143770857, 1644241275, 22143770857, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2026-08-07T13:50:24+00:00" ] ], "rows": 10 } ] ``` Result collections are limited to 10 items. The response shows the 10 most recent transactions for the specified pool over the last day, all classified as "trade" events on Meteora, with alternating SOL/USDC swap directions and their corresponding raw and human-readable amounts. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/pool-transactions" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/pool-transactions") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Pool Transaction Feed (Time Bounded) **Endpoint:** /api/v1/solana/pool-transactions-time-bounded # Pool Transaction Feed (Time Bounded) ## Overview Get detailed transaction data for any SPL token across major Solana DEXs with precise Unix timestamp filtering for historical analysis and event-driven research. This endpoint returns individual swap, add-liquidity, and remove-liquidity events for a specific pool within a defined time window. ## Business Value - **Trading Analysis**: Track pool trading activity and volume patterns over specific time periods - **Performance Monitoring**: Monitor pool performance and liquidity changes during chosen intervals - **Historical Research**: Access detailed transaction history for backtesting and market analysis - **Risk Assessment**: Analyze transaction patterns to understand pool behavior during market events - **Strategy Development**: Use historical data to develop and validate trading strategies ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/pool-transactions-time-bounded ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | string | Yes | - | Pool address (base58-44 string). | | after_time | integer | Yes | - | Unix timestamp - start time for data range | | before_time | integer | Yes | - | Unix timestamp - end time for data range | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | signature | String | Transaction signature (unique identifier) for the on-chain transaction. | | slot | UInt64 | Solana slot number in which the transaction was processed. | | txType | LowCardinality(String) | Type of transaction (e.g., trade, add_liquidity, remove_liquidity). | | amountIn | Float64 | Human-readable amount of the input token. | | amountOut | Float64 | Human-readable amount of the output token. | | amountInRaw | UInt128 | Raw (unscaled) amount of the input token, in base units. | | amountOutRaw | UInt128 | Raw (unscaled) amount of the output token, in base units. | | tokenInSymbol | String | Symbol of the input token. | | tokenOutSymbol | String | Symbol of the output token. | | tokenInAddress | String | Mint address of the input token. | | tokenOutAddress | String | Mint address of the output token. | | dex | LowCardinality(String) | DEX on which the transaction occurred. | | poolAddress | String | Pool address the transaction belongs to. | | blockTime | DateTime('UTC') | UTC timestamp of the block containing the transaction. | ## Examples ### 1. Fetch Time-Bounded Pool Transactions Retrieve transactions for a specific SOL/USDC pool on Meteora within a defined Unix timestamp range. ```bash curl -X GET "https://api.cambrian.org/solana/pool-transactions-time-bounded?pool_address=5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6&after_time=1735689600&before_time=1735776000&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "signature", "type": "String" }, { "name": "slot", "type": "UInt64" }, { "name": "txType", "type": "LowCardinality(String)" }, { "name": "amountIn", "type": "Float64" }, { "name": "amountOut", "type": "Float64" }, { "name": "amountInRaw", "type": "UInt128" }, { "name": "amountOutRaw", "type": "UInt128" }, { "name": "tokenInSymbol", "type": "String" }, { "name": "tokenOutSymbol", "type": "String" }, { "name": "tokenInAddress", "type": "String" }, { "name": "tokenOutAddress", "type": "String" }, { "name": "dex", "type": "LowCardinality(String)" }, { "name": "poolAddress", "type": "String" }, { "name": "blockTime", "type": "DateTime('UTC')" } ], "data": [ [ "3Bq3LhaVVr9CqcELMuRneAwuQaAqDJGNyM4fAjfTYTBRtwjojajjmWGrn5DVRFW7tTpXxVP4974BEZjxsKUH3Nns", 311292565, "add_liquidity", 0.279999933, 0, 279999933, 0, "SOL", "USDC", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:59:38+00:00" ], [ "3xi1tab17hSH6rVGoe7i6BAtXdiuqU84EF7pPdUqNBqsJvyZDiVoQ5ebDHsp31c1vRxGQyi2nfJRb79SHaTTpNME", 311292464, "trade", 37.656821901, 7301.219803, 37656821901, 7301219803, "SOL", "USDC", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:58:57+00:00" ], [ "4GUEKuwZGE3v3qs4KZ5FKdJ8QG1PHCd7RwMqYbFyhoqovZzpHhhnnrCDi8izyxgWufRANTcFocTSBmLBbtgZ4Lty", 311292337, "trade", 13.299050238, 2578.526434, 13299050238, 2578526434, "SOL", "USDC", "So11111111111111111111111111111111111111112", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:58:04+00:00" ], [ "uMycjE36FUXAGV26XjcayZrxTowBEJBF2ty9uHpXUMHQvoLrRk5KpN7PafUWR1WA3v1kdy9m3CdKaATjBCUekYX", 311292290, "trade", 9000.001056, 46.380857956, 9000001056, 46380857956, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:57:45+00:00" ], [ "2vcBQ1TknhNk65eWTgbeEUWZVLV9LWumpBQj8VxHYhBAFADhTZGbdKbNxo4dKFgEiDqaTcdhyJf4MZefyUugNkTc", 311292279, "trade", 663.793848, 3.420813839, 663793848, 3420813839, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:57:41+00:00" ], [ "9xomBtJESJhNiSW7aYLpj3ckWS9zedQgnwkS5nGjoYYWPVHkBWnGkZ8r6YykW6LnkZez1LHRhyM18TMbfqSw3FT", 311292269, "trade", 220, 1.133754169, 220000000, 1133754169, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:57:37+00:00" ], [ "3j5akVEbw7xWCRxk3S5EfxdLmPcHTR8Q9GtnGfh1vVzLRiw7JuLQrpyWr3mUQAwRWzXwMGZ8yfK4U4PsYVLeGbYm", 311292251, "trade", 1165.084732, 6.006622567, 1165084732, 6006622567, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:57:29+00:00" ], [ "Ly3XAVLwrG8gLuyXjqVXvNgV3iySqK7S9MScTby2LmUP1JsufTKYy1XjRS1TQEfhkV917UdukZhbuSJmRsdMyLv", 311292247, "trade", 2016.982173, 10.398600486, 2016982173, 10398600486, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:57:27+00:00" ], [ "5eNNEJw8VpJkMZJYvkMcYNTWy3Attgoj9MB8yyXXKoTZ9qgF5h1Na9Pq7bSmcTaYcyCJimGmr4SXUHqJHjuJT2k7", 311292247, "trade", 2149.682201, 11.082738699, 2149682201, 11082738699, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:57:27+00:00" ], [ "4eJ822NwrrjKZCJdY7LavuH8AkQonP4gdJAPK1kky13NYe2K7X2ewJb1nW8JaPNB9akaPfoyU8XVW12v2L9GQGU1", 311292247, "trade", 2624.894801, 13.532708777, 2624894801, 13532708777, "USDC", "SOL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "So11111111111111111111111111111111111111112", "Meteora", "5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6", "2025-01-01T23:57:27+00:00" ] ], "rows": 10 } ] ``` Result collections are limited to 10 items. The response above shows the most recent transactions (one `add_liquidity` event followed by several `trade` swaps) for the SOL/USDC pool on Meteora within the requested time window, ordered by descending block time. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/pool-transactions-time-bounded" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/pool-transactions-time-bounded") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Price (Current) **Endpoint:** /api/v1/solana/price-current # Token Price (Current) ## Overview Returns the most recent traded USD price of a Solana token, derived from swaps across Orca, Raydium, and Meteora. The price is a volume-weighted average of recent trades, so for a token that has not traded recently it reflects its last trades rather than a live quote. ## Business Value - **No Price Feed to Maintain**: Get a token's most recent traded USD price in one call, without aggregating DEX swaps yourself. ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/price-current ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | The Solana token program address (base58 string). | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | The Solana token program address (base58 string). | | symbol | String | The token's ticker symbol. | | priceUSD | Float64 | The latest available USD price for the token. | ## Examples ### 1. Get the current price of SOL Fetches the latest USD price for the native SOL token using its program address. ```bash curl -X GET "https://api.cambrian.org/solana/price-current?token_address=So11111111111111111111111111111111111111112" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "priceUSD", "type": "Float64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", 73.96796163505655 ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. This response has a single row with the token address, symbol (`SOL`), and current USD price (`73.96796163505655`). ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/price-current" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/price-current") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/price-hour - Aggregated USD price of a Solana token by program address, grouped by the specified interval (e.g., 1H, 1D, 1W, etc). Returns the average price for each interval. - /solana/price-multi - Retrieves the latest available USD prices for multiple Solana token program addresses (comma-separated) - /solana/price-unix - Retrieve historical price data for a specified Solana token at the nearest hour to a specific Unix timestamp. Returns the price, actual update time, and 24-hour price change. - /solana/price-volume/single - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token. - /solana/price-volume/multi - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token. --- ## Cambrian API: Token Price (Interval Aggregated) **Endpoint:** /api/v1/solana/price-hour # Solana Token Price (Hourly Interval Aggregated) ## Overview Returns the aggregated USD price of a Solana token, grouped by a specified time interval (e.g., 1H, 1D, 1W). For each interval bucket, the endpoint returns the average price along with the number of underlying datapoints used in the calculation. ## Business Value - **Historical Price Analysis**: Access comprehensive hourly price data for technical analysis and trend identification - **Trading Strategy Development**: Build data-driven trading algorithms using reliable historical price feeds - **Portfolio Performance Tracking**: Monitor token price movements over custom time intervals for portfolio optimization - **Market Research**: Analyze token price volatility and patterns for investment decision-making - **Integration Flexibility**: Customize data retrieval with various interval options (1H to 1M) and result limits ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/price-hour ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | Token program address (base58-44 string). See tokens for valid addresses. | | interval | string | Yes | - | Time interval for price aggregation. One of: 1H, 2H, 4H, 6H, 8H, 12H, 1D, 3D, 1W, 1M. | | limit | integer | No | 24 | Limit the number of results. | | offset | integer | No | 0 | Offsets the results, letting you skip a number of rows before the response starts returning rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | Token program address (base58-44 string) | | tokenSymbol | String | Token symbol | | intervalStart | DateTime('UTC') | Start timestamp of the aggregation interval, in UTC | | priceUSD | Float64 | Average USD price for the token during this interval | | datapoints | UInt64 | Number of underlying price datapoints averaged for this interval | ## Examples ### 1. Hourly SOL Price History Retrieve the most recent hourly-aggregated USD prices for wrapped SOL. ```bash curl -X GET "https://api.cambrian.org/solana/price-hour?token_address=So11111111111111111111111111111111111111112&interval=1H&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "tokenSymbol", "type": "String" }, { "name": "intervalStart", "type": "DateTime('UTC')" }, { "name": "priceUSD", "type": "Float64" }, { "name": "datapoints", "type": "UInt64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T14:00:00+00:00", 73.89083682097075, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T13:00:00+00:00", 74.0340956599602, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T12:00:00+00:00", 73.88464550162668, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T11:00:00+00:00", 73.59140423518488, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T10:00:00+00:00", 73.56725774800141, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T09:00:00+00:00", 73.47087076766317, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T08:00:00+00:00", 73.06897472270381, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T07:00:00+00:00", 72.87077455055025, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T06:00:00+00:00", 72.89854532508471, 1 ], [ "So11111111111111111111111111111111111111112", "SOL", "2026-08-07T05:00:00+00:00", 72.64493813154434, 1 ] ], "rows": 10 } ] ``` Note: This example limits results to 10 items. Each row represents one hourly interval, starting at `intervalStart`, with the average USD price for wrapped SOL (`priceUSD`) and the count of datapoints (`datapoints`) averaged for that hour. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/price-hour" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/price-hour") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Multi Token Price (Current) **Endpoint:** /api/v1/solana/price-multi # Multi Token Price (Current) ## Overview Retrieves the latest available USD prices for multiple Solana token program addresses in a single request. This endpoint accepts a comma-separated list of base58 token addresses and returns the most recent price and symbol for each. ## Business Value - **Multi-Token Pricing**: Get prices for multiple tokens in a single API call, reducing latency and improving efficiency - **Real-Time Market Data**: Access current market prices for immediate trading decisions and portfolio valuation - **Cost-Effective**: Bulk pricing reduces API call overhead compared to individual price requests - **Data Consistency**: All prices retrieved simultaneously ensure data consistency across token comparisons - **Portfolio Management**: Essential for portfolio tracking applications and multi-token analysis workflows ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/price-multi ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_addresses | string | Yes | - | Comma-separated list of Solana token program addresses (base58 strings). | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | Solana token program address (base58). | | symbol | String | Token symbol. | | priceUSD | Float64 | Latest available price of the token in USD. | ## Examples ### 1. Fetch prices for multiple SPL tokens Retrieves the latest USD prices for SOL and Bonk in a single request using their token program addresses. ```bash curl -X GET "https://api.cambrian.org/solana/price-multi?token_addresses=So11111111111111111111111111111111111111112%2CDezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "priceUSD", "type": "Float64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", 73.98361922559988 ], [ "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", "Bonk", 2.802104412015938e-06 ] ], "rows": 2 } ] ``` The API limits result collections to 10 items. In this example, SOL is priced at about $73.98 and Bonk at about $0.0000028. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/price-multi" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/price-multi") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/price-current - Retrieves the latest available USD price for a given Solana token program address - /solana/price-hour - Aggregated USD price of a Solana token by program address, grouped by the specified interval (e.g., 1H, 1D, 1W, etc). Returns the average price for each interval. - /solana/price-unix - Retrieve historical price data for a specified Solana token at the nearest hour to a specific Unix timestamp. Returns the price, actual update time, and 24-hour price change. - /solana/price-volume/multi - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token. - /solana/token-details-multi - Retrieve comprehensive details for multiple Solana tokens simultaneously. --- ## Cambrian API: Token Price (Unix) **Endpoint:** /api/v1/solana/price-unix # Token Price (Unix) ## Overview Retrieve historical price data for a specified Solana token at the nearest hour to a specific Unix timestamp. Returns the price, actual update time, and 24-hour price change, making it well suited for time-specific price analysis, backtesting, and historical data queries. ## Business Value - **Historical Analysis**: Access accurate price data for any specific point in time for backtesting and analysis - **Time-Series Research**: Build comprehensive datasets for token price movements and volatility studies - **Portfolio Tracking**: Calculate exact portfolio values at specific timestamps for performance analysis - **Data Integration**: Seamlessly integrate historical price data into trading algorithms and research platforms - **Precise Timestamps**: Get hour-level granular price data with UTC timestamp alignment for global consistency ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/price-unix ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | String | Yes | - | Solana token mint address (base58 format). Example: `So11111111111111111111111111111111111111112` | | unixtime | Integer | Yes | - | Hour in unix timestamp to query price for (0 to 10000000000, rounded down to the nearest hour). Example: `1750110000` | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|--------------| | tokenAddress | String | Solana token mint address that was queried | | updateUnixTime | UInt32 | Unix timestamp (nearest hour) at which the price was recorded | | updateUTCTime | String | Human-readable UTC timestamp corresponding to `updateUnixTime` | | priceUSD | Float64 | Token price in USD at the given hour | | change24h | Float64 | Percentage price change over the 24 hours leading up to `updateUnixTime` | | dataSource | String | Source classification of the data (e.g., `historical`) | | availability | String | Availability status of the data point (e.g., `available`) | ## Examples ### 1. Historical Price for Wrapped SOL Retrieve the USD price of Wrapped SOL (SOL) at a specific historical hour, useful for backtesting a trade that occurred at that time. ```bash curl -X GET "https://api.cambrian.org/solana/price-unix?token_address=So11111111111111111111111111111111111111112&unixtime=1750110000" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "updateUnixTime", "type": "UInt32" }, { "name": "updateUTCTime", "type": "String" }, { "name": "priceUSD", "type": "Float64" }, { "name": "change24h", "type": "Float64" }, { "name": "dataSource", "type": "String" }, { "name": "availability", "type": "String" } ], "data": [ [ "So11111111111111111111111111111111111111112", 1750107600, "2025-06-16T21:00:00Z", 157.03180938284908, 5.096096498184193, "historical", "available" ] ], "rows": 1 } ] ``` The requested unix time (1750110000) was rounded down to the nearest hour (1750107600, i.e. 2025-06-16T21:00:00Z), at which point SOL traded at approximately $157.03, up ~5.10% over the prior 24 hours. ### 2. Historical Price for a Stablecoin (USDC) Retrieve the historical price of USDC at the same hour to verify stablecoin peg stability over time. ```bash curl -X GET "https://api.cambrian.org/solana/price-unix?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&unixtime=1750110000" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "updateUnixTime", "type": "UInt32" }, { "name": "updateUTCTime", "type": "String" }, { "name": "priceUSD", "type": "Float64" }, { "name": "change24h", "type": "Float64" }, { "name": "dataSource", "type": "String" }, { "name": "availability", "type": "String" } ], "data": [ [ "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", 1750107600, "2025-06-16T21:00:00Z", 0.9999439763517698, -0.0013210433825215158, "historical", "available" ] ], "rows": 1 } ] ``` At the same historical hour, USDC traded at approximately $0.99994, confirming the stablecoin held close to its $1.00 peg with a negligible 24-hour change of -0.0013%. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2) — pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/price-unix" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/price-unix") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2–5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/solana/price-current` - Retrieves the latest available USD price for a given Solana token program address - `/solana/price-hour` - Aggregated USD price of a Solana token by program address, grouped by the specified interval (e.g., 1H, 1D, 1W, etc). Returns the average price for each interval. - `/solana/price-multi` - Retrieves the latest available USD prices for multiple Solana token program addresses (comma-separated) - `/solana/price-volume/single` - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token. - `/solana/price-volume/multi` - Retrieve current USD price, timeframe volume, and percentage changes for any SPL token (batch). --- ## Cambrian API: Token Price and Volume (Multi) **Endpoint:** /api/v1/solana/price-volume/multi # Token Price and Volume (Multi) ## Overview Retrieve current USD price, timeframe volume, and percentage changes for multiple SPL tokens in a single request. This endpoint combines price and volume data across major Solana DEXs to reduce API calls and improve application performance. ## Business Value - **Multi-token Efficiency**: Query up to 50 tokens simultaneously, reducing API calls by 50x compared to individual requests - **Real-time Price Tracking**: Get current USD prices with timestamp precision for accurate market data - **Volume Analytics**: Track trading volume and percentage changes over customizable timeframes (1h-24h) - **Performance Optimization**: Single-request design minimizes latency for portfolio and dashboard applications - **Cross-DEX Aggregation**: Consolidated data from major Solana decentralized exchanges for comprehensive market coverage ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/price-volume/multi ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_addresses | String | Yes | - | Comma-separated SPL token mint addresses (max 50, base58). Example: `So11111111111111111111111111111111111111112` | | timeframe | String | Yes | - | Timeframe for volume/change calculations. One of: `1h`, `2h`, `4h`, `8h`, `24h` | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | The Solana SPL token mint address | | symbol | String | Token symbol (e.g., SOL, USDC) | | priceUSD | Float64 | Current USD price of the token | | updateUnixTime | UInt32 | Unix timestamp of the last price update | | volumeUSD | Float64 | Trading volume in USD for the specified timeframe | | volumeChangePercent | Nullable(Float64) | Percentage change in volume compared to the previous equivalent period | | priceChangePercent | Nullable(Float64) | Percentage change in price over the specified timeframe | | priceChangeUSD | Float64 | Absolute price change in USD over the specified timeframe | ## Examples ### 1. Single Token Price and Volume Get current price and 24-hour volume data for SOL. ```bash curl -X GET "https://api.cambrian.org/solana/price-volume/multi?token_addresses=So11111111111111111111111111111111111111112&timeframe=24h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "priceUSD", "type": "Float64" }, { "name": "updateUnixTime", "type": "UInt32" }, { "name": "volumeUSD", "type": "Float64" }, { "name": "volumeChangePercent", "type": "Nullable(Float64)" }, { "name": "priceChangePercent", "type": "Nullable(Float64)" }, { "name": "priceChangeUSD", "type": "Float64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", 74.08998328711053, 1785882990, 5809344077.13, 7.49, 0.81, 0.5989375792962619 ] ], "rows": 1 } ``` This response shows SOL trading at approximately $74.09, with a 24-hour volume of roughly $5.81B, a +0.81% price change, and a +7.49% volume change versus the prior 24-hour period. ### 2. Multiple Tokens Analysis Query price and volume data for SOL and USDC together using a shorter 1-hour timeframe. ```bash curl -X GET "https://api.cambrian.org/solana/price-volume/multi?token_addresses=So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&timeframe=1h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "priceUSD", "type": "Float64" }, { "name": "updateUnixTime", "type": "UInt32" }, { "name": "volumeUSD", "type": "Float64" }, { "name": "volumeChangePercent", "type": "Nullable(Float64)" }, { "name": "priceChangePercent", "type": "Nullable(Float64)" }, { "name": "priceChangeUSD", "type": "Float64" } ], "data": [ [ "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 1, 1785883016, 7764622.2, -33.72, 0.01, 0.00009741738607205175 ], [ "So11111111111111111111111111111111111111112", "SOL", 74.09165043246642, 1785883016, 229135891.69, -2.16, 0.03, 0.02149753241180008 ] ], "rows": 2 } ``` This example demonstrates fetching multiple tokens in one call: USDC holds its $1.00 peg (0.01% change) with a -33.72% drop in 1-hour volume, while SOL is up 0.03% with a -2.16% volume change over the same window. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/price-volume/multi" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/price-volume/multi") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/solana/price-volume/single` - Retrieve current USD price, timeframe volume, and percentage changes for a single SPL token - `/solana/price-current` - Retrieves the latest available USD price for a given Solana token program address - `/solana/price-multi` - Retrieves the latest available USD prices for multiple Solana token program addresses (comma-separated) - `/solana/price-hour` - Aggregated USD price of a Solana token by program address, grouped by the specified interval - `/solana/price-unix` - Retrieve historical price data for a specified Solana token at the nearest hour to a specific Unix timestamp --- ## Cambrian API: Token Price and Volume (Single) **Endpoint:** /api/v1/solana/price-volume/single # Token Price and Volume (Single) ## Overview Retrieve current USD price, timeframe volume, and percentage changes for any SPL token on Solana. This endpoint combines price and volume data in a single request to reduce API calls and improve application performance, with data aggregated across major Solana DEXs. ## Business Value - **Unified Data Access**: Get both price and volume metrics in a single API call, reducing latency and API usage - **Performance Optimization**: Minimizes network requests by combining related data points into one response - **Multi-DEX Coverage**: Aggregated data from major Solana DEXs provides comprehensive market view - **Real-time Analytics**: Current pricing and volume changes enable responsive trading and portfolio applications - **Developer Efficiency**: Streamlined integration reduces code complexity for applications needing both price and volume data ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/price-volume/single ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | SPL token mint address (base58, 44 chars) | | timeframe | string | Yes | - | Timeframe: 1h, 2h, 4h, 8h, 24h | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | SPL token mint address | | symbol | String | Token symbol | | priceUSD | Float64 | Current price of the token in USD | | updateUnixTime | UInt32 | Unix timestamp of when the price was last updated | | volumeUSD | Float64 | Trading volume in USD over the specified timeframe | | volumeChangePercent | Nullable(Float64) | Percentage change in volume over the specified timeframe | | priceChangePercent | Nullable(Float64) | Percentage change in price over the specified timeframe | | priceChangeUSD | Float64 | Change in price (in USD) over the specified timeframe | ## Examples ### 1. Get 24-hour price and volume for SOL Retrieve the current price, 24-hour volume, and percentage changes for the native SOL token. ```bash curl -X GET "https://api.cambrian.org/solana/price-volume/single?token_address=So11111111111111111111111111111111111111112&timeframe=24h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "priceUSD", "type": "Float64" }, { "name": "updateUnixTime", "type": "UInt32" }, { "name": "volumeUSD", "type": "Float64" }, { "name": "volumeChangePercent", "type": "Nullable(Float64)" }, { "name": "priceChangePercent", "type": "Nullable(Float64)" }, { "name": "priceChangeUSD", "type": "Float64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", 73.98361922559988, 1785939569, 6720158901.17, 15.19, 0.57, 0.41930502657031354 ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. The response shows SOL trading at approximately $73.98, with 24-hour trading volume of over $6.7 billion, a 15.19% increase in volume, and a 0.57% increase in price over the timeframe. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), paying **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/price-volume/single" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/price-volume/single") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/price-volume/multi - Retrieve current USD price, timeframe volume, and percentage changes for multiple SPL tokens in a single request. - /solana/price-current - Retrieves the latest available USD price for a given Solana token program address. - /solana/trade-statistics - Get instant trade analytics and performance metrics for any SPL tokens, including buy/sell volume breakdowns. - /solana/ohlcv/token - Retrieve Open, High, Low, Close, and Volume data for any SPL token. - /solana/price-hour - Aggregated USD price of a Solana token, grouped by the specified interval. --- ## Cambrian API: Pool Info **Endpoint:** /api/v1/solana/raydium-clmm/pool # Raydium CLMM Pool Info ## Overview Retrieve detailed pool information for a specific Raydium CLMM (Concentrated Liquidity Market Maker) pool on Solana. Returns pricing, liquidity, and performance metrics including TVL, 24-hour volume, fees, and APR. ## Business Value - **Pool Analysis**: Get real-time metrics for specific Raydium CLMM pools including TVL, APR, and 24h volume - **Trading Intelligence**: Access current price, tick information, and liquidity utilization for informed trading decisions - **Risk Assessment**: Monitor pool volatility, fee tiers, and utilization rates to evaluate investment opportunities - **Portfolio Management**: Track performance metrics and fees generated by liquidity positions - **Market Research**: Analyze token pair dynamics and pool efficiency across different fee tiers ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/raydium-clmm/pool ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | pool_address | String | Yes | - | Program ID for raydium clmm pool | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | chainId | UInt16 | Chain ID of the network (900 for Solana) | | dexAddress | String | Program address of the Raydium CLMM DEX | | dexName | String | Name of the DEX (Raydium CLMM) | | poolAddress | FixedString(44) | Address of the pool | | createdAt | DateTime('UTC') | Timestamp when the pool was created | | token0Address | FixedString(44) | Mint address of token0 | | token0Symbol | String | Symbol of token0 | | token0Decimals | UInt8 | Number of decimal places for token0 | | token1Address | FixedString(44) | Mint address of token1 | | token1Symbol | String | Symbol of token1 | | token1Decimals | UInt8 | Number of decimal places for token1 | | feeTier | UInt32 | Fee tier of the pool | | tickSpacing | UInt16 | Tick spacing configured for the pool | | sqrtPriceX64 | UInt128 | Current square root price in X64 fixed-point format | | tick | Int32 | Current tick index of the pool | | price | Float64 | Current price of token0 denominated in token1 | | tvlToken0 | Float64 | Total value locked in token0 (native units) | | tvlToken1 | Float64 | Total value locked in token1 (native units) | | tvlToken0Usd | Float64 | USD value of token0 TVL | | tvlToken1Usd | Float64 | USD value of token1 TVL | | tvl | Float64 | Total value locked in the pool, in USD | | volume24h | Float64 | Trading volume in USD over the last 24 hours | | fees24h | Float64 | Fees generated in USD over the last 24 hours | | apr24h | Float64 | Annualized percentage rate based on 24-hour fees | | priceVolatility | Float64 | Price volatility metric for the pool | | utilization24h | Float64 | Capital utilization percentage over the last 24 hours | ## Examples ### 1. Get Pool Info for a Raydium CLMM Pool Retrieve pool metrics for the SOL/USDC Raydium CLMM pool by its pool address. ```bash curl -X GET "https://api.cambrian.org/solana/raydium-clmm/pool?pool_address=3ucNos4NbumPLZNWztqGHNFFgkHeRMBQAVemeeomsUxv" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "String" }, { "name": "dexName", "type": "String" }, { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "token0Address", "type": "FixedString(44)" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "FixedString(44)" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "feeTier", "type": "UInt32" }, { "name": "tickSpacing", "type": "UInt16" }, { "name": "sqrtPriceX64", "type": "UInt128" }, { "name": "tick", "type": "Int32" }, { "name": "price", "type": "Float64" }, { "name": "tvlToken0", "type": "Float64" }, { "name": "tvlToken1", "type": "Float64" }, { "name": "tvlToken0Usd", "type": "Float64" }, { "name": "tvlToken1Usd", "type": "Float64" }, { "name": "tvl", "type": "Float64" }, { "name": "volume24h", "type": "Float64" }, { "name": "fees24h", "type": "Float64" }, { "name": "apr24h", "type": "Float64" }, { "name": "priceVolatility", "type": "Float64" }, { "name": "utilization24h", "type": "Float64" } ], "data": [ [ 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "3ucNos4NbumPLZNWztqGHNFFgkHeRMBQAVemeeomsUxv", "2024-08-07T13:33:36+00:00", "So11111111111111111111111111111111111111112", "SOL", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, 400, 1, 5007514919866041000, -26081, 73.68940653485875, 64128.60366252, 1340710.78242, 4729199.201131496, 1340710.78242, 6069909.983551496, 14887521.413448513, 5955.008565379405, 35.80906689314238, 0.0014831762375695026, 100 ] ], "rows": 1 } ] ``` > Note: Result collections are limited to 10 items. This response describes the SOL/USDC Raydium CLMM pool created on 2024-08-07, with a current price of ~73.69 USDC per SOL, total TVL of ~$6.07M, 24-hour volume of ~$14.89M, and a 24-hour APR of ~35.81%. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/raydium-clmm/pool" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/raydium-clmm/pool") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/raydium-clmm/pool-multi - Get comprehensive overview metrics for multiple Raydium CLMM pools simultaneously - /solana/raydium-clmm/pools - Lists basic pool information for Raydium CLMM - /solana/orca/pool - Retrieves detailed metrics and information for a specific Orca pool - /solana/meteora-dlmm/pool - Returns basic pool information for a Meteora pool - /solana/pool-transactions - Retrieve a paginated list of trades/transactions for a specified Solana pool --- ## Cambrian API: List Pools **Endpoint:** /api/v1/solana/raydium-clmm/pools # Raydium CLMM Pools ## Overview Lists basic pool information for all Raydium CLMM (Concentrated Liquidity Market Maker) pools on Solana. Returns core identifying and configuration data for each pool, including token pairs, fee tier, and tick spacing. ## Business Value - **Pool Discovery**: Identify and analyze all available Raydium CLMM pools for trading and liquidity provision opportunities - **Market Intelligence**: Track new pool creation activity and monitor the expansion of the Raydium ecosystem - **Trading Strategy**: Access complete pool metadata to develop informed trading strategies based on fee tiers and token pairs - **Portfolio Management**: Evaluate potential liquidity mining opportunities across different fee structures - **DeFi Analytics**: Perform comprehensive analysis of the Raydium CLMM ecosystem for research and investment decisions ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/raydium-clmm/pools ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | limit | integer | No | 100 | Maximum number of pool records to return per page | | offset | integer | No | 0 | Number of pool records to skip, for pagination | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | poolAddress | FixedString(44) | On-chain address of the Raydium CLMM pool | | chainId | UInt16 | Chain identifier for the pool (900 = Solana) | | dexAddress | FixedString(44) | Program address of the Raydium CLMM DEX | | dexName | String | Human-readable DEX name ("Raydium CLMM") | | token0Address | FixedString(44) | Mint address of the first token in the pair | | token0Symbol | String | Symbol of the first token in the pair | | token0Decimals | UInt8 | Decimal precision of the first token | | token1Address | FixedString(44) | Mint address of the second token in the pair | | token1Symbol | String | Symbol of the second token in the pair | | token1Decimals | UInt8 | Decimal precision of the second token | | createdAt | DateTime('UTC') | Timestamp when the pool was created | | fee | UInt32 | Fee tier of the pool, in hundredths of a basis point | | tickSpacing | UInt16 | Tick spacing configured for the pool | ## Examples ### 1. List Raydium CLMM Pools (default paging) Retrieves the default page of Raydium CLMM pools with no explicit paging parameters. ```bash curl -X GET "https://api.cambrian.org/solana/raydium-clmm/pools" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(44)" }, { "name": "dexName", "type": "String" }, { "name": "token0Address", "type": "FixedString(44)" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "FixedString(44)" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "UInt16" } ], "data": [ [ "Ax2g3wLJEcyaxAXyVZm9NZ65wYpFfdCZAYm2MLEbtKjM", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", "USDT", 6, "GtXn1D1BV9WdtqjCBhaSfXm92oc3fo17rt3hoMreQk8L", "FEFER", 9, "2026-08-04T22:36:06+00:00", 40000, 120 ], [ "2gvSrNosXFXxJNSQyeRY25EdiwtFERsbKFQjb4dRXYCt", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "5LJgBtMQv6NP7rqYJFY1Rcht6e3zUqUJSerzPvHf2L4C", "FEFER", 9, "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", "USDT", 6, "2026-08-04T22:34:14+00:00", 40000, 120 ], [ "Dr5R4T7B68gD85iV7vrzB1WLfZrrHphMZVRS5tB3oyMy", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "Fo8rGRg4bfgJPMN5Xdpc9TXX52Z3uB5UgkugCSYM68u4", "EUROPOOR", 9, "HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr", "EURC", 6, "2026-08-04T22:32:04+00:00", 40000, 120 ], [ "EyJfEjtZ9ZqWh4x8VNtwYvGqy5Uu5S3S13u7THroxQc5", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "HZKoNa36QMrrqiRzS2TXTv1pk94L3YbAsePnhKD9JzMG", "KEKE", 6, "J2VABMu4MSZRdpUrmAFsiY1cUmH12EW8TrwGYbssdbYp", "USDKEK", 6, "2026-08-04T15:56:58+00:00", 20000, 120 ], [ "5kD59M5WgYYq4jvGcaeYxVswZG7p69pWAaEm9kSgGqMy", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "So11111111111111111111111111111111111111112", "SOL", 9, "FGc5bVp6LQUpF2AKigkedsp3cPxSbgZLAUEKqXReXBXP", "STEST", 6, "2026-08-04T11:04:05+00:00", 20000, 120 ], [ "2P9trwoT1kVKngH91Acg4qb6gNsx2UZNiiJyAd3fceqZ", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "Hnnhwcoc93ubGA9CcCL77jdC8TZZz1vhgSpAjYvJiS6M", "MVP", 9, "2026-08-03T21:19:58+00:00", 100, 1 ], [ "25NZH72VUBWbduLgKaiozGoCsSQQpWWWMje2aBUS4K7U", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "5dUXcCLVpqeYsXn5aqkwAAa2pd3esLDquU8ZGqheKNXe", "USCC", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-08-03T21:13:03+00:00", 100, 1 ], [ "8Ec5rbL1oZbutBFCmAsKxuc4Bj6z1i9BAnTxmKUXukyj", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "ERrafZVDRdpMuAkmZmeuSqUCjSYicQDXNsd7UdKAgMKY", "KEKED", 6, "J2VABMu4MSZRdpUrmAFsiY1cUmH12EW8TrwGYbssdbYp", "USDKEK", 6, "2026-08-03T13:48:39+00:00", 20000, 120 ], [ "BhoPMnPM7nhdeCBPX3mzgMBF8xSGMcodVwaE2wgGFJTG", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "8Z3xYDeo8mvAf7EChbQtzKF1weguzETeRtHyCzNhpteY", "MVP", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-08-03T07:16:10+00:00", 100, 1 ], [ "D7MQsffMqa6tDVJDN5RArivg7uubz8PGfD5Trq2zhUyE", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "CcZHWC3jB6hHNZFqkxGJm2H7ESNQbFQvQR1iRghWSpCE", "RDUS", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-08-02T18:54:58+00:00", 100, 1 ] ], "rows": 100 } ] ``` The result collection above is limited to its first 10 items for documentation purposes; the live `rows` value (100) reflects the actual page size returned by the API. Each row represents a distinct Raydium CLMM pool with its token pair, fee tier, and creation time. ### 2. Paginate Through Pools with limit and offset Uses `limit` and `offset` to retrieve a specific page of results, useful for iterating through the full pool list. ```bash curl -X GET "https://api.cambrian.org/solana/raydium-clmm/pools?limit=5&offset=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "chainId", "type": "UInt16" }, { "name": "dexAddress", "type": "FixedString(44)" }, { "name": "dexName", "type": "String" }, { "name": "token0Address", "type": "FixedString(44)" }, { "name": "token0Symbol", "type": "String" }, { "name": "token0Decimals", "type": "UInt8" }, { "name": "token1Address", "type": "FixedString(44)" }, { "name": "token1Symbol", "type": "String" }, { "name": "token1Decimals", "type": "UInt8" }, { "name": "createdAt", "type": "DateTime('UTC')" }, { "name": "fee", "type": "UInt32" }, { "name": "tickSpacing", "type": "UInt16" } ], "data": [ [ "F4Ye9gU2ae28KxBX9XsztDhpLyePnDnkGJeS4iki8hgF", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "HeTfUDwPzcLR9VTDwakLrteqJTLannBRjGrDFk7hDy7S", "OKUD", 9, "2026-08-02T18:28:38+00:00", 100, 1 ], [ "4nNjLSZ4DbGpdcrznqXU3TdTSwi1RknXP9CT1y1hcJyb", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "FgyEKM1DVzRdLR3AuEvf39ArTtFdEdnaefnBURSvuPvb", "RDUS", 9, "2026-08-02T12:26:43+00:00", 100, 1 ], [ "5hDabLS7nkXwZ4QzMtm3GyuScrmhwkJstWVkJDhKNFiE", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "8d5krtToMwSCDgndfP3eiz5tgbDduSXzbG9y4Qj6nJSK", "RSDU", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-08-02T11:50:21+00:00", 100, 1 ], [ "2Ebe4iNoMEUbjixjzfdUoXh4qpddDCe2ff4B9xm5zGHA", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "9x7tDhKJonFwTXfWME56oA1BwQfLdpybgDXc4UkJ797b", "MVP", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-08-02T06:29:27+00:00", 100, 1 ], [ "CFfPxfzrvaiydwZsZwVo33JbuDgrjjVTr5BUCyd2i39a", 900, "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", "Raydium CLMM", "6RFwqTYdML3gaGjWygte9VBja7kmNH6CenHTszbQLbtx", "MVP", 9, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "USDC", 6, "2026-08-02T06:17:01+00:00", 100, 1 ] ], "rows": 5 } ] ``` With `limit=5&offset=10`, exactly 5 pool records are returned (rows: 5), skipping the first 10 pools in the default ordering. This demonstrates pagination over the full pool list. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/raydium-clmm/pools" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/raydium-clmm/pools") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/solana/raydium-clmm/pool` - This endpoint returns pool info for a specific raydium clmm pool. Among metrics returned are, tvl, apr24h, volume24h - `/solana/raydium-clmm/pool-multi` - Get comprehensive overview metrics for multiple pools/pairs simultaneously within the same DEX. Returns pool details including price, volume, trades, and token information. - `/solana/orca/pools` - Retrieves a list of all Orca pools registered in the backend database (orca_pool_registry_target). It provides essential static information about each pool. - `/solana/meteora-dlmm/pools` - This endpoint lists meteora pools - `/solana/token-pool-search` - Find pools containing a specific token and retrieve comprehensive trading statistics including 24h volume, trade counts, and buy/sell ratios. Essential for token analysis, liquidity discovery, and identifying the most active trading venues for any token. --- ## Cambrian API: Token Details **Endpoint:** /api/v1/solana/token-details # Token Details ## Overview Retrieves details about a Solana token, including price history, trade statistics, holder information, and other metrics. The endpoint returns current price, trading volume, buy/sell breakdowns, and supply metrics in a single response. ## Business Value - **Market Analysis**: Access current price and trading volume data for investment decisions and market research - **Trading Intelligence**: Get 1h, 24h, and 7-day trading statistics for algorithmic trading strategies - **Portfolio Tracking**: Monitor token metrics including holder count and fully diluted valuation for portfolio management - **Risk Assessment**: Analyze buy/sell ratios and volume patterns to assess token liquidity and market sentiment - **Token Research**: Access fundamental token data including symbol, name, decimals, and supply information ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/token-details ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | The Solana token program address (base58 string) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | The Solana token program address (base58 string) | | symbol | String | Token symbol | | name | String | Token name | | decimals | UInt8 | Number of decimal places for the token | | lastTradeUnixTime | UInt32 | Unix timestamp of the most recent trade | | lastTradeHumanTime | String | Human-readable timestamp of the most recent trade | | priceUSD | Float64 | Current price of the token in USD | | trade1hCount | UInt64 | Number of trades in the last 1 hour | | trade24hCount | UInt64 | Number of trades in the last 24 hours | | trade7dCount | UInt64 | Number of trades in the last 7 days | | volume1h | Float64 | Trading volume (in token units) over the last 1 hour | | volume24h | Float64 | Trading volume (in token units) over the last 24 hours | | volume7d | Float64 | Trading volume (in token units) over the last 7 days | | volume1hUSD | Float64 | Trading volume in USD over the last 1 hour | | volume24hUSD | Float64 | Trading volume in USD over the last 24 hours | | volume7dUSD | Float64 | Trading volume in USD over the last 7 days | | buy24hCount | UInt64 | Number of buy trades in the last 24 hours | | sell24hCount | UInt64 | Number of sell trades in the last 24 hours | | buyVolume24h | Float64 | Buy volume (in token units) over the last 24 hours | | sellVolume24h | Float64 | Sell volume (in token units) over the last 24 hours | | buyVolume24hUSD | Float64 | Buy volume in USD over the last 24 hours | | sellVolume24hUSD | Float64 | Sell volume in USD over the last 24 hours | | holderCount | Nullable(UInt64) | Total number of token holders | | totalSupply | Nullable(Float64) | Total supply of the token | | fdvUSD | Nullable(Float64) | Fully diluted valuation in USD | ## Examples ### 1. Retrieve Token Details for Wrapped SOL This example fetches details for Wrapped SOL, including current price, trade activity, and volume across multiple timeframes. ```bash curl -X GET "https://api.cambrian.org/solana/token-details?token_address=So11111111111111111111111111111111111111112" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "name", "type": "String" }, { "name": "decimals", "type": "UInt8" }, { "name": "lastTradeUnixTime", "type": "UInt32" }, { "name": "lastTradeHumanTime", "type": "String" }, { "name": "priceUSD", "type": "Float64" }, { "name": "trade1hCount", "type": "UInt64" }, { "name": "trade24hCount", "type": "UInt64" }, { "name": "trade7dCount", "type": "UInt64" }, { "name": "volume1h", "type": "Float64" }, { "name": "volume24h", "type": "Float64" }, { "name": "volume7d", "type": "Float64" }, { "name": "volume1hUSD", "type": "Float64" }, { "name": "volume24hUSD", "type": "Float64" }, { "name": "volume7dUSD", "type": "Float64" }, { "name": "buy24hCount", "type": "UInt64" }, { "name": "sell24hCount", "type": "UInt64" }, { "name": "buyVolume24h", "type": "Float64" }, { "name": "sellVolume24h", "type": "Float64" }, { "name": "buyVolume24hUSD", "type": "Float64" }, { "name": "sellVolume24hUSD", "type": "Float64" }, { "name": "holderCount", "type": "Nullable(UInt64)" }, { "name": "totalSupply", "type": "Nullable(Float64)" }, { "name": "fdvUSD", "type": "Nullable(Float64)" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 1785940953, "2026-08-05 14:42:33", 73.63365510418993, 1038608, 23761377, 147533755, 4488665.3103171615, 91296628.87546705, 508123466.21481895, 330516833.3380355, 6722504482.791368, 37414988061.60748, 9530398, 14230979, 45464572.17362762, 45832056.7018394, 3347722626.892447, 3374781855.898919, 9790713, 13348181.108462175, 982875364.0087674 ] ], "rows": 1 } ] ``` Note: Result collections are limited to 10 items. This result shows Wrapped SOL trading at about $73.63, with over 23.7 million trades in the past 24 hours, a 24h USD volume above $6.7 billion, and roughly 9.79 million holders. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/token-details" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/token-details") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/token-details-multi - Retrieve comprehensive details for multiple Solana tokens simultaneously - /solana/price-current - Retrieves the latest available USD price for a given Solana token program address - /solana/trade-statistics - Get instant trade analytics and performance metrics for any SPL tokens - /solana/tokens/holders - Returns a list of accounts currently holding a specific Solana token - /solana/trending-tokens - Retrieves a list of trending Solana tokens --- ## Cambrian API: Token Details Multi **Endpoint:** /api/v1/solana/token-details-multi # Token Details Multi ## Overview Get detailed data for multiple Solana tokens in a single request. The response uses the same structure as the single-token `token-details` endpoint, including price, trading activity, volume, and holder metrics, batched for up to 50 tokens per call. ## Business Value - **Batch Processing**: Query up to 50 tokens in a single API call, dramatically reducing latency and API calls compared to individual requests - **Portfolio Analysis**: Efficiently gather comprehensive metrics for entire token portfolios or watchlists in one operation - **Trading Intelligence**: Access real-time price data, volume metrics, holder counts, and trading statistics for multiple tokens simultaneously - **Cost Optimization**: Minimize API usage costs by batching multiple token queries into single requests - **Performance Enhancement**: Reduce network overhead and improve application responsiveness with bulk data retrieval ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/token-details-multi ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_addresses | string | Yes | - | Comma-separated Solana token mint addresses (max 50, base58). Example: `So11111111111111111111111111111111111111112,DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263` | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | Solana token mint address | | symbol | String | Token ticker symbol | | name | String | Full token name | | decimals | UInt8 | Number of decimal places for the token | | priceUSD | Float64 | Current price of the token in USD | | lastTradeUnixTime | UInt32 | Unix timestamp of the most recent trade | | lastTradeHumanTime | String | Human-readable timestamp of the most recent trade | | trade1hCount | UInt64 | Number of trades in the last 1 hour | | trade24hCount | UInt64 | Number of trades in the last 24 hours | | trade7dCount | UInt64 | Number of trades in the last 7 days | | volume1h | Float64 | Trading volume (token units) in the last 1 hour | | volume24h | Float64 | Trading volume (token units) in the last 24 hours | | volume7d | Float64 | Trading volume (token units) in the last 7 days | | volume1hUSD | Float64 | Trading volume in USD over the last 1 hour | | volume24hUSD | Float64 | Trading volume in USD over the last 24 hours | | volume7dUSD | Float64 | Trading volume in USD over the last 7 days | | buy24hCount | UInt64 | Number of buy trades in the last 24 hours | | sell24hCount | UInt64 | Number of sell trades in the last 24 hours | | buyVolume24h | Float64 | Buy volume (token units) in the last 24 hours | | sellVolume24h | Float64 | Sell volume (token units) in the last 24 hours | | buyVolume24hUSD | Float64 | Buy volume in USD in the last 24 hours | | sellVolume24hUSD | Float64 | Sell volume in USD in the last 24 hours | | holderCount | UInt64 | Total number of token holders | ## Examples ### 1. Fetch details for multiple well-known tokens Get details for SOL (wrapped native token) and Bonk in a single request by passing their comma-separated mint addresses. ```bash curl -X GET "https://api.cambrian.org/solana/token-details-multi?token_addresses=So11111111111111111111111111111111111111112%2CDezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "name", "type": "String" }, { "name": "decimals", "type": "UInt8" }, { "name": "priceUSD", "type": "Float64" }, { "name": "lastTradeUnixTime", "type": "UInt32" }, { "name": "lastTradeHumanTime", "type": "String" }, { "name": "trade1hCount", "type": "UInt64" }, { "name": "trade24hCount", "type": "UInt64" }, { "name": "trade7dCount", "type": "UInt64" }, { "name": "volume1h", "type": "Float64" }, { "name": "volume24h", "type": "Float64" }, { "name": "volume7d", "type": "Float64" }, { "name": "volume1hUSD", "type": "Float64" }, { "name": "volume24hUSD", "type": "Float64" }, { "name": "volume7dUSD", "type": "Float64" }, { "name": "buy24hCount", "type": "UInt64" }, { "name": "sell24hCount", "type": "UInt64" }, { "name": "buyVolume24h", "type": "Float64" }, { "name": "sellVolume24h", "type": "Float64" }, { "name": "buyVolume24hUSD", "type": "Float64" }, { "name": "sellVolume24hUSD", "type": "Float64" }, { "name": "holderCount", "type": "UInt64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 74.00676590925579, 1785945415, "2026-08-05 15:56:55", 1093034, 23826521, 147985950, 4429122.400240805, 93032561.4433486, 510949224.80290234, 327785024.6580624, 6885038996.676356, 37813699671.504105, 9559168, 14267353, 46330616.84688268, 46701944.59646592, 3428779115.418669, 3456259881.257687, 9792518 ], [ "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", "Bonk", "Bonk", 5, 2.7855047656462087e-06, 1785945412, "2026-08-05 15:56:52", 359, 7870, 63074, 1468809952.5160499, 45186071309.198135, 283381622871.66986, 4091.3771225620385, 125866.01697260083, 789360.8610055931, 3687, 4183, 22313864735.79276, 22872206573.40538, 62155.37656153561, 63710.64041106523, 430549 ] ], "rows": 2 } ] ``` Note: Result collections are limited to 10 items. The response returns one row per requested token address in the columnar `columns`/`data` format. SOL is priced at ~$74.01 with ~9.8M holders, and Bonk trades at a fraction of a cent with ~430K holders; both rows include the full 1h/24h/7d trade count and volume breakdowns. ## x402 Payment Option This endpoint also supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/token-details-multi" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/token-details-multi") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Mint/Burn Transactions **Endpoint:** /api/v1/solana/token-mint-burn-transactions # Token Mint/Burn Transactions ## Overview Returns a paginated list of mint and burn transactions for a specified Solana token, including transaction details, amounts, and timing information. This forms a complete audit trail of supply changes, useful for tracking token supply dynamics and monitoring compliance. ## Business Value - **Supply Monitoring**: Track complete token supply changes through detailed mint and burn transaction history - **Compliance Auditing**: Essential for regulatory compliance monitoring and token supply verification - **Risk Assessment**: Monitor large supply changes and unusual mint/burn patterns that could indicate market risks - **Analytics Integration**: Historical supply dynamics data for trading algorithms and market analysis tools - **Forensic Analysis**: Complete transaction trail for investigating suspicious token activities and supply manipulation ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/token-mint-burn-transactions ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | String | Yes | - | SPL token mint address (base58 format, 44 characters) | | after_time | Integer | Yes | - | Unix timestamp - only return transactions after this time | | before_time | Integer | Yes | - | Unix timestamp - only return transactions before this time | | limit | Integer | No | 100 | Limit the number of results (min 1, max 1000) | | offset | Integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows (min 0, max 100000) | | order_asc | Array | No | - | List of column names to order by in ascending order divided by comma. Valid values: blockTime, blockNumber, txSignature, tokenAddress, operationType, accountCount, authority, amount, amountUI, decimals | | order_desc | Array | No | - | List of column names to order by in descending order divided by comma. Valid values: blockTime, blockNumber, txSignature, tokenAddress, operationType, accountCount, authority, amount, amountUI, decimals | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | blockTime | DateTime('UTC') | UTC timestamp when the mint/burn transaction was included in a block | | blockNumber | UInt64 | Slot/block number in which the transaction was processed | | txSignature | String | Unique transaction signature for the mint/burn event | | tokenAddress | String | SPL token mint address associated with the transaction | | operationType | String | Type of supply operation, e.g. "mint" or "burn" | | accountCount | String | Number of accounts involved in the transaction | | authority | String | Address of the authority/account that executed the mint or burn operation | | amount | UInt64 | Raw token amount minted or burned, in base units (subject to `decimals`) | | amountUI | Float64 | Human-readable token amount minted or burned, adjusted for `decimals` | | decimals | UInt8 | Number of decimal places used by the token | ## Examples ### 1. Retrieve Mint/Burn Transactions for USDC in a Time Window This example retrieves mint and burn transactions for the USDC token within a specific one-hour time window, limited to 10 results. ```bash curl -X GET "https://api.cambrian.org/solana/token-mint-burn-transactions?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&after_time=1752503691&before_time=1752523691&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "blockTime", "type": "DateTime('UTC')" }, { "name": "blockNumber", "type": "UInt64" }, { "name": "txSignature", "type": "String" }, { "name": "tokenAddress", "type": "String" }, { "name": "operationType", "type": "String" }, { "name": "accountCount", "type": "String" }, { "name": "authority", "type": "String" }, { "name": "amount", "type": "UInt64" }, { "name": "amountUI", "type": "Float64" }, { "name": "decimals", "type": "UInt8" } ], "data": [ [ "2025-07-14T14:34:59+00:00", 353264343, "uSJYnGUrqs1hkXgeFm2CvTtrMmXwkLwjJxF5LGrAhDEtaew32vadRySwEqJynK6ZoPidVFc7SV54Zpqz3Ny7zeE", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "G2EmAqgVr7yvBm8MXxnZZLSwWfAcQeeUW1d12CnAhsdx", "38Rw1AW2aMJDgQbkxVFdm18U8LnEvNaiNinxcsk7z6cj", 522359340, 522.35934, 6 ], [ "2025-07-14T14:35:15+00:00", 353264381, "Apu8eEiAgi98M6MupgvkiHdATTKhF317byqQuKtXoKHtux2XkWmdvDUpKEVRPDyWFWrXb8xGNCNv6oHLpBBMRQk", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "6Yiwy4f8pRpuqbwm2XaSaK6zTzBMo1tWRvXZ5cvFh2tj", "2gSY8UsB2Sii5pD7tjjkcHL3EjgjK65RP4BR66Ftc1wu", 8768981344, 8768.981344, 6 ], [ "2025-07-14T14:36:14+00:00", 353264528, "3uEzBudzKb5DcdP4q8g2BSfE1to1TCWNPeEMwosypspBTkS9deecvkz5RFeoGHRLBZsXfPcD9qutEEQSLvY3BGAJ", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "HgzwqJvhAbPk1UhLbNkDZHi59oHAN5zFPpDfnWjLKLak", "nzwcFGkUHTbASA3X6nWzXyheHTmYyL3PnmevoGh9bcP", 11134485, 11.134485, 6 ], [ "2025-07-14T14:36:17+00:00", 353264535, "2dVQYYEo4EUaAYNGb4CquUkhZc5isRY3sC8aNc4zxC5ToT7dHj5badS78fJAUQT2t1cQA5VPen8Tx4qvnLvx7BNZ", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "DKHzBbP5LicH5W9zwXJZX3E2pdyHkrYJwuTfDFEcZG2T", "D8rBNTAUgkkAgguj8QtmEJAW1eFda33kKfuNzvcoopVi", 110986701, 110.986701, 6 ], [ "2025-07-14T14:37:34+00:00", 353264723, "4TRGmGwJpNSEwe7So8RMFFonTDgiKrZoqQbeXFZ7Hn4kn1kL55qfj3YUJNvmnXeR8oSRqCafeP5SeXBLbS9aSzNB", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "6JBicoNmFdrNDRPYZnnCEnXEBmchKvR4XLDtVQaR164T", "4WbeDhRxyj9m8Uh7GZSNpW7DFh989oTFguTE4c2A2cgK", 1, 1e-06, 6 ], [ "2025-07-14T14:39:05+00:00", 353264952, "1EK1th3K41PUGdRfFP5LHWnHTwVzTzVMgEcHYuHrKeC9CUwqiu9jAW8xFe4S6wdbD8myKdfiMaRjdbYr2jW8t5J", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "FqYHBxHCVy1BhzuCcbPq4aSFDJo6XdvP76VYgcfSmKrZ", "JD1BuUeiQ35pqSxKEiLtmqgkGfdL7kq2XDf6bEN1R1v4", 572858586, 572.858586, 6 ], [ "2025-07-14T14:39:34+00:00", 353265023, "srs7YqbQVTz78Nj9mDtQmVm4ikYsphhgRWbWVN8TJZTGgDV5tAXnH3mNJWDEwWfiCf4ErGqA9najNJhFAbq46dq", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "DYU4yerNMB48M8vJPGCgdhduosocF6HgYFtHfVrGJ9wt", "2snHHreXbpJ7UwZxPe37gnUNf7Wx7wv6UKDSR2JckKuS", 451329357600, 451329.3576, 6 ], [ "2025-07-14T14:40:12+00:00", 353265120, "4kBFJMFEG6xK7Ji2RThJdbPGab8KxZFYez8x5AqtcNyrgtxtpg3TmQWH7xFXZvuLcfYQSXAmBnYcdAXiKszEchm4", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "7nBZHDNz5mAqsBaYnpzsbsgtSvdefpkXq7hCw2AzDceN", "FrhNiJb697chBwP3ySECeijsf3faapYsS12Da5TzC7hd", 97783555, 97.783555, 6 ], [ "2025-07-14T14:41:04+00:00", 353265254, "28djtRAybJY8y8Rf8EAe7kpnidoPJiF9LQ1G5SKS1Y5brEz3RfFKodwMMej7FkXBskd9CYyD8eZQ7JHAWXV2LaXK", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "EcyGApQmu2YxgzB5jA2EEvHJdiMowLTXdzwovS7MX7TE", "5q542QD1JyMWn42t6LvCiXb4AFpgwYvVsANaVVUJGAcT", 25543491, 25.543491, 6 ], [ "2025-07-14T14:41:13+00:00", 353265279, "3zwDyJNkWLerbNrPnycoN4unBXbUbp9Aa79cnFFpJKaQVsSKmB9sgB7VGzPHBiq6EdZWgBky3LaQYUmM3ydfMyhL", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "burn", "3eCWgBZxs5Htu3Gb4J1AdmvrCod3eVdyK2aAcUhnrWPq", "3iuczpPuaNezWEhgaYJne9b1qVbAw2dM2jAryVUqVioM", 363046733, 363.046733, 6 ] ], "rows": 10 } ] ``` Note: Result collections are limited to 10 items. In this example, all 10 transactions returned for USDC in the one-hour window are "burn" operations. Each one shows the executing authority, the raw and UI-formatted amounts, and the block-level timing. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/token-mint-burn-transactions" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/token-mint-burn-transactions") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK automatically handles steps 2 through 5. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Pool Search **Endpoint:** /api/v1/solana/token-pool-search # Token Pool Search ## Overview The Token Pool Search endpoint finds all liquidity pools containing a specific Solana token and returns trading statistics for each pool, including 24-hour volume, trade counts, and buy/sell breakdowns. It helps identify the most active trading venues for a given token across Solana DEXs. ## Business Value - **Pool Discovery**: Quickly find all liquidity pools where a specific token is tradeable - **Volume Analysis**: Compare 24-hour trading volumes across different DEXes and pool pairs - **Trading Insights**: Access buy/sell ratio data to understand market sentiment for each pool - **DEX Comparison**: Identify which decentralized exchanges have the most active pools for a token - **Liquidity Mapping**: Understand the full trading landscape for any SPL token across the Solana ecosystem ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/token-pool-search ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | Token contract address (base58 format) to search pools for | | limit | integer | No | 20 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | Token contract address (base58 format) | | tokenSymbol | String | Symbol of the queried token | | tokenName | String | Full name of the queried token | | tokenDecimals | UInt8 | Number of decimal places for the token | | tokenPrice | Float64 | Current USD price of the token | | poolAddress | FixedString(44) | Address of the liquidity pool | | poolDex | String | DEX where the pool is hosted (e.g., pump_amm) | | poolPairToken | String | Symbol of the paired token in the pool | | volume24hUSD | Float64 | 24-hour trading volume in USD for the pool | | volume24hToken | Float64 | 24-hour trading volume denominated in the token | | trades24hCount | UInt64 | Total number of trades in the pool over the last 24 hours | | buys24hCount | UInt64 | Number of buy trades in the pool over the last 24 hours | | sells24hCount | UInt64 | Number of sell trades in the pool over the last 24 hours | ## Examples ### 1. Find Top Pools for Wrapped SOL This example searches for pools containing Wrapped SOL and limits the results to the top 10, the most active trading venues for the token. ```bash curl -X GET "https://api.cambrian.org/solana/token-pool-search?token_address=So11111111111111111111111111111111111111112&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "tokenSymbol", "type": "String" }, { "name": "tokenName", "type": "String" }, { "name": "tokenDecimals", "type": "UInt8" }, { "name": "tokenPrice", "type": "Float64" }, { "name": "poolAddress", "type": "FixedString(44)" }, { "name": "poolDex", "type": "String" }, { "name": "poolPairToken", "type": "String" }, { "name": "volume24hUSD", "type": "Float64" }, { "name": "volume24hToken", "type": "Float64" }, { "name": "trades24hCount", "type": "UInt64" }, { "name": "buys24hCount", "type": "UInt64" }, { "name": "sells24hCount", "type": "UInt64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "YQwP3x59QT7HqA5TtjCmFhat5mxFBuUADnoXMUg9js8", "pump_amm", "NVDA", 141883505.81124693, 1920889.5645437944, 297245, 211300, 85945 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "6L3RTvmp1fZ3HVmQDHziF7WfRc2P1vCqy6biVPHDbffB", "pump_amm", "INTC", 140638424.35520402, 1904033.0316984504, 243623, 144463, 99160 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "CqPPZvtJJB7snvg5jURHVa2zYawT5Vd5MgZrBreyt7jM", "pump_amm", "NVDIA", 107801096.57037222, 1459464.9340275275, 161258, 91473, 69785 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "4gJbD9my9KErCd6F6hMfQbHgKR4SCJxUWC7sC7EEbULM", "pump_amm", "Monkey", 104502931.91113743, 1414812.7382712464, 108445, 54218, 54227 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "D7kjFM8eyernyL9YNkJujJKjM2GeMJuxxDbdVLQpg7iy", "pump_amm", "NVDA", 80218524.26880476, 1086038.333138196, 165115, 117456, 47659 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "7HdXDSP8iYoN6nYU3rAMu6pcQaZYP6mDrQrkXx3yRuXQ", "pump_amm", "Anthropic", 79366527.61225885, 1074503.578078207, 127633, 76591, 51042 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "Bkm5aYu8HQouqme6X4GrwuRYXpTWXb8mBQzfhzgunnKj", "pump_amm", "AIW3", 78102066.091259, 1057384.6682615366, 102963, 53722, 49241 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "EoF1WjKcfwfJ4jFEs8DkuYf5ptwH79djxy93je7yAi86", "pump_amm", "HOOD", 77281758.14204863, 1046278.9307035237, 121280, 71133, 50147 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "5gCQurcLXbhf6eV4uGXWjWawoxFysHx3zccQbBvxWDhW", "pump_amm", "HOOD", 69079234.27246518, 935229.077417792, 180565, 131313, 49252 ], [ "So11111111111111111111111111111111111111112", "SOL", "Wrapped SOL", 9, 73.86343724811887, "FtBED1WfuP8V4HUHCefbsMF7cDFErFXbUGJZ4JRGzwGx", "pump_amm", "CATE", 63121689.277874194, 854572.8662184856, 82399, 44332, 38067 ] ], "rows": 10 } ] ``` Note: Result collections are limited to 10 items. The response shows the top 10 pools by 24h volume for Wrapped SOL, all currently on the pump_amm DEX. The top pool, paired with NVDA, recorded over $141M in 24h USD volume and nearly 300,000 trades. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/token-pool-search" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/token-pool-search") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: List Tokens **Endpoint:** /api/v1/solana/tokens # List Solana Tokens ## Overview Returns a paginated list of known tokens on the Solana chain, including each token's program ID (mint address), symbol, name, and decimal precision. Use `limit` and `offset` to page through the full token registry. ## Business Value - **Token Discovery**: Access a comprehensive database of Solana tokens for portfolio tracking, DeFi applications, and market analysis - **Integration Support**: Standardized token metadata enables seamless integration with wallets, DEXs, and trading platforms - **Data Reliability**: Curated token list ensures accurate symbol and decimal information for financial calculations - **Scalable Access**: Pagination support allows efficient handling of large token datasets without performance impact - **Real-time Updates**: Access to the latest token additions and metadata changes in the Solana ecosystem ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/tokens ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | limit | integer | No | 100 | Limit the number of results. (min: 1, max: 1000) | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. (min: 0, max: 100000) | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | programId | String | The token's program ID (mint address) on Solana | | symbol | String | The token's ticker symbol | | name | String | The token's full name | | decimals | UInt8 | Number of decimal places used to convert raw token amounts to display values | ## Examples ### 1. List Solana Tokens Retrieve a page of known Solana tokens, limited to 10 results. ```bash curl -X GET "https://api.cambrian.org/solana/tokens?limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "programId", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "name", "type": "String" }, { "name": "decimals", "type": "UInt8" } ], "data": [ [ "111pZmnFrX5G9jidWUg1icALt8PxkRGt19nV9ywrTd", "RPOW", "RPOW", 6 ], [ "117wSs4gNY39i8q5AqCFozrzCEhDxvSa2Hi7vBbofaQ", "emilio", "emilio", 6 ], [ "11BMjvM2tzoP4Ww4G5TMTa8oR4kCSMjvQ74XXfXuHtx", "ANSEM", "The Black Bull", 6 ], [ "11FUarnYkUCkM4AXJvnmnnGzW2VBEDHrrNrBuZr7yBE", "$FRC", "Flamingo Revolution", 6 ], [ "11K8eZYt5KR282ZkK2c8bB4ZHFfqtbY6muqHMvLEASY", "YEILDCASH", "yeildcash", 6 ], [ "11T6GBCzs429acLCrBGk2FTsJd74mjiHeDkgCd4ryZh", "W26", "WORLD CUP 2026", 6 ], [ "11pys8LJLJoeMfhvBMbEFFkwEwj5B87G8k3gA6PEASY", "VARSKO", "Varsko Intelligent ", 6 ], [ "11shjygYRN8tVcXNGCFepSXBT9aVXwvXj97ySf1bory", "NGG", "NinjaGuild", 6 ], [ "1215hKyD1K8apJcpmndXyQDfR4UoqQtUtmfJJxGirXPX", "BIRDS", "Birds for some Reason", 9 ], [ "121UCZVRpK3DrLryx4eEE37YoiCJanyZt7hwgRPCBAGS", "TAXFREE", "Taxfree coin", 9 ] ], "rows": 10 } ] ``` Note: result collections are limited to 10 items in this example. The response returns a columnar table: `columns` describes each field's name and type, and each inner array in `data` represents one token row in the same column order. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/tokens" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/tokens") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Holders Distribution **Endpoint:** /api/v1/solana/tokens/holder-distribution-over-time # Solana Token Holder Distribution Over Time ## Overview Returns the distribution of a Solana token's holders over a specified block range, sampled at a given block interval and grouped into USD value tiers. Use it to track how holder concentration and value distribution change as the token's on-chain activity unfolds. ## Business Value - **Portfolio Analysis**: Track how token distribution changes across different holder value tiers over time - **Market Insights**: Understand concentration and democratization trends in token ownership - **Risk Assessment**: Identify periods of wealth concentration or distribution that may impact market stability - **Investment Research**: Analyze holder behavior patterns to inform strategic decisions - **Compliance Monitoring**: Track large holder movements for regulatory and risk management purposes ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/tokens/holder-distribution-over-time ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | Token mint address (program id) | | interval | integer | Yes | - | Block interval to use | | start_block | integer | Yes | - | Block to start from | | end_block | integer | Yes | - | Block to end at | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | blockNumber | UInt64 | Block number of the sampled snapshot | | blockTime | DateTime('UTC') | UTC timestamp corresponding to the block | | minAmountUSD | Nullable(UInt32) | Lower bound (inclusive) of the USD value tier | | maxAmountUSD | Nullable(UInt32) | Upper bound (exclusive) of the USD value tier; null indicates no upper bound | | totalHeldUSD | Float64 | Total USD value held by all holders within this tier at this block | | holderCount | UInt64 | Number of holders within this USD value tier at this block | ## Examples ### 1. Retrieve Holder Distribution Over a Block Range This example fetches the holder distribution for a token across a 1,000,000 block range, sampled every 500,000 blocks, grouped by USD value tiers. ```bash curl -X GET "https://api.cambrian.org/solana/tokens/holder-distribution-over-time?token_address=HeLp6NuQkmYB4pYWo2zYs22mESHXPQYzXbB8n4V98jwC&interval=500000&start_block=340000000&end_block=341000000" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "blockNumber", "type": "UInt64" }, { "name": "blockTime", "type": "DateTime('UTC')" }, { "name": "minAmountUSD", "type": "Nullable(UInt32)" }, { "name": "maxAmountUSD", "type": "Nullable(UInt32)" }, { "name": "totalHeldUSD", "type": "Float64" }, { "name": "holderCount", "type": "UInt64" } ], "data": [ [ 340000000, "2025-05-14T16:53:13+00:00", 0, 100, 64672.01377046308, 6380 ], [ 340000000, "2025-05-14T16:53:13+00:00", 100, 1000, 620681.6522664049, 1689 ], [ 340000000, "2025-05-14T16:53:13+00:00", 1000, 10000, 2751297.04059455, 891 ], [ 340000000, "2025-05-14T16:53:13+00:00", 10000, 100000, 7071390.425242035, 247 ], [ 340000000, "2025-05-14T16:53:13+00:00", 100000, 1000000, 13759394.531400206, 51 ], [ 340000000, "2025-05-14T16:53:13+00:00", 1000000, null, 36312518.00213441, 4 ], [ 340500000, "2025-05-16T23:53:03+00:00", 0, 100, 3915.4879536763506, 342 ], [ 340500000, "2025-05-16T23:53:03+00:00", 100, 1000, 30717.89440404316, 88 ], [ 340500000, "2025-05-16T23:53:03+00:00", 1000, 10000, 143098.24544360803, 44 ], [ 340500000, "2025-05-16T23:53:03+00:00", 10000, 100000, 221563.2437320579, 10 ] ], "rows": 16 } ] ``` Note: result collections are limited to 10 items. This response shows two block snapshots (340000000 and 340500000), each broken into USD value tiers with the total USD held and holder count per tier. At block 340000000, the top tier (holders with over $1,000,000) had only 4 holders but collectively held over $36M; a small number of large holders accounted for most of the value. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/tokens/holder-distribution-over-time" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/tokens/holder-distribution-over-time") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - /solana/tokens - Returns a paginated list of known tokens for the Solana chain. - /solana/tokens/holders - Returns a list of accounts currently holding a specific Solana token, sorted by their current balance (descending). - /solana/tokens/holders-over-time - Returns a list of accounts holding a specific token on Solana, providing snapshots at specified block intervals within a given range. - /solana/tokens/security - Provides comprehensive security analysis for a token on Solana, including ownership concentration and holder distribution. --- ## Cambrian API: Token Holders by Program ID **Endpoint:** /api/v1/solana/tokens/holders # Token Holders by Program ID ## Overview Returns a list of accounts currently holding a specific Solana token (identified by its program ID/mint address), sorted by their current balance in descending order. This endpoint uses pre-aggregated data for fast, efficient holder lookups. ## Business Value - **Portfolio Analysis**: Track token distribution across holders to understand concentration and diversification patterns - **Community Insights**: Identify large holders and community distribution for token governance and ecosystem health - **Risk Assessment**: Monitor holder concentration to assess potential liquidity and market manipulation risks - **Market Research**: Analyze token adoption patterns and holder behavior for investment and partnership decisions - **Compliance Monitoring**: Track token distribution for regulatory reporting and AML compliance requirements ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/tokens/holders ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | program_id | string | Yes | - | The program ID (mint address) of the token. | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | account | FixedString(44) | The Solana account address holding the token. | | balanceRaw | UInt64 | The raw token balance, in the token's smallest unit (before applying decimals). | | balanceUi | Float64 | The human-readable token balance, adjusted for token decimals. | | balanceUSD | Float64 | The current USD value of the held balance. | ## Examples ### 1. Top Holders of the ORCA Token This example retrieves the top 10 holders of the ORCA token by current balance, useful for quickly assessing holder concentration. ```bash curl -X GET "https://api.cambrian.org/solana/tokens/holders?program_id=orcaEKTdK7LKz57vaAYr9QeNsVEPfiu6QeMU1kektZE&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "account", "type": "FixedString(44)" }, { "name": "balanceRaw", "type": "UInt64" }, { "name": "balanceUi", "type": "Float64" }, { "name": "balanceUSD", "type": "Float64" } ], "data": [ [ "5ooCx5vKiV2ZxAEKNNHAJjAJ7BARfLUZPGvgiApZjgFD", 14200768337139, 14200768.337139, 15015018.540679738 ], [ "Ce5j11WAsSzM3nkzrw4Kw6v6ic3nbyqpv5eywjYKeKc5", 9279147186819, 9279147.186819, 9811199.207257356 ], [ "3YzoJK4pS8Urmd6PZtj16BMBVtc8eepk3MLs6LYtrArV", 8350646724836, 8350646.724836, 8829459.95761101 ], [ "BwzWKw33iBQin9E8HwFgevCeMByioZCvoZFk7uN433ft", 6027328553947, 6027328.553947, 6372926.298050964 ], [ "3qPbC7P9baPCXxz2Duqk2Qmbj21ap8pRRbRY8sfobKje", 4078280040240, 4078280.04024, 4312122.341869334 ], [ "2NUxDnrNAUuPAmzHoCS2pFsRt9u5gFhdJTAHyfhj9mwp", 3293703343107, 3293703.343107, 3482559.224271808 ], [ "6wfrMMr9BAuEXHK7u93vxTDnzWJfHSURXJeN5HYFhkKi", 3000000010001, 3000000.010001, 3172015.3940120926 ], [ "AxNLCnLxauG6gEoi5aq6efZXSdwbWmtW39YWW3ARtvoh", 2062018344538, 2062018.344538, 2180251.303268391 ], [ "5WkQBvLSvHPR2MVd3P8oPvMg7rFpvr34MgBFU6J14dkd", 1823728142681, 1823728.142681, 1928297.907930769 ], [ "5oL1EyZEMJT1PjACWgTu1P3zhg62iEqmySVb6JWtf9iL", 1777694420093, 1777694.420093, 1879624.6825287566 ] ], "rows": 10 } ] ``` Note: Result collections are limited to 10 items in this example. The response shows the top 10 ORCA holders. The top account alone holds over 14.2M tokens (~$15M USD), and the top few wallets hold a substantial share of supply. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/tokens/holders" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/tokens/holders") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 to 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Holders Over Time **Endpoint:** /api/v1/solana/tokens/holders-over-time # Token Holders Over Time ## Overview Returns a list of accounts holding a specific token (identified by its program ID/mint address) on Solana. It returns snapshots at specified block intervals within a given range: the first block returns the full list of holders, while subsequent blocks only return holders whose balance changed during that interval. Results are sorted by block number (ascending) and then balance (descending) within each block. ## Business Value - **Portfolio Tracking**: Monitor token distribution patterns and concentration levels over time - **Historical Analysis**: Analyze token holder behavior and balance changes for research and investment decisions - **Liquidity Assessment**: Understand how token ownership has evolved to assess market dynamics - **Risk Management**: Track large holder movements and concentration risks for better portfolio management - **Market Intelligence**: Gain insights into token adoption and distribution patterns for competitive analysis ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/tokens/holders-over-time ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | The program ID (mint address) of the token. | | interval | integer | Yes | - | Block interval for sampling balances. | | start_block | integer | Yes | - | Starting block number for the time range. | | end_block | integer | Yes | - | Ending block number for the time range. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | blockNumber | UInt64 | Block number at which this holder balance snapshot was recorded. | | blockTime | DateTime('UTC') | UTC timestamp corresponding to blockNumber. | | account | FixedString(44) | Solana account address holding the token. | | balanceUi | Float64 | Human-readable token balance, adjusted for the token's decimals. | | balanceRaw | UInt64 | Raw token balance in the smallest base unit (unadjusted for decimals). | ## Examples ### 1. Snapshot Token Holders Over a Block Range Fetch holder balance snapshots for a specific SPL token across a 200,000-block range, sampled every 100,000 blocks. ```bash curl -X GET "https://api.cambrian.org/solana/tokens/holders-over-time?token_address=27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4&interval=100000&start_block=395800000&end_block=396000000" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "blockNumber", "type": "UInt64" }, { "name": "blockTime", "type": "DateTime('UTC')" }, { "name": "account", "type": "FixedString(44)" }, { "name": "balanceUi", "type": "Float64" }, { "name": "balanceRaw", "type": "UInt64" } ], "data": [ [ 395900000, "2026-01-25T19:42:16+00:00", "AgnTi2m37HvVqNbcEzWmooxfRFAVKTo9QZ6NHvJjitew", 49639.912345, 49639912345 ], [ 395900000, "2026-01-25T19:42:16+00:00", "mVpNmozxcJxpEtSrjcpuREqFkcVVdqGXg4GdJpHvRVp", 3606.174917, 3606174917 ], [ 395900000, "2026-01-25T19:42:16+00:00", "7beNLayHpdpqNsHhxWnzCkHoN9ASTcMHZoA6yVgkKMSo", 403.502152, 403502152 ], [ 395900000, "2026-01-25T19:42:16+00:00", "AqD36cHuHeGzNK3AKnn9Sy1uKfRkgs94BG29c5aR5fQ", 125.544764, 125544764 ], [ 395900000, "2026-01-25T19:42:16+00:00", "8b56iWZqVk15KjcDmcQctUBauHZ5kdhYHXBDxdGqvTn4", 110.984518, 110984518 ], [ 395900000, "2026-01-25T19:42:16+00:00", "6wh6ymEMEHhx8WmS4LH2RHJM7xGQtN7YZBFQmxpSny7c", 49.218273, 49218273 ], [ 395900000, "2026-01-25T19:42:16+00:00", "BoEz8VsJtvywEedFYpAveLFRS31i4gBzyB9NPsndgS99", 45.241709, 45241709 ], [ 395900000, "2026-01-25T19:42:16+00:00", "3xvGv3B8MDbN2hBX25NWSyfTKJTjLoULZU21A42wF2Z7", 17.774227, 17774227 ], [ 395900000, "2026-01-25T19:42:16+00:00", "FiDAd4pi6jN47QTHdbsaYzBCJwUikYiYSm2LZFXpD3u9", 10.296345, 10296345 ], [ 395900000, "2026-01-25T19:42:16+00:00", "CGJKkJe1UdBxfnHRES65zuNhEeM9aFnXh1gJG8RZegLE", 2.680754, 2680754 ] ], "rows": 338 } ] ``` Result collections are limited to 10 items per response. The `rows` field (338) reflects the total number of matching holder-snapshot records for the requested block range, while `data` contains only the first 10, all from block 395900000 sorted by balance descending. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/tokens/holders-over-time" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/tokens/holders-over-time") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2-5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Security Metrics **Endpoint:** /api/v1/solana/tokens/security # Token Security Metrics ## Overview Provides security analysis for a token on Solana, covering ownership concentration, holder distribution, and transaction metrics. The endpoint combines holder concentration ratios, balance distribution statistics, transaction activity, and price volatility into a single composite security score. ## Business Value - **Risk Assessment**: Evaluate token security risks before investing or integrating with DeFi protocols - **Due Diligence**: Comprehensive metrics for institutional analysis and compliance requirements - **Market Intelligence**: Understand holder concentration patterns and transaction activity levels - **Investment Protection**: Identify potential red flags like excessive whale concentration or unusual trading patterns - **Portfolio Management**: Monitor security metrics for existing token holdings ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/tokens/security ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | The token address to analyze | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | address | String | The token's mint/program address | | chain | String | Blockchain network the token belongs to | | symbol | String | Token ticker symbol | | name | String | Full token name | | totalSupply | Float64 | Total supply of the token | | holderCount | UInt64 | Total number of holders | | top5HolderConcentration | Float64 | Percentage of supply held by the top 5 holders | | top10HolderConcentration | Float64 | Percentage of supply held by the top 10 holders | | top20HolderConcentration | Float64 | Percentage of supply held by the top 20 holders | | top50HolderConcentration | Float64 | Percentage of supply held by the top 50 holders | | bottom10pctBalance | Float64 | Balance held at the bottom 10th percentile of holders | | medianBalance | Float64 | Median balance across all holders | | top10pctBalance | Float64 | Balance held at the top 10th percentile of holders | | transaction1dCount | UInt64 | Number of transactions in the last 24 hours | | activeAccounts1dCount | UInt64 | Number of unique active accounts in the last 24 hours | | txUniquenessRatio | Float64 | Ratio of unique active accounts to total transactions (24h), indicating organic vs. repetitive trading | | latestTransaction | DateTime('UTC') | Timestamp of the most recent transaction | | priceVolatility30d | Float64 | Price volatility measure over the last 30 days | | priceMaxMinRatio30d | Float64 | Ratio of maximum to minimum price over the last 30 days | | priceRange30d | Float64 | Price range (max - min) over the last 30 days | | securityScore | Float64 | Composite security score derived from concentration, distribution, and activity metrics | ## Examples ### 1. Analyze Security Metrics for Wrapped SOL Retrieve comprehensive security metrics for Wrapped SOL, including holder concentration and transaction activity. ```bash curl -X GET "https://api.cambrian.org/solana/tokens/security?token_address=So11111111111111111111111111111111111111112" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "address", "type": "String" }, { "name": "chain", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "name", "type": "String" }, { "name": "totalSupply", "type": "Float64" }, { "name": "holderCount", "type": "UInt64" }, { "name": "top5HolderConcentration", "type": "Float64" }, { "name": "top10HolderConcentration", "type": "Float64" }, { "name": "top20HolderConcentration", "type": "Float64" }, { "name": "top50HolderConcentration", "type": "Float64" }, { "name": "bottom10pctBalance", "type": "Float64" }, { "name": "medianBalance", "type": "Float64" }, { "name": "top10pctBalance", "type": "Float64" }, { "name": "transaction1dCount", "type": "UInt64" }, { "name": "activeAccounts1dCount", "type": "UInt64" }, { "name": "txUniquenessRatio", "type": "Float64" }, { "name": "latestTransaction", "type": "DateTime('UTC')" }, { "name": "priceVolatility30d", "type": "Float64" }, { "name": "priceMaxMinRatio30d", "type": "Float64" }, { "name": "priceRange30d", "type": "Float64" }, { "name": "securityScore", "type": "Float64" } ], "data": [ [ "So11111111111111111111111111111111111111112", "solana", "SOL", "Wrapped SOL", 13348181.108462175, 6973676, 0.16189652639737476, 0.2142132379822427, 0.25792370503464934, 0.31370070811266915, 1e-09, 0.00014928899999999999, 0.11172613570000002, 48290409, 199543, 0.46580054851057484, "2026-08-05T14:56:38+00:00", 0.02912814651254293, 1.163993860005979, 11.673931646565606, 83.50960990149156 ] ], "rows": 1 } ] ``` Result collections are limited to 10 items. The response shows Wrapped SOL with a holder count of ~6.97M, top-5 holder concentration of ~16.2%, and a composite security score of ~83.5, figures consistent with relatively decentralized ownership and healthy transaction activity. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/tokens/security" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/tokens/security") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Transaction Feed **Endpoint:** /api/v1/solana/token-transactions # Token Transaction Feed ## Overview Retrieve a paginated list of trades and transactions for a specified Solana token address across all DEXes. You can filter results by transaction type, DEX, pool, minimum trade value, and time range to build a complete trading activity feed for any SPL token. ## Business Value - **Real-time Trading Intelligence**: Access up-to-the-minute transaction data across all major Solana DEXes to identify trading patterns and market movements - **Cross-DEX Analytics**: Monitor token activity across Meteora, Raydium CLMM, Pump.fun AMM, and Orca in a unified dataset for comprehensive market analysis - **Risk Management**: Filter transactions by minimum USD value and transaction type to focus on meaningful trades and avoid noise from micro-transactions - **Portfolio Tracking**: Track specific token transactions within defined time periods to analyze trading performance and market timing - **Arbitrage Opportunities**: Identify price discrepancies and trading volumes across different DEXes to spot potential arbitrage opportunities ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/token-transactions ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | Token program address (base58-44 string). See tokens for valid addresses. | | after_time | integer | No | 1735689600 | Unix timestamp - start time for data range | | before_time | integer | No | 1735776000 | Unix timestamp - end time for data range | | days | integer | Yes | - | Number of days to look back for transactions. Default is 1 day.. | | tx_type | string | No | - | Transaction type filter: buy, sell, add_liquidity or remove_liquidity. | | dex | string | No | - | Filter by DEX: Meteora , Raydium CLMM, Pump.fun AMM or Orca | | pool_address | string | No | - | Filter trades by pool contract address | | min_value_usd | number | No | - | Minimum trade value in USD | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | transactionHash | String | Signature/hash of the transaction | | slot | UInt64 | Solana slot number in which the transaction was processed | | blockTime | UInt32 | Unix timestamp of the block containing the transaction | | transactionType | String | Type of transaction (e.g., buy, sell) | | tokenAmount | Float64 | Amount of the token involved in the transaction | | valueUSD | Float64 | USD value of the transaction | | priceUSD | Float64 | USD price per token at the time of the transaction | | dex | String | DEX where the transaction occurred | | poolAddress | String | Address of the liquidity pool involved in the transaction | | instructionIndex | UInt32 | Index of the instruction within the transaction | ## Examples ### 1. Fetch Recent Trades for a Token Retrieve the most recent trades for a specific SPL token across all DEXes over the last day, limited to 10 results. ```bash curl -X GET "https://api.cambrian.org/solana/token-transactions?token_address=So11111111111111111111111111111111111111112&days=1&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "transactionHash", "type": "String" }, { "name": "slot", "type": "UInt64" }, { "name": "blockTime", "type": "UInt32" }, { "name": "transactionType", "type": "String" }, { "name": "tokenAmount", "type": "Float64" }, { "name": "valueUSD", "type": "Float64" }, { "name": "priceUSD", "type": "Float64" }, { "name": "dex", "type": "String" }, { "name": "poolAddress", "type": "String" }, { "name": "instructionIndex", "type": "UInt32" } ], "data": [ [ "2u9onkexbhKcMt5V3qQwSpiyGBvUW4ZAbgotBHvY42Zxqb4LEsLosFrbsxNn3c7mCvxSrJdY4ydKJv8YBKoN7nvu", 437815452, 1786117235, "sell", 0.156193896, 11.54013385328043, 73.88338564319076, "Pump.fun AMM", "J6uRnFEvRc8mzcVL7aVcDPJKNLfJaAPeFDVNU1bh5zG1", 194 ], [ "4c1LCzbf7ykaFbjhpxGfsCBLbqJZDfvWnsscXtHRv4cWB5655QsT8rzdABxSNqFKQGsgLr1JWEgzQd8Mbq36i6sA", 437815452, 1786117235, "buy", 2.593251462, 191.59819783671426, 73.88338564319076, "Pump.fun AMM", "CVEtj77yETHMMZ95AWF2XtdCQ2P6XvJeG2H94m4ZNyxf", 192 ], [ "3ngy77s9YsykZtdBfM7NLV4VAbJxzwZRw8NazkqQCAD4919Tnv2f9bbMvNxU5mLHWa292YcsAQiizXLbPJxQkfSx", 437815452, 1786117235, "sell", 3, 221.6501569295723, 73.88338564319076, "Pump.fun AMM", "2d6dfWmM8E19F5JZq8Xxv76SxPbkxJpFyyEZtELsAxsr", 190 ], [ "5Dz9zdDbXMFE8k6XJss1rN2RLcaEAtuA2mDR2mvC9nyanAz2M7jQ9RL6idxYGtFzBCppAnK7RodH5Q5Q7FnTT4Ku", 437815452, 1786117235, "sell", 1.463611756, 108.13659180045562, 73.88338564319076, "Pump.fun AMM", "6HQLH59ZKi7guqDATaxjfpWsyRciM6uBUt5L6D4t55b", 188 ], [ "2fVc8jM3JrxhXziesuV71MjM2zAq8AhBLBxAJQb83Gcvpuz1537oXsWDuPqcvBjCuuoKa8fgfe2FM5XQuig83hJf", 437815452, 1786117235, "sell", 0.2475, 18.286137946689713, 73.88338564319076, "Pump.fun AMM", "Cp4Gu42oVyQWCLKupNiKTnJGerWx5kZr4YvaexH8rRPB", 186 ], [ "4ZcX5maQ7gUrF8UNGQzDYNdXoqKrHv7hKFTqJr4UnKJJZyqBhQMHWUAGU42AK28UZUUFL9XDgY6z77WCDwhfU7zi", 437815452, 1786117235, "buy", 0.113780203, 8.40646661680953, 73.88338564319076, "Pump.fun AMM", "5WUpu1GXtoHcWo3qQaGWEFoRJwZ6kgacUVfzn8x2V2Hz", 184 ], [ "2SKkjLF9HzQNr5bqGYQpG2Zo152zEDmiiMkMD3gZoDqnmgcETvxFBiWDghLbf4iTjUDnBwxKEsqoYJAe5ARFnSVB", 437815452, 1786117235, "sell", 2.3672e-05, 0.0017489675049456117, 73.88338564319076, "Pump.fun AMM", "21wp48aHAd53ADVJiEEsGdFAQUmN8Hk7j8aMXJLX9xBY", 182 ], [ "3VP7F56TBuMkPjpwUpbPsfBERg1MhTjKa7HECP2vQdVw2fP1a39et5JAVKeNw7QtKpwEDV8a22sAZ1vxEiC9rHux", 437815452, 1786117235, "buy", 9.336756018, 689.8311455342762, 73.88338564319076, "Pump.fun AMM", "Hc6Z9AFiSfWA3SmL3np35VNZNpxpgAK9aBjdjFs5Zzvo", 180 ], [ "3VP7F56TBuMkPjpwUpbPsfBERg1MhTjKa7HECP2vQdVw2fP1a39et5JAVKeNw7QtKpwEDV8a22sAZ1vxEiC9rHux", 437815452, 1786117235, "sell", 9.376357551, 692.7570408689767, 73.88338564319076, "Pump.fun AMM", "Hc6Z9AFiSfWA3SmL3np35VNZNpxpgAK9aBjdjFs5Zzvo", 178 ], [ "3uQ58uMFxLKFutqu3oWJLwyHZ9pL5w6NwauD6LjXw2Hm5kcfVaBYyUaq1noH3Rc7PBe5P6oyTzUZZJF2ksSLDAPJ", 437815452, 1786117235, "sell", 0.218506773, 16.14402017520814, 73.88338564319076, "Pump.fun AMM", "CVEtj77yETHMMZ95AWF2XtdCQ2P6XvJeG2H94m4ZNyxf", 176 ] ], "rows": 10 } ] ``` Note: result collections are limited to 10 items in this example. All 10 returned trades for Wrapped SOL occurred on Pump.fun AMM at the same price point (~$73.88) and include a mix of buy and sell transactions within the same slot. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/token-transactions" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/token-transactions") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Transaction Feed (Time Bounded) **Endpoint:** /api/v1/solana/token-transactions-time-bounded # Token Transaction Feed (Time Bounded) ## Overview Get detailed transaction data for any SPL token with precise Unix timestamp filtering for historical analysis and event-driven research. This endpoint returns individual buy/sell transactions across major Solana DEXs within a specified time window, including trade size, USD value, and pool/DEX details. ## Business Value - **Historical Analysis**: Enables precise time-bounded queries for tracking token activity during specific events or periods - **Event-Driven Research**: Perfect for analyzing token behavior around announcements, launches, or market events - **Transaction Tracking**: Comprehensive view of all buy/sell transactions with DEX information and pricing data - **Real-time Monitoring**: Track recent transaction activity with slot-level precision for up-to-the-minute insights - **Multi-DEX Coverage**: Aggregates transaction data across major Solana DEXs including Meteora, Raydium CLMM, and others ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/token-transactions-time-bounded ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | Token program address (base58-44 string). See tokens for valid addresses. | | after_time | integer | Yes | - | Unix timestamp - start time for data range | | before_time | integer | Yes | - | Unix timestamp - end time for data range | | limit | integer | No | 100 | Limit the number of results. | | offset | integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | signature | String | Transaction signature (unique identifier) for the trade | | slot | UInt64 | Solana slot number in which the transaction was processed | | txType | String | Transaction type, e.g. `buy` or `sell` | | tokenAmount | Float64 | Amount of the token traded in the transaction | | valueUSD | Float64 | USD value of the traded amount at execution time | | priceUSD | Float64 | USD price per token at the time of the transaction | | dex | String | DEX on which the transaction occurred (e.g. Meteora, Raydium CLMM) | | poolAddress | String | Address of the liquidity pool where the transaction occurred | ## Examples ### 1. Fetch Transactions Within a Fixed Time Window Retrieve transaction data for SOL within a specific Unix timestamp range, limited to 10 results. ```bash curl -X GET "https://api.cambrian.org/solana/token-transactions-time-bounded?token_address=So11111111111111111111111111111111111111112&after_time=1735689600&before_time=1735776000&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "signature", "type": "String" }, { "name": "slot", "type": "UInt64" }, { "name": "txType", "type": "String" }, { "name": "tokenAmount", "type": "Float64" }, { "name": "valueUSD", "type": "Float64" }, { "name": "priceUSD", "type": "Float64" }, { "name": "dex", "type": "String" }, { "name": "poolAddress", "type": "String" } ], "data": [ [ "4Dqa1fme5FfHC1iBJ9jUPVbRsDJ92SmSAyFP138R5ybUiX38UC9XVxB9ZKjmj7nXoo27PCc5Ew76SedE1e33cfVz", 311292616, "buy", 0.074712157, 14.489356306005309, 193.9357246238428, "Meteora", "FqW6QxWG7kDHbQgZ9pxZR5rqXYJHd7ZHwUEcCugHFmSQ" ], [ "5NY1QG3qHqr333JHWgxnPVJsqgKdyHtcvybQLkpBmhft8jXtprBgXgR3KM1fbniBGcnanV1vdyzTQnDEDYMzohBW", 311292616, "buy", 5.540280975, 1074.4584055063153, 193.9357246238428, "Meteora", "FqW6QxWG7kDHbQgZ9pxZR5rqXYJHd7ZHwUEcCugHFmSQ" ], [ "2BjnScg6rTGu3757nbPkqyM3gdr18CQHwC13foo4bTdKdqCNTrCvvNPRsqf8GYj4it45CZu3qEWzkJyUNFBHUxHq", 311292616, "sell", 11.344764636, 2200.1551503696064, 193.9357246238428, "Raydium CLMM", "EtU7GUW6ogxke9gSjRFm8akgxwyuMT4Rm1mgbkEBTi34" ], [ "2BjnScg6rTGu3757nbPkqyM3gdr18CQHwC13foo4bTdKdqCNTrCvvNPRsqf8GYj4it45CZu3qEWzkJyUNFBHUxHq", 311292616, "sell", 11.344764636, 2200.1551503696064, 193.9357246238428, "Raydium CLMM", "EtU7GUW6ogxke9gSjRFm8akgxwyuMT4Rm1mgbkEBTi34" ], [ "58vRkVdv26UFFfsyH8x6SzrrsZvHnisLppetJFqGA8hirJsKxzN6JiXLmZkH41r9Q41cpmkBszLj9VJeVxgF7HDZ", 311292616, "sell", 11.319778006, 2195.309350174648, 193.9357246238428, "Raydium CLMM", "8sN9549P3Zn6xpQRqpApN57xzkCh6sJxLwuEjcG2W4Ji" ], [ "58vRkVdv26UFFfsyH8x6SzrrsZvHnisLppetJFqGA8hirJsKxzN6JiXLmZkH41r9Q41cpmkBszLj9VJeVxgF7HDZ", 311292616, "sell", 11.319778006, 2195.309350174648, 193.9357246238428, "Raydium CLMM", "8sN9549P3Zn6xpQRqpApN57xzkCh6sJxLwuEjcG2W4Ji" ], [ "uakqqgxhd3P6YFwCoydaPYwmisBuze263ZUhrMQmhrpTyTbLxtkGCSf6pDn5R6aAa8bnEGxVFKfpfWvh8o1H89v", 311292615, "buy", 6.3539e-05, 0.012322482006874347, 193.9357246238428, "Meteora", "BAn32AF4BZ9npV6ufFKq9JR85SiokJg9VDmHH1v1ZC6f" ], [ "4bhbmYadFwcDm2KX9JuS33ZWUNF7UZqYmsngeb8JKji7vsD5uCExNaMSo48c55x5XzVbL84YY9z68JPaXPTQTLzy", 311292615, "sell", 0.117894634, 22.863981274052733, 193.9357246238428, "Meteora", "7yhzz79wnrtxZ27RrsqxtHUFH69tWeQs8U4ptUdNGtyU" ], [ "5Sv2ZpredmSBDyYgRuz43CbJgU3T9bKrg2ACJvc56ekg9qv9TqLnxSYpsayuxp4nZ5fpCwffVZZjFtVRJxfbaAeP", 311292615, "sell", 0.167196515, 32.4253772911062, 193.9357246238428, "Meteora", "CZWD8zbzFwdjv13FJcCgHg2Ytyam9H2NsXVLZMeyYFCy" ], [ "z4wKCXk1roenee5UgMMr6GSeiJZ9a7T9dMdQEZDi7Q1ayGLPuzUzoEkPeDRLTxLgBKeUqaBdAmLWh14RKMmv15X", 311292615, "sell", 0.00067343, 0.13060213503343446, 193.9357246238428, "Meteora", "BTz3nMDswq6mTBMPFzkxacRR7gqo2VR7qsR2t9cR8eR6" ] ], "rows": 10 } ] ``` Note: result collections are limited to 10 items per request via the `limit` parameter (maximum 1000). This response shows 10 SOL transactions between the specified timestamps, mixing buy and sell activity across Meteora and Raydium CLMM pools, each with its own token amount, USD value, and price. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), paying **$0.05 USDC per request** through blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/token-transactions-time-bounded" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/token-transactions-time-bounded") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Token Traders Leaderboard **Endpoint:** /api/v1/solana/traders/leaderboard # Token Traders Leaderboard ## Overview Returns a leaderboard of the top traders for a specified SPL token, ranked by trade count and buy/sell/total volume across major Solana DEXs over a recent lookback interval. Supports front-end sorting on `total_volume`, `buy_volume`, `sell_volume`, and `trade_count`. ## Business Value - **Trading Intelligence**: Identify the most active traders for any SPL token to understand market dynamics and trading patterns - **Market Analysis**: Track who's driving volume and trades for specific tokens across multiple DEX platforms - **Real-time Insights**: Get recent trading activity with configurable time intervals from 30 minutes to 24 hours - **Volume Tracking**: Separate buy and sell volume metrics provide detailed trading behavior analysis - **Performance Ranking**: Sortable columns enable flexible analysis of trader performance across multiple dimensions ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/traders/leaderboard ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_address | string | Yes | - | SPL token mint address (base58) | | interval | string | Yes | - | Lookback window for trades (SQL Interval). Enum: `24 HOUR`, `12 HOUR`, `1 HOUR`, `30 MINUTE` | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | trader | FixedString(44) | Trader's Solana wallet address | | tradeCount | UInt64 | Number of trades executed by this trader in the interval | | sellVolume | UInt128 | Total sell volume for this trader in the interval | | buyVolume | UInt128 | Total buy volume for this trader in the interval | | totalVolume | UInt128 | Combined buy and sell volume for this trader in the interval | ## Examples ### 1. Get Top Traders for USDC over 24 Hours Retrieves the trader leaderboard for USDC over the last 24 hours, ranked by activity. ```bash curl -X GET "https://api.cambrian.org/solana/traders/leaderboard?token_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&interval=24+HOUR" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "trader", "type": "FixedString(44)" }, { "name": "tradeCount", "type": "UInt64" }, { "name": "sellVolume", "type": "UInt128" }, { "name": "buyVolume", "type": "UInt128" }, { "name": "totalVolume", "type": "UInt128" } ], "data": [ [ "48Mp1KAiD8BoLEh9p1DudCuKRoPVpmkvzhygj9mAqv25", 1, 10780040, 0, 10780040 ], [ "H61ukuFZwQgCm2oMfBPkRxv8keTCr7JfXSGGZ9EnaYsz", 1, 0, 60260280, 60260280 ], [ "CZ7mTtg9rjtWz7CXSUuRU9ecjfyFekixQSn3ffHEuhZh", 1, 20580077, 0, 20580077 ], [ "Amn7NaWDsor2dvXN4pqH2h4HyuAnp1rbLtDHiyjfdWAr", 1, 5675348, 0, 5675348 ], [ "9d5H8CnxtqzfB373tcdyqdg829mLBHMe6yriKsdCVCPN", 6, 7872529, 59391009, 67263538 ], [ "77nDwqMiFmKDUhe7J6TVscvgkG68iXQYSufyvHohEW3v", 1, 0, 29402692, 29402692 ], [ "6452cmt8gS9gWMFGiBzVWjtSMmKiJ3WgsczBcqBEzthp", 1, 0, 8111709, 8111709 ], [ "GSQ3dijmF3TUAvGXffY8sfb5Gf4USAWLTKDTMUda8g6i", 1, 0, 66957, 66957 ], [ "6SyEc5vGePVXkHKx21sitsYmMHzS2GGiRqWuqY6FDwHv", 1, 24500099, 0, 24500099 ], [ "6w91mtDw46YBmHHhWmcRTNREUgLKcgmPxtC7Yz7VMyfh", 1, 0, 546500, 546500 ] ], "rows": 38553 } ] ``` Result collections are limited to 10 items. The response shows the top 10 traders (out of 38,553 total unique traders in the interval) for USDC, ranked by activity, with wallet `9d5H8CnxtqzfB373tcdyqdg829mLBHMe6yriKsdCVCPN` showing both buy and sell activity across 6 trades. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/traders/leaderboard" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/traders/leaderboard") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Trade Statistics **Endpoint:** /api/v1/solana/trade-statistics # Trade Statistics ## Overview Retrieve instant trade analytics and performance metrics for one or more Solana SPL tokens. The endpoint returns buy/sell volume breakdowns, trade counts, and USD values over a configurable timeframe, along with a buy-to-sell ratio for quick market sentiment analysis. ## Business Value - **Real-Time Analytics**: Get instant trade statistics for any Solana token with up-to-date buy/sell volume data - **Market Insights**: Access comprehensive metrics including trade counts, volume ratios, and USD values for informed decision-making - **Portfolio Tracking**: Monitor performance across multiple tokens with customizable timeframes from 1 hour to 30 days - **Trading Intelligence**: Leverage buy-to-sell ratios and volume breakdowns to understand market sentiment and trading patterns - **Dashboard Integration**: Perfect for building performance dashboards and market analysis tools with structured data ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/trade-statistics ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | token_addresses | String | Yes | - | Comma-separated token addresses (e.g., `So11111111111111111111111111111111111111112`) | | timeframe | String | Yes | - | Time interval: `1h`, `4h`, `12h`, `24h`, `7d` | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | The SPL token mint address | | timeframe | String | The requested time interval for the statistics | | buyCount | UInt64 | Number of buy trades in the timeframe | | sellCount | UInt64 | Number of sell trades in the timeframe | | totalTradeCount | UInt64 | Total number of trades (buys + sells) in the timeframe | | volumeBuy | Float64 | Buy volume denominated in the token's native units | | volumeSell | Float64 | Sell volume denominated in the token's native units | | totalVolume | Float64 | Total trade volume (buy + sell) in the token's native units | | volumeBuyUSD | Float64 | Buy volume converted to USD | | volumeSellUSD | Float64 | Sell volume converted to USD | | totalVolumeUSD | Float64 | Total trade volume (buy + sell) converted to USD | | buyToSellRatio | Nullable(Float64) | Ratio of buy volume to sell volume; values above 1 indicate net buying pressure | ## Examples ### 1. Single Token Trade Statistics (24h) Retrieve 24-hour trade statistics for Wrapped SOL to assess recent trading activity. ```bash curl -X GET "https://api.cambrian.org/solana/trade-statistics?token_addresses=So11111111111111111111111111111111111111112&timeframe=24h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "timeframe", "type": "String" }, { "name": "buyCount", "type": "UInt64" }, { "name": "sellCount", "type": "UInt64" }, { "name": "totalTradeCount", "type": "UInt64" }, { "name": "volumeBuy", "type": "Float64" }, { "name": "volumeSell", "type": "Float64" }, { "name": "totalVolume", "type": "Float64" }, { "name": "volumeBuyUSD", "type": "Float64" }, { "name": "volumeSellUSD", "type": "Float64" }, { "name": "totalVolumeUSD", "type": "Float64" }, { "name": "buyToSellRatio", "type": "Nullable(Float64)" } ], "data": [ [ "So11111111111111111111111111111111111111112", "24h", 9461678, 14059850, 23521528, 39080876.11428526, 39379760.06464342, 78460636.17892867, 2895566611.65415, 2917711416.8239617, 5813278028.478111, 0.9924 ] ], "rows": 1 } ] ``` Wrapped SOL saw roughly 23.5M total trades in the last 24 hours. The `buyToSellRatio` of 0.9924 shows sell volume slightly exceeded buy volume (~$5.8B total volume in USD). ### 2. Multi-Token Trade Statistics (1h) Compare short-term trading activity between Wrapped SOL and USDC in a single request. ```bash curl -X GET "https://api.cambrian.org/solana/trade-statistics?token_addresses=So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&timeframe=1h" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "timeframe", "type": "String" }, { "name": "buyCount", "type": "UInt64" }, { "name": "sellCount", "type": "UInt64" }, { "name": "totalTradeCount", "type": "UInt64" }, { "name": "volumeBuy", "type": "Float64" }, { "name": "volumeSell", "type": "Float64" }, { "name": "totalVolume", "type": "Float64" }, { "name": "volumeBuyUSD", "type": "Float64" }, { "name": "volumeSellUSD", "type": "Float64" }, { "name": "totalVolumeUSD", "type": "Float64" }, { "name": "buyToSellRatio", "type": "Nullable(Float64)" } ], "data": [ [ "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "1h", 10002, 10583, 20585, 3874949.065586, 3855149.96228, 7730099.027866, 3874949.065586, 3855149.96228, 7730099.027866, 1.0051 ], [ "So11111111111111111111111111111111111111112", "1h", 403707, 623668, 1027375, 1469929.681518283, 1486747.432879488, 2956677.1143977707, 108845430.57028665, 110090752.30992499, 218936182.88021165, 0.9887 ] ], "rows": 2 } ] ``` In the last hour, USDC (`buyToSellRatio` 1.0051) saw slightly more buy volume than sell volume, while Wrapped SOL (`buyToSellRatio` 0.9887) saw slightly more sell volume. Both results came back from a single request. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/trade-statistics" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/trade-statistics") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ## Related Endpoints - `/solana/token-details` - Retrieves comprehensive details about a Solana token, including price history, trade statistics, holder information, and other key metrics - `/solana/token-details-multi` - Retrieve comprehensive details for multiple Solana tokens simultaneously - `/solana/token-pool-search` - Find pools containing a specific token and retrieve comprehensive trading statistics including 24h volume, trade counts, and buy/sell ratios - `/solana/traders/leaderboard` - Leaderboard of the top traders by trade count, buy/sell/total volume for any SPL token across major Solana DEXs - `/solana/token-transactions` - Retrieve a paginated list of trades/transactions for a specified Solana token address across all DEXes --- ## Cambrian API: Tokens Trending **Endpoint:** /api/v1/solana/trending-tokens # Tokens Trending ## Overview Retrieves a list of trending Solana tokens, ordered by price change in 24h, trade volume in 24h, or current price. This endpoint helps identify tokens experiencing significant market activity across major Solana DEXs. ## Business Value - **Market Analysis**: Track trending tokens to identify emerging market opportunities and price momentum patterns - **Investment Research**: Analyze token performance metrics including 24-hour price changes and trading volumes to inform investment decisions - **Risk Management**: Monitor token volatility and trading activity to assess market risk and liquidity conditions - **Portfolio Optimization**: Identify high-performing tokens based on price appreciation and volume metrics for portfolio diversification - **Trading Strategy**: Use trending data to develop momentum-based trading strategies and identify entry/exit points ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/trending-tokens ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | order_by | string | Yes | - | Column to sort the results by. Enum: `price_change_percentage`, `volume_usd_24h`, `current_price_usd` | | limit | integer | No | 10 | Limit the number of results. Minimum 1, maximum 1000 | | offset | integer | No | 0 | Offset the results, skipping a number of rows before returning results. Minimum 0, maximum 100000 | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | tokenAddress | String | The token's program/mint address on Solana | | symbol | String | The token's ticker symbol | | currentPriceUSD | Float64 | Current price of the token in USD | | price24hAgo | Float64 | Token price in USD 24 hours ago | | priceChangePercentage | Float64 | Percentage change in price over the last 24 hours | | volume24hUSD | Float64 | Total trade volume in USD over the last 24 hours | ## Examples ### 1. Trending Tokens by Price Change Retrieve the top trending Solana tokens sorted by 24-hour price change percentage. ```bash curl -X GET "https://api.cambrian.org/solana/trending-tokens?order_by=price_change_percentage&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [ { "name": "tokenAddress", "type": "String" }, { "name": "symbol", "type": "String" }, { "name": "currentPriceUSD", "type": "Float64" }, { "name": "price24hAgo", "type": "Float64" }, { "name": "priceChangePercentage", "type": "Float64" }, { "name": "volume24hUSD", "type": "Float64" } ], "data": [ [ "7LA4wwjoXU4hAdwX1eT5ouuSsMrHq9wHQBfAyPfJK1eQ", "CLANKER", 0.00030977020995104327, 6.350242501898885e-05, 387.8084732329734, 222831.61405092085 ], [ "pumpvQHCc1kxMZ2iHZwYKYkdHHemnZQjKbnQemQUmcB", "PUMP", 2.8815529240891106e-05, 6.488801682055631e-06, 344.08090511655826, 45209.74804679812 ], [ "7ssJZGFT3twGqeYA1kvpoMWwZYvMZvrMEbjRaWgg46BL", "BUTTHOLE", 0.00406459742682072, 0.0011439312392943436, 255.31833445933745, 3094384.6383995335 ], [ "PerPsCe2SJ7Q25CN4R5TTX4fmBdmknE2hQmqCt96fHL", "PERPSPAD", 0.0008224269868897212, 0.0003096333739143196, 165.61315936094786, 40270.75731695424 ], [ "2Q3RhyE3u9qWf4ZNMebsWBkUJjCuQiYT62b15zu2LtCD", "CLAWD", 0.00010926558382160787, 4.7795907537797596e-05, 128.6086601351785, 528293.917378107 ], [ "8G4XEHtNpoDmtf9emkGFEkwHwPeCXkS5V4MpfrBJpump", "Queefcoin", 7.247218167775941e-06, 3.1773600870118674e-06, 128.0892932910085, 20404.61168746477 ], [ "Ga5ErptAQ5oHwB7G195UEq9FeJ5UNDoV9SCRCpebFeG7", "REDACTED", 0.00020724716811236447, 9.515913646529828e-05, 117.79008911870632, 70774.37743015483 ], [ "2u3ufZ5defxwPXMixvvQpSs68PDNzHTdE52t9Crspump", "BLOXWAP", 0.00037071967568893204, 0.00017726804186187184, 109.12944702000979, 118048.5331991455 ], [ "CTgiaZUK12kCcB8sosn4Nt2NZtzLgtPqDwyQyr2syATC", "BITCOIN", 0.022990489205846888, 0.011009650156737855, 108.82125116188924, 31538.14602054251 ], [ "3H7kMWRa7WfrpBGcyMpiAxkjBCc7k1pDShjQLDHJpump", "SD", 4.944444029294309e-05, 2.387929761887958e-05, 107.05986031118042, 37863.43883718179 ] ], "rows": 10 } ] ``` This example limits the result set to 10 items, showing the top 10 Solana tokens ranked by 24-hour price change percentage, with CLANKER leading at a 387.8% increase. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2), letting you pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/trending-tokens" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/trending-tokens") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 through 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- --- ## Cambrian API: Wallet Token Balance History **Endpoint:** /api/v1/solana/wallet-balance-history # Wallet Token Balance History ## Overview Returns a paginated list of balance changes for a specified Solana wallet address and token. Together, the records form a complete audit trail of portfolio changes, with transaction details, pre/post balances, and timing information for a given time range. ## Business Value - **Portfolio Tracking**: Track detailed balance changes over time for comprehensive wallet monitoring and analysis - **Compliance Monitoring**: Provide complete audit trail of all token balance changes with transaction-level detail - **Transaction Analysis**: Analyze balance impact of each transaction with before/after balance states - **Historical Analysis**: Access complete historical balance data for research and backtesting purposes - **Risk Management**: Monitor wallet activity patterns and balance fluctuations for risk assessment ## Endpoint Details **URL**: ``` https://api.cambrian.org/solana/wallet-balance-history ``` **Method**: GET **Authentication**: Required via `X-API-Key` header ## Query Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | wallet_address | String | Yes | - | Solana wallet address (base58 format, 32-44 characters) | | token_address | String | Yes | - | Filter by specific token address (base58 format) | | after_time | Integer | Yes | - | Unix timestamp - start time for data range | | before_time | Integer | Yes | - | Unix timestamp - end time for data range | | limit | Integer | No | 100 | Limit the number of results. (min 1, max 1000) | | offset | Integer | No | 0 | Offset the results, allows you to skip a number of rows before starting to return rows. (min 0, max 100000) | | order_asc | Array[String] | No | - | List of column names to order by in ascending order, comma-separated. Leave empty items to combine with descending order. Valid values: txHash, slot, blockTime, blockHumanTime, tokenAddress, tokenSymbol, tokenDecimals, preBalance, postBalance, changeAmount, uiPreBalance, uiPostBalance, uiChangeAmount | | order_desc | Array[String] | No | - | List of column names to order by in descending order, comma-separated. Leave empty items to combine with ascending order. Valid values: txHash, slot, blockTime, blockHumanTime, tokenAddress, tokenSymbol, tokenDecimals, preBalance, postBalance, changeAmount, uiPreBalance, uiPostBalance, uiChangeAmount | ## Response Field Descriptions | Response Field | Type | Description | |---------------|------|-------------| | txHash | String | Transaction hash of the balance-changing transaction | | slot | UInt64 | Solana slot number in which the transaction was processed | | blockTime | Integer | Unix timestamp of the block containing the transaction | | blockHumanTime | String | Human-readable timestamp of the block | | tokenAddress | String | Token mint address for the balance change | | tokenSymbol | String | Symbol of the token | | tokenDecimals | Integer | Number of decimals used by the token | | preBalance | UInt64 | Raw token balance immediately before the transaction | | postBalance | UInt64 | Raw token balance immediately after the transaction | | changeAmount | Int64 | Raw change in balance (postBalance - preBalance) | | uiPreBalance | Float | Human-readable (decimal-adjusted) balance before the transaction | | uiPostBalance | Float | Human-readable (decimal-adjusted) balance after the transaction | | uiChangeAmount | Float | Human-readable (decimal-adjusted) change in balance | ## Examples ### 1. Query Wallet Balance History for a Token Over a Time Range Retrieve balance change history for a specific wallet's holdings of a specific token (SOL) within a defined Unix timestamp range, limited to 10 results. ```bash curl -X GET "https://api.cambrian.org/solana/wallet-balance-history?wallet_address=DKxRinQQhKnZcfdaSnKov5v4ja95pEncjBYU8ajzVgsW&token_address=So11111111111111111111111111111111111111112&after_time=1735689600&before_time=1735776000&limit=10" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json [ { "columns": [], "data": [], "rows": 0 } ] ``` Result collections are limited to 10 items. In this case, no balance-change records were found for the specified wallet, token, and time range, so the response returns an empty column/data set with `rows: 0`. ## x402 Payment Option This endpoint supports pay-per-use access via the [x402 payment protocol](https://x402.org) (v2): pay **$0.05 USDC per request** using blockchain micropayments. No API key required. ### Quick Start (TypeScript) ```bash npm install @x402/fetch @x402/evm viem ``` ```typescript import { x402Client } from "@x402/core/client"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { wrapFetchWithPayment } from "@x402/fetch"; import { privateKeyToAccount } from "viem/accounts"; const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`); const client = new x402Client(); client.register("eip155:*", new ExactEvmScheme(signer)); const fetchWithPayment = wrapFetchWithPayment(fetch, client); const response = await fetchWithPayment( "https://x402.cambrian.org/solana/wallet-balance-history" ); const data = await response.json(); ``` ### Quick Start (Python) ```bash pip install "x402[httpx]" ``` ```python import asyncio, os from eth_account import Account from x402 import x402Client from x402.http.clients import x402HttpxClient from x402.mechanisms.evm import EthAccountSigner from x402.mechanisms.evm.exact.register import register_exact_evm_client async def main(): client = x402Client() account = Account.from_key(os.getenv("EVM_PRIVATE_KEY")) register_exact_evm_client(client, EthAccountSigner(account)) async with x402HttpxClient(client) as http: response = await http.get("https://x402.cambrian.org/solana/wallet-balance-history") print(response.json()) asyncio.run(main()) ``` ### Payment Flow 1. Send a normal request to the endpoint (no API key needed) 2. Server returns `402 Payment Required` with payment details 3. The x402 SDK automatically signs a payment authorization with your wallet 4. The SDK resubmits the request with the signed payment 5. Server verifies payment and returns the API response The x402 SDK handles steps 2 to 5 automatically. **Network**: Base (chain ID 8453) | **Currency**: USDC | **Price**: $0.05 per request --- ---