> ## Documentation Index
> Fetch the complete documentation index at: https://ducs.surchi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Market Data API: Real-Time Solana DeFi Data from SURCHI

> Access real-time and historical on-chain market data for Solana tokens, DEX prices, liquidity pools, and wallet analytics via the SURCHI Market Data API.

The SURCHI Market Data API provides real-time and historical on-chain data aggregated from across the Solana DeFi ecosystem. Rather than querying individual DEX programs directly, the API normalizes data from Raydium, Orca, Meteora, and other major Solana protocols into a unified interface — giving you token prices, DEX liquidity, trading volume, and wallet portfolio analytics through a single authenticated endpoint.

## GET /v1/market/data

Fetch real-time market data for any tracked Solana token, including price, 24-hour volume, liquidity pool composition, and optional sentiment scoring.

### Query Parameters

<ParamField query="asset" type="string" required>
  The token to query. Accepts either a token symbol (e.g. `SOL`, `BONK`, `JTO`) or a full Solana mint address. Required.
</ParamField>

<ParamField query="include" type="array">
  Comma-separated list of data fields to include in the response. Available options:

  * `price` — current USD price and 24h change
  * `volume` — 24-hour trading volume in USD
  * `liquidity` — TVL and top liquidity pool breakdown
  * `sentiment` — Alpha Sentinel sentiment score for the asset

  Omitting this parameter returns all available fields.
</ParamField>

### Example Request

```bash theme={null}
curl 'https://api.surchi.io/v1/market/data?asset=SOL&include=price,volume,liquidity' \
  -H 'Authorization: Bearer {token}'
```

### Example Response

```json theme={null}
{
  "asset": "SOL",
  "price_usd": 94.23,
  "price_change_24h": 3.14,
  "volume_24h_usd": 1840000000,
  "liquidity": {
    "total_tvl_usd": 420000000,
    "top_pools": [
      {
        "dex": "Raydium",
        "pair": "SOL/USDC",
        "tvl_usd": 89000000
      },
      {
        "dex": "Orca",
        "pair": "SOL/USDC",
        "tvl_usd": 74000000
      },
      {
        "dex": "Meteora",
        "pair": "SOL/USDT",
        "tvl_usd": 31000000
      }
    ]
  },
  "updated_at": "2024-01-15T14:25:01Z"
}
```

### Response Fields

| Field                     | Type   | Description                                                                  |
| ------------------------- | ------ | ---------------------------------------------------------------------------- |
| `asset`                   | string | Token symbol as queried                                                      |
| `price_usd`               | number | Current token price in USD                                                   |
| `price_change_24h`        | number | Percentage price change over the last 24 hours                               |
| `volume_24h_usd`          | number | Aggregate trading volume across all tracked DEXes in the last 24 hours       |
| `liquidity.total_tvl_usd` | number | Total value locked across all liquidity pools for this asset                 |
| `liquidity.top_pools`     | array  | Breakdown of the highest-TVL pools including DEX name, trading pair, and TVL |
| `updated_at`              | string | ISO 8601 UTC timestamp of the last data refresh                              |

***

## GET /v1/wallet/portfolio

Query comprehensive portfolio analytics for any Solana wallet address. Returns current token holdings, estimated USD values, and summarized position data.

### Query Parameters

<ParamField query="address" type="string" required>
  The Solana wallet public key to query. Must be a valid base58-encoded Solana public key. Required.
</ParamField>

### Example Request

```bash theme={null}
curl 'https://api.surchi.io/v1/wallet/portfolio?address=7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU' \
  -H 'Authorization: Bearer {token}'
```

### Example Response

```json theme={null}
{
  "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "total_value_usd": 14823.50,
  "tokens": [
    {
      "symbol": "SOL",
      "mint": "So11111111111111111111111111111111111111112",
      "balance": 120.5,
      "price_usd": 94.23,
      "value_usd": 11354.72,
      "allocation_pct": 76.6
    },
    {
      "symbol": "JTO",
      "mint": "jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL",
      "balance": 4200,
      "price_usd": 0.83,
      "value_usd": 3468.78,
      "allocation_pct": 23.4
    }
  ],
  "last_activity": "2024-01-15T12:10:33Z",
  "updated_at": "2024-01-15T14:25:05Z"
}
```

***

## Historical Data

The SURCHI Market Data API supports historical snapshots for price, volume, and liquidity data going back to protocol launch. Access to historical data ranges depends on your API tier:

| Tier     | Historical Data Access             |
| -------- | ---------------------------------- |
| Explorer | 7 days                             |
| Sentinel | 90 days                            |
| Elite    | Full history since protocol launch |

To query historical data, append a `from` and `to` ISO 8601 timestamp to your market data request:

```bash theme={null}
curl 'https://api.surchi.io/v1/market/data?asset=SOL&from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z' \
  -H 'Authorization: Bearer {token}'
```

Historical endpoints return paginated arrays of timestamped data points. See the full API reference for pagination parameters.

<Info>
  Market data is refreshed every **5 seconds** from on-chain sources. For applications requiring sub-second price and liquidity updates, use the [WebSocket signal stream](/developers/ai-intelligence-api#websocket-live-signal-stream) which delivers data as soon as on-chain events are detected.
</Info>