Token API Endpoints: Search, Data, and Holder Analysis

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/

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

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

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

Example Response

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

curl -X GET "https://api.surchi.xyz/v1/tokens/search?q=PEPE&network=ethereum&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Example Response

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

curl -X GET "https://api.surchi.xyz/v1/tokens/0x6982508145454Ce325dDbE47a25d4ec3d2311933/holders?network=ethereum&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

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
}

Example Response

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

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

curl -X GET "https://api.surchi.xyz/v1/trending?network=solana&timeframe=1h&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Example Response

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

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.

API Reference

SDK

Webhooks

Token API Endpoints: Search, Data, and Holder Analysis

GET /v1/tokens/

Parameters

Example Request

Example Response

Response Fields

GET /v1/tokens/search

Parameters

Example Request

Example Response

GET /v1/tokens//holders

Parameters

Example Request

Example Response

Parameters

Example Request

Example Response

​GET /v1/tokens/

​Parameters

​Example Request

​Example Response

​Response Fields

​GET /v1/tokens/search

​Parameters

​Example Request

​Example Response

​GET /v1/tokens//holders

​Parameters

​Example Request

​Example Response

​GET /v1/trending

​Parameters

​Example Request

​Example Response

GET /v1/tokens/

Parameters

Example Request

Example Response

Response Fields

GET /v1/tokens/search

Parameters

Example Request

Example Response

GET /v1/tokens//holders

Parameters

Example Request

Example Response

GET /v1/trending

Parameters

Example Request

Example Response