SURCHI REST API: Blockchain Analytics for Developers

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.

Get your API key

Sign in to your account at 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.

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.

curl -X GET "https://api.surchi.xyz/v1/tokens/So11111111111111111111111111111111111111112?network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

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);

import requests

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

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.

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.

{
  "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 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.

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "next_cursor": "eyJpZCI6MTIzNH0",
    "limit": 20,
    "total": 84
  }
}

# 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 reference. For details on plan-level security and infrastructure, see the Security page.

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.

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

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"
  }'

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

Example Response

{
  "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
  }
}

For full details on the webhook payload format and event types, see the Webhooks Overview and Webhook Events reference.

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

curl -X GET "https://api.surchi.xyz/v1/networks" \
  -H "Authorization: Bearer YOUR_API_KEY"

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');

Example Response

{
  "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

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.

API Reference

SDK

Webhooks

SURCHI REST API: Blockchain Analytics for Developers

Base URL

Quick Start

Response Envelope

Available Endpoints

Rate Limits

POST /v1/alerts

Request Body

Example Request

Example Response

GET /v1/networks

Parameters

Example Request

Example Response

Response Fields

​Base URL

​Quick Start

​Response Envelope

​Available Endpoints

​Pagination

​Rate Limits

​POST /v1/alerts

​Request Body

​Example Request

​Example Response

​GET /v1/networks

​Parameters

​Example Request

​Example Response

​Response Fields

Base URL

Quick Start

Response Envelope

Available Endpoints

Pagination

Rate Limits

POST /v1/alerts

Request Body

Example Request

Example Response

GET /v1/networks

Parameters

Example Request

Example Response

Response Fields