> ## 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.

# SURCHI REST API: Blockchain Analytics for Developers

> The SURCHI API provides programmatic access to token data, wallet analytics, AI contract audits, and liquidity routing across 7+ blockchains via JSON REST.

The SURCHI REST API gives you programmatic access to the full breadth of on-chain data powering the SURCHI platform — token analytics, wallet PnL, AI-driven contract audits, and DEX liquidity routing across Ethereum, BNB Chain, Solana, Polygon, Base, Avalanche, and Arbitrum. Every response is a predictable JSON envelope, making it straightforward to integrate SURCHI data into trading bots, portfolio dashboards, security tooling, and any other application that depends on reliable blockchain intelligence.

## Base URL

All API requests are made over HTTPS to the following base URL. HTTP requests are not supported.

```
https://api.surchi.xyz/v1
```

## Quick Start

Get up and running with your first API call in under two minutes.

<Steps>
  <Step title="Get your API key">
    Sign in to your account at [surchi.xyz/dashboard](https://surchi.xyz/dashboard) and navigate to **Settings → API Keys**. Click **Create New Key**, give it a name, choose its scope, and copy the key. It is shown only once — store it somewhere safe immediately.
  </Step>

  <Step title="Make your first request">
    Use the examples below to query token data for wrapped SOL on Solana. Replace `YOUR_API_KEY` with the key you just copied.

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

      ```python Python theme={null}
      import requests

      response = requests.get(
          'https://api.surchi.xyz/v1/tokens/So11111111111111111111111111111111111111112',
          params={'network': 'solana'},
          headers={'Authorization': 'Bearer YOUR_API_KEY'}
      )
      print(response.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Parse the response">
    Every successful response follows the standard envelope format described below. Read the `data` field for the payload you requested and the `meta` field for timing and context information.
  </Step>
</Steps>

## Response Envelope

Every response from the SURCHI API — success or error — uses a consistent top-level envelope. This makes it easy to write generic response-handling logic across all endpoints.

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "network": "solana",
    "latency_ms": 42
  }
}
```

| Field             | Type    | Description                                               |
| ----------------- | ------- | --------------------------------------------------------- |
| `success`         | boolean | `true` for successful responses, `false` for errors       |
| `data`            | object  | The requested payload. Shape varies by endpoint.          |
| `meta.timestamp`  | string  | ISO 8601 UTC timestamp of when the response was generated |
| `meta.network`    | string  | The network the query was resolved against                |
| `meta.latency_ms` | integer | Server-side processing time in milliseconds               |

When `success` is `false`, the envelope contains an `error` object instead of `data`. See the [Errors](/developer/api/errors) reference for the full error format and code list.

## Available Endpoints

| Endpoint Group  | Description                      |
| --------------- | -------------------------------- |
| `/v1/tokens`    | Token data, search, holders      |
| `/v1/wallets`   | Wallet analytics, PnL, portfolio |
| `/v1/contracts` | AI contract audits               |
| `/v1/liquidity` | Liquidity routing and pools      |
| `/v1/trending`  | Trending tokens feed             |
| `/v1/alerts`    | Alert management                 |
| `/v1/networks`  | Supported networks               |

## Pagination

Endpoints that return lists use **cursor-based pagination**. This approach is stable under high-frequency data updates — unlike offset-based pagination, it won't return duplicates or skip records when new items are inserted between requests.

Include the `limit` query parameter to control page size (default: `20`, maximum: `100`). When there are more results, the response `meta` object includes a `next_cursor` string. Pass that value as the `cursor` query parameter on your next request to fetch the following page. When `next_cursor` is absent or `null`, you have reached the last page.

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "next_cursor": "eyJpZCI6MTIzNH0",
    "limit": 20,
    "total": 84
  }
}
```

```bash theme={null}
# First page
curl "https://api.surchi.xyz/v1/tokens/search?q=PEPE&network=ethereum&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page using the cursor from the previous response
curl "https://api.surchi.xyz/v1/tokens/search?q=PEPE&network=ethereum&limit=20&cursor=eyJpZCI6MTIzNH0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Rate Limits

Every API key is subject to per-minute rate limits based on your plan. When you exceed your limit, the API returns HTTP `429` with a `Retry-After` header indicating how many seconds to wait before retrying.

| Plan     | Requests per Minute |
| -------- | ------------------- |
| Free     | 10                  |
| Standard | 60                  |
| Pro      | 300                 |
| Elite    | 1,000               |

The following headers are included on every response so you can monitor your consumption in real time:

| Header                  | Description                                       |
| ----------------------- | ------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per minute for your plan |
| `X-RateLimit-Remaining` | Requests remaining in the current window          |
| `X-RateLimit-Reset`     | Unix timestamp when the current window resets     |

For retry logic and rate limit handling patterns, see the [Errors](/developer/api/errors) reference. For details on plan-level security and infrastructure, see the [Security](/technology/security) page.

<Note>
  **API versioning:** The current version, `v1`, is stable. SURCHI will never introduce breaking changes within `v1`. When incompatible changes are required, they will be released under a new version prefix (e.g. `/v2/`), and `v1` will continue to be supported with advance deprecation notice.
</Note>

***

## POST /v1/alerts

Create a price or activity alert for a token or wallet. When the specified condition is met, SURCHI sends a notification to your configured webhook URL. Requires the `write:alerts` scope on your API key.

### Request Body

| Parameter     | Type   | Required | Description                                                                                                   |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `type`        | string | Yes      | Alert type: `price_above`, `price_below`, `volume_spike`, `whale_buy`, `whale_sell`                           |
| `address`     | string | Yes      | Token contract address or wallet address to monitor                                                           |
| `network`     | string | Yes      | Network identifier: `ethereum`, `bnb`, `solana`, `polygon`, `base`, `avalanche`, or `arbitrum`                |
| `threshold`   | number | Yes      | The value that triggers the alert. For price alerts, a USD amount. For `volume_spike`, a percentage increase. |
| `webhook_url` | string | Yes      | HTTPS URL that SURCHI will POST the alert payload to when triggered                                           |
| `label`       | string | No       | Optional human-readable label for this alert (e.g. `"SOL price watch"`)                                       |

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.surchi.xyz/v1/alerts" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "price_above",
      "address": "So11111111111111111111111111111111111111112",
      "network": "solana",
      "threshold": 200.00,
      "webhook_url": "https://your-app.example.com/webhooks/surchi",
      "label": "SOL $200 alert"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.surchi.xyz/v1/alerts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'price_above',
      address: 'So11111111111111111111111111111111111111112',
      network: 'solana',
      threshold: 200.00,
      webhook_url: 'https://your-app.example.com/webhooks/surchi',
      label: 'SOL $200 alert'
    })
  });
  const data = await response.json();
  console.log(data.data.alert_id); // store this to manage the alert later
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "alert_id": "alrt_9f2d3a1b4e",
    "type": "price_above",
    "address": "So11111111111111111111111111111111111111112",
    "network": "solana",
    "threshold": 200.00,
    "webhook_url": "https://your-app.example.com/webhooks/surchi",
    "label": "SOL $200 alert",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "latency_ms": 28
  }
}
```

<Note>
  For full details on the webhook payload format and event types, see the [Webhooks Overview](/developer/webhooks/overview) and [Webhook Events](/developer/webhooks/events) reference.
</Note>

***

## GET /v1/networks

Returns the complete list of blockchain networks currently supported by the SURCHI API, along with their status and supported features. Use this endpoint to programmatically discover available networks and check for any degraded services before making queries.

### Parameters

This endpoint takes no query parameters.

### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.surchi.xyz/v1/networks" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.surchi.xyz/v1/networks', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  const { data } = await response.json();
  // data is an array of supported network objects
  const activeNetworks = data.filter(n => n.status === 'operational');
  ```
</CodeGroup>

### Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "ethereum",
      "name": "Ethereum",
      "chain_id": 1,
      "native_currency": "ETH",
      "status": "operational",
      "features": ["tokens", "wallets", "contracts", "liquidity"]
    },
    {
      "id": "solana",
      "name": "Solana",
      "chain_id": null,
      "native_currency": "SOL",
      "status": "operational",
      "features": ["tokens", "wallets", "contracts", "liquidity"]
    },
    {
      "id": "bnb",
      "name": "BNB Chain",
      "chain_id": 56,
      "native_currency": "BNB",
      "status": "operational",
      "features": ["tokens", "wallets", "contracts", "liquidity"]
    },
    {
      "id": "polygon",
      "name": "Polygon",
      "chain_id": 137,
      "native_currency": "MATIC",
      "status": "operational",
      "features": ["tokens", "wallets", "contracts", "liquidity"]
    },
    {
      "id": "base",
      "name": "Base",
      "chain_id": 8453,
      "native_currency": "ETH",
      "status": "operational",
      "features": ["tokens", "wallets", "contracts", "liquidity"]
    },
    {
      "id": "avalanche",
      "name": "Avalanche",
      "chain_id": 43114,
      "native_currency": "AVAX",
      "status": "operational",
      "features": ["tokens", "wallets", "contracts", "liquidity"]
    },
    {
      "id": "arbitrum",
      "name": "Arbitrum",
      "chain_id": 42161,
      "native_currency": "ETH",
      "status": "operational",
      "features": ["tokens", "wallets", "contracts", "liquidity"]
    }
  ],
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "latency_ms": 12
  }
}
```

### Response Fields

| Field             | Type            | Description                                                             |
| ----------------- | --------------- | ----------------------------------------------------------------------- |
| `id`              | string          | Network identifier used in all other API requests                       |
| `name`            | string          | Human-readable network name                                             |
| `chain_id`        | integer \| null | EVM chain ID. `null` for non-EVM networks such as Solana                |
| `native_currency` | string          | Symbol of the network's native gas token                                |
| `status`          | string          | Current operational status: `operational`, `degraded`, or `maintenance` |
| `features`        | array           | List of SURCHI API feature groups available on this network             |

<Tip>
  Cache the `/v1/networks` response for up to 5 minutes. Network status changes infrequently, and polling this endpoint more often than necessary consumes rate limit quota. For real-time status updates, check [status.surchi.xyz](https://status.surchi.xyz).
</Tip>