zSignals API

API Reference

Complete reference for all zSignals API endpoints. Click on any endpoint for detailed documentation and examples.

Trending & Market Data

GET /v1/market/trending

Get trending tokens sorted by volume and market activity

Example Response

{
  "rank": 1,
  "symbol": "ENJOY",
  "name": "Enjoy Token",
  "contract_address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
  "creator_handle": "enjoyer",
  "trade_count": 142,
  "volume_24h": 125000.50
}

Query Parameters

limit integer Number of results (1-100) Default: 100
offset integer Skip results for pagination Default: 0
timeframe string Time period: 1h, 24h, 7d Default: 24h
GET /v1/tokens/:id

Get detailed information for a specific token by contract address

Path Parameters

id string Required Token ID or contract address

Response

{
  "symbol": "ENJOY",
  "name": "Enjoy Token",
  "contract_address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
  "price_usd": 0.000125,
  "market_cap": 2500000,
  "volume_24h": 125000,
  "holders_count": 4521,
  "liquidity_usd": 450000,
  "change_24h": 15.3,
  "change_7d": 45.2,
  "created_at": "2024-01-10T12:00:00Z"
}
GET /v1/tokens/:id/price-history

Get historical price data for a specific token

Query Parameters

period string Time period: 1h, 4h, 24h, 7d Default: 24h
GET /v1/tokens/:id/metrics

Get detailed token metrics (supply, ATH/ATL, etc.)

Response

{
  "token": {
    "symbol": "BALAJIS",
    "name": "balajis.eth",
    "address": "0x..."
  },
  "metrics": {
    "market_cap": 4170.23,
    "total_supply": 1000000,
    "circulating_supply": 1000000,
    "holders_count": 1523,
    "volume_24h": 1250.50,
    "trades_24h": 142,
    "price_change_24h": 15.3,
    "all_time_high": 0.00825,
    "all_time_low": 0.00102
  },
  "last_updated": "2025-10-06T10:30:00Z"
}
GET /v1/tokens/:id/holders

Get holder distribution analytics from Blockscout

Query Parameters

limit integer Number of top holders (1-100) Default: 100

Response

{
  "token": {
    "symbol": "BALAJIS",
    "name": "balajis.eth",
    "address": "0x..."
  },
  "total_holders": 1523,
  "distribution": {
    "top10_concentration": 45.2,
    "top25_concentration": 62.8,
    "top50_concentration": 78.5,
    "top100_concentration": 89.2,
    "gini_coefficient": 0.85,
    "whale_count": 12,
    "whale_percentage": 0.27
  },
  "holder_types": {
    "contract_holders": 89,
    "eoa_holders": 1434
  },
  "holders": [
    {
      "address": "0x...",
      "balance": 125000,
      "percentage": 12.5
    }
  ],
  "data_source": "blockscout",
  "last_updated": "2025-10-06T10:30:00Z"
}
GET /v1/tokens/:id/swaps

Get recent swap history for a specific token

Query Parameters

limit integer Number of swaps (1-100) Default: 50

Comprehensive Data

GET /v1/all

Get all Z100 data (creators + posts) in a single comprehensive call

Query Parameters

period string Time period: 1h, 4h, 24h, 7d Default: 24h
include_changes boolean Include historical comparison data Default: true
GET /v1/tokens

Search/filter tokens by specific fields

Query Parameters

field string Required Field to search: symbol, name, address, creator
value string Required Value to match

Example

curl "https://api.zsignals.xyz/v1/tokens?field=symbol&value=BALAJIS" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET /v1/search

General search across all Z100 tokens

Query Parameters

q string Required Search query (min 2 characters)
GET /v1/market/volume

Get aggregate volume data across all tokens

Query Parameters

period string Time period: 1h, 4h, 24h, 7d Default: 24h

Discovery

GET /v1/discover/rising

Get rising/emerging tokens with strong momentum

Query Parameters

limit integer Number of results (1-50) Default: 20
GET /v1/discover/new-launches

Get recently launched tokens

Query Parameters

limit integer Number of results (1-50) Default: 20

z100 Leaderboards

GET /v1/z100/creators

Get top 100 Zora creators ranked by portfolio value and activity

LIVE EXAMPLE 
{
  "rank": 1,
  "handle": "jessepollak",
  "name": "jessepollak",
  "creator_address": "0x2211d1d0020daea8039e46cf1367962070d77da9",
  "portfolio_value": "$10.4M",
  "portfolio_value_raw": 10395910.24,
  "volume_24h": "$117.6K",
  "total_volume": "$31.5M",
  "unique_holders": 30153,
  "change_24h": "-0.7%"
}

Query Parameters

limit integer Number of results (1-100) Default: 100
sort string Sort by: value, volume, holders Default: value
GET /v1/z100/posts

Get top 100 Zora posts ranked by engagement and market metrics

LIVE EXAMPLE 
{
  "rank": 1,
  "symbol": "Base is for everyone",
  "name": "Base is for everyone",
  "creator_name": "base",
  "creator_address": "0x19ff7ea0badffa183f03533c3884f9ca03145aad",
  "market_cap": "$2.1M",
  "market_cap_raw": 2128407.14,
  "volume_24h": "$7.0K",
  "total_volume": "$120.2M",
  "unique_holders": 78986,
  "change_24h": "-3.3%"
}

Query Parameters

limit integer Number of results (1-100) Default: 100
sort string Sort by: engagement, volume, holders Default: engagement

z100 Index

GET /v1/z100/index

Get Z100 Index value and aggregate metrics (market-cap weighted, baseline 1000)

Query Parameters

period string Time period: 1h, 4h, 24h, 7d Default: 24h

Response

{
  "period": "24h",
  "index_value": 1247.53,
  "total_volume": 1247530000,
  "total_trades": 45823,
  "creator_volume": 823450000,
  "post_volume": 424080000,
  "active_creators": 100,
  "active_posts": 100,
  "top_creators": ["balajis", "wbnns", "vitalik", "punk6529", "beeple"],
  "top_posts": ["enjoy", "higher", "degen", "farther", "build"],
  "timestamp": 1696592400
}
GET /v1/z100/historical

Get historical Z100 index data

⚠️ Requires Professional or Enterprise tier

Query Parameters

from string ISO 8601 date Default: 7 days ago
to string ISO 8601 date Default: now
interval string hourly, daily, weekly Default: daily

Recent Activity

GET /v1/market/recent-swaps

Get recent swaps and trading activity across all tokens

LIVE EXAMPLE 
{
  "transaction_hash": "0xb8e1aae0a22d56b8cb7bd02963910d0369a9aeba37847bc9125820eb4aed2161",
  "pool_id": "0x1a3812473f28d4203387e8f3836d07f4215135b9c0a5cd0e304403a04c5d8f53",
  "timestamp": 1759764041,
  "token_symbol": "arbstein",
  "is_buy": false,
  "amount_in": 3.83253363799726,
  "amount_out": 3.83253363799726,
  "volume_usd": 0.34
}

Query Parameters

limit integer Number of results (1-100) Default: 50
type string Filter by: buy, sell, all Default: all
min_value decimal Minimum USD value Optional

Pagination

All list endpoints support pagination using limit and offset parameters:

# First page (items 1-20)
GET /v1/market/trending?limit=20&offset=0

# Second page (items 21-40)
GET /v1/market/trending?limit=20&offset=20

# Third page (items 41-60)
GET /v1/market/trending?limit=20&offset=40

Pagination Response Headers

Paginated responses include helpful headers:

X-Total-Count: 500
X-Page-Count: 25
X-Current-Page: 1
X-Per-Page: 20

Response Formats

Success Response

Successful requests return JSON data with HTTP status 200:

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

Error Response

Failed requests return error details with appropriate HTTP status:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested token was not found",
    "details": {
      "token": "0xinvalid"
    }
  }
}

Server-Sent Events (SSE) Streaming

Real-time swap data streaming via EventSource. Note: SSE endpoint is at the root domain, not under /api/v1.

const eventSource = new EventSource('https://zsignals.xyz/stream/swaps');

eventSource.onmessage = (event) => {
  const swap = JSON.parse(event.data);
  console.log('New swap:', swap);
};

eventSource.onerror = (error) => {
  console.error('SSE error:', error);
  eventSource.close();
};

SSE Response Format

Each swap event contains the following data:

{
  "timestamp": 1696592400,
  "tx_hash": "0xabc123...",
  "token_symbol": "BALAJIS",
  "token_address": "0x0578d8a44db98b23bf096a382e016e29a5ce0ffe",
  "is_buy": true,
  "volume_usd": 125.50,
  "amount": 30000,
  "price_per_token": 0.00418,
  "pool_address": "0x...",
  "trader": "0x..."
}

Stream Characteristics

Property Value Description
Endpoint /stream/swaps Server-Sent Events endpoint
Authentication None required Public stream for all users
Update Frequency Real-time Events sent as swaps occur
Connection Type Long-lived HTTP Automatic reconnection on disconnect