Get Paginated List of Tokens

Retrieves a paginated list of deployed tokens with optional filtering and sorting capabilities.

Endpoint: GET https://www.clanker.world/api/tokens

---

Query Parameters

Parameter	Type	Default	Description
q	string	undefined	Search query for token name or symbol
fid	number	undefined	Filter by a single Farcaster user ID (e.g., fid=12345)
fids	string (comma-separated numbers)	undefined	Filter by multiple Farcaster user IDs (e.g., fids=123,456,789)
pairAddress	string	undefined	Filter by paired token contract address
sort	string	'desc'	Sort order: asc (oldest first) or desc (newest first)
sortBy	string	undefined	Sort field: market-cap, tx-h24, price-percent-h24, price-percent-h1, or deployed-at
socialInterface	string	undefined	Filter by social interface (e.g., clanker.world, Bankr)
limit	number	10	Number of results to return (max 20)
cursor	string	undefined	Cursor for efficient pagination
includeUser	boolean	false	Include creator profile data (avatar, name, bio, etc.)
includeMarket	boolean	false	Include real-time market data (market cap, price change, volume)
startDate	number	undefined	Filter tokens created after this Unix timestamp
chainId	number	undefined	Filter by chain ID (e.g., 8453 for Base)
champagne	boolean	false	Filter to show only champagne tokens

---

Example Requests

Search by token name/symbol

curl "https://www.clanker.world/api/tokens?q=EXAMPLE"

Search by single FID (creator)

curl "https://www.clanker.world/api/tokens?fid=12345"

Search by FID with market data

curl "https://www.clanker.world/api/tokens?fid=12345&includeMarket=true&sortBy=market-cap&sort=desc"

Search by contract address

curl "https://www.clanker.world/api/tokens?q=0x525358b364b9bb38227054affdc37cecdd516b81"

---

Example Response

{
  "data": [
    {
      "id": 12345,
      "created_at": "2024-12-15T14:30:00",
      "last_indexed": "2024-12-15T14:32:17.303",
      "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "contract_address": "0xAbCdEf1234567890AbCdEf1234567890AbCdEf12",
      "name": "Example Token",
      "symbol": "EXAMPLE",
      "description": "This is an example token for demonstration purposes",
      "supply": "100000000000000000000000000000",
      "img_url": "https://example.com/images/token-logo.png",
      "pool_address": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
      "type": "clanker_v4",
      "pair": "WETH",
      "chain_id": 8453,
      "metadata": {
        "auditUrls": [],
        "description": "This is an example token for demonstration purposes",
        "socialMediaUrls": [
          {
            "platform": "twitter",
            "url": "https://twitter.com/example_token"
          }
        ]
      },
      "deployed_at": "2024-12-15T14:30:00",
      "msg_sender": "0x1111111111111111111111111111111111111111",
      "factory_address": "0x2222222222222222222222222222222222222222",
      "locker_address": "0x3333333333333333333333333333333333333333",
      "position_id": "0",
      "warnings": [],
      "pool_config": {
        "pairedToken": "0x4444444444444444444444444444444444444444",
        "tickIfToken0IsNewToken": -230400
      }
    }
  ],
  "total": 1,
  "cursor": "eyJpZCI6IjIwMjQtMTItMTVUMTQ6MzA6MDAifQ==",
  "tokensDeployed": 1
}

---

Response Fields

Field	Description
data	Array of token objects
total	Total number of tokens matching the query
cursor	Pagination cursor for next page (use in subsequent requests)
tokensDeployed	Total number of tokens deployed (useful when filtering by creator FID)

---

Token Object Fields

Field	Description
contract_address	Token contract address
name	Token name
symbol	Token symbol
description	Token description
img_url	Token image URL
type	Token type (e.g., clanker_v4, clanker_v3_1)
pair	Trading pair (e.g., WETH, DEGEN)
chain_id	Chain ID (e.g., 8453 for Base)
deployed_at	Deployment timestamp
tx_hash	Deployment transaction hash
pool_address	Uniswap pool address
msg_sender	Address that deployed the token
factory_address	Clanker factory contract address
locker_address	LP locker contract address
social_context	Social media context (platform, messageId, etc.)
extensions	Additional token features (fees, vault, airdrop, etc.)
warnings	Array of warnings about the token configuration
related.user	Creator profile data (only if includeUser=true)
related.market	Market data (only if includeMarket=true)

---

Pagination Tips

• Default limit is 10, maximum is 20

• Search is case-insensitive and matches both token names and symbols

• Use the cursor from the response to fetch the next page of results

• When searching by fid, tokensDeployed gives you the total count of tokens created by that user