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

# Token API Endpoints: Search, Data, and Holder Analysis

> REST API endpoints for token data including price, market cap, liquidity, 24h volume, holder lists, and risk scores across all supported networks.

The Tokens API gives you detailed on-chain and market data for any token across all seven SURCHI-supported networks. You can fetch a token by its contract address, search for tokens by name or symbol, retrieve a ranked holder list, and pull a live trending feed. All endpoints require the `read:tokens` scope on your API key.

***

## GET /v1/tokens/{address}

Retrieve full analytics for a single token by its contract address. Returns price, market cap, volume, liquidity, holder count, risk score, and metadata.

### Parameters

| Parameter | Type   | Required    | Description                                                                                    |
| --------- | ------ | ----------- | ---------------------------------------------------------------------------------------------- |
| `address` | string | Yes (path)  | The token's contract address on the target network                                             |
| `network` | string | Yes (query) | Network identifier: `ethereum`, `bnb`, `solana`, `polygon`, `base`, `avalanche`, or `arbitrum` |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.surchi.xyz/v1/tokens/So11111111111111111111111111111111111111112?network=solana" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const address = 'So11111111111111111111111111111111111111112';

  const response = await fetch(
    `https://api.surchi.xyz/v1/tokens/${address}?network=solana`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "address": "So11111111111111111111111111111111111111112",
    "network": "solana",
    "name": "Wrapped SOL",
    "symbol": "SOL",
    "decimals": 9,
    "price_usd": 185.42,
    "price_change_24h_pct": 3.17,
    "market_cap_usd": 85420000000,
    "fully_diluted_valuation_usd": 85420000000,
    "volume_24h_usd": 2340000000,
    "liquidity_usd": 450000000,
    "holder_count": 2840512,
    "risk_score": 5,
    "risk_level": "very_low",
    "logo_url": "https://assets.surchi.xyz/tokens/solana/sol.png",
    "created_at": "2020-03-16T00:00:00Z"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "network": "solana",
    "latency_ms": 38
  }
}
```

### Response Fields

| Field                         | Type    | Description                                                                |
| ----------------------------- | ------- | -------------------------------------------------------------------------- |
| `address`                     | string  | Token contract address                                                     |
| `network`                     | string  | Network the token lives on                                                 |
| `name`                        | string  | Full token name                                                            |
| `symbol`                      | string  | Token ticker symbol                                                        |
| `decimals`                    | integer | Number of decimal places                                                   |
| `price_usd`                   | number  | Current price in USD                                                       |
| `price_change_24h_pct`        | number  | 24-hour price change percentage                                            |
| `market_cap_usd`              | number  | Circulating market cap in USD                                              |
| `fully_diluted_valuation_usd` | number  | FDV based on total supply                                                  |
| `volume_24h_usd`              | number  | 24-hour trading volume in USD                                              |
| `liquidity_usd`               | number  | Total DEX liquidity in USD                                                 |
| `holder_count`                | integer | Number of unique holders                                                   |
| `risk_score`                  | integer | Risk score from 0 (safest) to 100 (highest risk)                           |
| `risk_level`                  | string  | Human-readable risk label: `very_low`, `low`, `medium`, `high`, `critical` |

***

## GET /v1/tokens/search

Search for tokens by name or symbol across one or all supported networks. Results are ordered by liquidity descending.

### Parameters

| Parameter | Type    | Required | Description                                        |
| --------- | ------- | -------- | -------------------------------------------------- |
| `q`       | string  | Yes      | Search term (name or symbol, minimum 2 characters) |
| `network` | string  | No       | Filter by network. Omit to search all networks.    |
| `limit`   | integer | No       | Results per page. Default: `20`, max: `100`        |
| `cursor`  | string  | No       | Pagination cursor from a previous response         |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.surchi.xyz/v1/tokens/search?q=PEPE&network=ethereum&limit=5" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    q: 'PEPE',
    network: 'ethereum',
    limit: '5'
  });

  const response = await fetch(
    `https://api.surchi.xyz/v1/tokens/search?${params}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );
  const data = await response.json();
  console.log(data.data); // array of matching tokens
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
      "network": "ethereum",
      "name": "Pepe",
      "symbol": "PEPE",
      "price_usd": 0.00001342,
      "market_cap_usd": 5640000000,
      "volume_24h_usd": 312000000,
      "liquidity_usd": 28500000,
      "risk_score": 42,
      "risk_level": "medium"
    }
  ],
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "next_cursor": "eyJpZCI6OTh9",
    "limit": 5,
    "total": 23
  }
}
```

***

## GET /v1/tokens/{address}/holders

Retrieve a paginated list of token holders, ordered by balance descending. Useful for whale analysis and holder concentration checks.

### Parameters

| Parameter | Type    | Required    | Description                                 |
| --------- | ------- | ----------- | ------------------------------------------- |
| `address` | string  | Yes (path)  | Token contract address                      |
| `network` | string  | Yes (query) | Network identifier                          |
| `limit`   | integer | No          | Results per page. Default: `20`, max: `100` |
| `cursor`  | string  | No          | Pagination cursor from a previous response  |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.surchi.xyz/v1/tokens/0x6982508145454Ce325dDbE47a25d4ec3d2311933/holders?network=ethereum&limit=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const address = '0x6982508145454Ce325dDbE47a25d4ec3d2311933';
  const params = new URLSearchParams({ network: 'ethereum', limit: '10' });

  const response = await fetch(
    `https://api.surchi.xyz/v1/tokens/${address}/holders?${params}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );
  const { data, meta } = await response.json();

  // Paginate if needed
  if (meta.next_cursor) {
    // fetch next page using meta.next_cursor
  }
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "address": "0xDeadDeadDeadDeadDeadDeadDeadDeadDeadDead",
      "balance_raw": "420690000000000000000000000000",
      "balance_formatted": "420690000000000",
      "percentage_of_supply": 4.21,
      "label": "Burn Address",
      "is_contract": false,
      "last_active": "2023-04-17T00:00:00Z"
    },
    {
      "rank": 2,
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "balance_raw": "320000000000000000000000000000",
      "balance_formatted": "320000000000000",
      "percentage_of_supply": 3.20,
      "label": null,
      "is_contract": true,
      "last_active": "2024-01-14T22:18:00Z"
    }
  ],
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "next_cursor": "eyJyYW5rIjoxMX0",
    "limit": 10,
    "total_holders": 2840512
  }
}
```

***

## GET /v1/trending

Retrieve the current trending tokens feed. Results are ranked by a composite score that weighs volume growth, holder growth, and social signals over the requested timeframe.

### Parameters

| Parameter   | Type    | Required | Description                                           |
| ----------- | ------- | -------- | ----------------------------------------------------- |
| `network`   | string  | No       | Filter by network. Omit to get cross-chain trending.  |
| `timeframe` | string  | No       | Trending window: `1h`, `6h`, or `24h`. Default: `24h` |
| `limit`     | integer | No       | Number of tokens to return. Default: `20`, max: `100` |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.surchi.xyz/v1/trending?network=solana&timeframe=1h&limit=5" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    network: 'solana',
    timeframe: '1h',
    limit: '5'
  });

  const response = await fetch(
    `https://api.surchi.xyz/v1/trending?${params}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );
  const data = await response.json();
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "rank": 1,
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "network": "solana",
      "name": "USD Coin",
      "symbol": "USDC",
      "price_usd": 1.0001,
      "price_change_1h_pct": 0.01,
      "volume_1h_usd": 18400000,
      "volume_change_pct": 42.3,
      "holder_growth_pct": 0.8,
      "trending_score": 98.4
    }
  ],
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "timeframe": "1h",
    "network": "solana",
    "limit": 5
  }
}
```

<Note>
  The trending feed is refreshed every 60 seconds. Polling more frequently than once per minute will not yield new results and counts against your rate limit.
</Note>