# Get Tokens

## Get Paginated List of Tokens

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

<mark style="color:blue;">`GET`</mark> `https://www.clanker.world/api/tokens`

#### **Query Parameters**

| Parameter       | Type                             | Default   | Description                                                      |
| --------------- | -------------------------------- | --------- | ---------------------------------------------------------------- |
| q               | string                           | undefined | Search query for token name or symbol                            |
| fids            | string (comma-separated numbers) | undefined | Filter by specific 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)            |
| 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                  |

**Request**

{% tabs %}
{% tab title="cURL" %}
```bash
curl "https://www.clanker.world/api/tokens"
```
{% endtab %}

{% tab title="JavaScript" %}
```javascript
const response = await fetch('https://www.clanker.world/api/tokens');
const data = await response.json();
console.log(data);
```
{% endtab %}
{% endtabs %}

**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
      },
      "starting_market_cap": 9.870869513221747,
      "tags": {
        "champagne": false
      },
      "extensions": {
        "fees": {
          "type": "static",
          "clankerFee": 10000,
          "pairedFee": 10000
        }
      },
      "related": {}
    }
  ],
  "total": 1,
  "cursor": "eyJpZCI6IjIwMjQtMTItMTVUMTQ6MzA6MDAifQ=="
}
```

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

#### 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)                       |
| social\_context   | Social media context (platform, messageId, etc.)       |
| extensions        | Additional token features (fees, vault, airdrop, etc.) |
| related.user      | Creator profile data (only if includeUser=true)        |
| related.market    | Market data (only if includeMarket=true)               |

{% hint style="info" %}
Pagination Tips

* Default limit is 10, maximum is 20
* Search is case-insensitive and matches both token names and symbols
{% endhint %}
