Indexer API

NestJS REST API + WebSocket server backed by PostgreSQL. Provides fast token discovery, trade history, leaderboards, and user profiles. All endpoints return JSON. All list endpoints use cursor-based pagination.

Base URL

Environment	URL
Local	http://localhost:3000/api/v1
Testnet	http://localhost:3002/api/v1
Production (via proxy)	/api/v1

Headers

Header	Required	Description
`X-Chain-Id`	Yes	Chain ID (31337, 46630, 4663). Auto-set by middleware.
`Content-Type`	For PUT/POST	application/json

Tokens

GET /tokens

List tokens with sorting and filtering.

Param	Type	Default	Description
`sort_by`	string	created	created, volume, market_cap, graduation, last_trade, trades
`sort_order`	string	desc	asc or desc
`graduated`	boolean	—	Filter by graduation status
`search`	string	—	Search name, symbol, or address
`platform_id`	string	—	Filter by platform (bytes32 hex)
`limit`	number	50	1–200
`cursor`	string	—	Pagination cursor

GET /api/v1/tokens?sort_by=volume&sort_order=desc&limit=20

{
  "chain_id": 46630,
  "network": "testnet",
  "data": [
    {
      "address": "0x...",
      "bonding_curve": "0x...",
      "name": "Pepe Coin",
      "symbol": "PEPE",
      "creator": "0x...",
      "platform_id": "0x...",
      "config_version": 1,
      "current_price_eth": "0.00000042",
      "market_cap_eth": "420.0",
      "reserve_target_eth": "10.0",
      "real_eth_reserves": "3.5",
      "tokens_sold": "350000000.0",
      "total_volume_eth": "150.0",
      "graduated": false,
      "pool_id": null,
      "lp_fee": 5000,
      "buy_count": 120,
      "sell_count": 45,
      "holder_count": 80,
      "created_at": "2026-07-12T10:00:00.000Z",
      "last_trade_at": "2026-07-12T10:05:00.000Z",
      "graduated_at": null,
      "website": "https://pepe.com",
      "twitter": "https://x.com/pepe",
      "telegram": "https://t.me/pepe",
      "discord": null,
      "curve_supply": "800000000.0",
      "trading_fee_bps": 125
    }
  ],
  "pagination": {
    "next_cursor": "eyJzb3J0...",
    "prev_cursor": null,
    "has_next": true,
    "has_prev": false,
    "limit": 20,
    "count": 20
  }
}

GET /tokens/:address

Single token by contract address.

GET /api/v1/tokens/0x3b02ff1e626ed7a8fd6ec5299e2c54e1421b626b

GET /trending

Tokens ranked by trade volume in a time window.

Param	Type	Default
`time_window`	string	24h (1h, 6h, 24h)
`limit`	number	20

GET /recent

Most recently created tokens.

Param	Type	Default
`graduated`	boolean	—
`limit`	number	20

GET /search

Search tokens by name, symbol, or address.

Param	Type	Required
`q`	string	Yes
`limit`	number	—

GET /leaderboard

Param	Type	Default
`sort_by`	string	volume (volume, market_cap, trades, graduation)
`time_window`	string	24h (1h, 6h, 24h, all)
`limit`	number	20

Trades

GET /trades/:tokenAddress

Trade history for a token (cursor-paginated).

GET /api/v1/trades/0x...?limit=50

{
  "data": [
    {
      "type": "Buy",
      "trader": "0x...",
      "eth_amount": "0.100000000000000000",
      "token_amount": "500000.000000000000000000",
      "fee_eth": "0.000125000000000000",
      "price_eth": "0.000000200000000000",
      "tx_hash": "0x...",
      "block_number": 12345,
      "timestamp": "2026-07-12T10:05:00.000Z"
    }
  ]
}

Platforms

GET /platforms

List all registered platforms.

GET /platforms/:id

Single platform by bytes32 ID.

Profiles

GET /profiles/:walletAddress

Get a user profile. Returns 404 if not found.

GET /api/v1/profiles/0x1234...

{
  "wallet_address": "0x1234...",
  "display_name": "CryptoApe",
  "avatar_url": null,
  "bio": "Meme coin degen since 2024",
  "twitter": "https://x.com/cryptoape",
  "telegram": null,
  "website": null,
  "created_at": "2026-07-12T10:00:00.000Z",
  "updated_at": "2026-07-12T10:00:00.000Z"
}

PUT /profiles

Create or update a profile. Body: { wallet_address, display_name?, avatar_url?, bio?, twitter?, telegram?, website? }

Analytics

GET /analytics/global

Global protocol statistics across all tokens and platforms.

{
  "total_tokens": 150,
  "graduated_tokens": 12,
  "total_volume_eth": "5000.5",
  "total_trades": 25000,
  "total_holders": 3200,
  "platforms_count": 5,
  "chain_id": 46630,
  "network": "testnet"
}

WebSocket Events

The indexer emits real-time events via Socket.IO at /events.

Event	Payload
`newToken`	`{ address, name, symbol, creator }`
`newTrade`	`{ type, token, trader, eth_amount, token_amount, price_eth, tx_hash }`
`graduation`	`{ token, poolId, ethAmount, tokenAmount }`

Pagination

All list endpoints return cursor-based pagination. Cursors are base64url-encoded JSON. Pass the next_cursor from a response as the cursor query parameter to get the next page.

{
  "pagination": {
    "next_cursor": "eyJzb3J0...",   // null if last page
    "prev_cursor": null,             // null if first page
    "has_next": true,
    "has_prev": false,
    "limit": 50,
    "count": 50                      // items in this page
  }
}

Error Responses

// 400 Bad Request
{ "statusCode": 400, "message": "Invalid cursor format." }

// 404 Not Found
{ "statusCode": 404, "message": "Token not found." }

// 500 Internal Server Error
{ "statusCode": 500, "message": "Internal server error." }