> ## Documentation Index
> Fetch the complete documentation index at: https://docs.donate.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Stats by Address

> Fetch donation stats for a Charity Token by chain and token address

<Badge icon="shield" color="blue" shape="pill">
  Requires <span style={{ color: '#1D4ED8', fontWeight: '800' }}>core</span> scope
</Badge>

This endpoint returns aggregate donation stats for a single Charity Token, plus a breakdown for the
active config and previous configs.

## Get token stats by address

`GET /{chainId}/tokens/{address}/stats`

```bash theme={null}
curl "https://www.donate.gg/api/v1/{chainId}/tokens/{address}/stats" \
	-H "donate-api-key: YOUR_API_KEY"
```

**Path parameters**

| Parameter | Type    | Description                                         |
| --------- | ------- | --------------------------------------------------- |
| `chainId` | integer | Supported chain ID (see [Chains](/core-api/chains)) |
| `address` | string  | Token address (canonicalized for the chain type)    |

**Response**

```json theme={null}
{
  "usdDonatedE6": "50000000",
  "donationCount": "10",
  "firstDonationDate": "2025-06-01T00:00:00.000Z",
  "lastDonationDate": "2026-03-15T00:00:00.000Z",
  "allTimeDonationRank": 12,
  "activeConfig": {
    "id": { "hex": "0x1234...abcd", "base58": "3xYz..." },
    "usdDonatedE6": "20000000",
    "donationCount": "4",
    "firstDonationDate": "2025-06-01T00:00:00.000Z",
    "lastDonationDate": "2026-01-10T00:00:00.000Z",
    "inputVolumeGrossAtomic": {
      "0xA0b8...": "12000000",
      "0xdAC1...": "8000000"
    }
  },
  "previousConfigs": [
    {
      "id": { "hex": "0xabcd...1234", "base58": "4AbC..." },
      "usdDonatedE6": "30000000",
      "donationCount": "6",
      "firstDonationDate": "2025-07-01T00:00:00.000Z",
      "lastDonationDate": "2026-03-15T00:00:00.000Z",
      "inputVolumeGrossAtomic": {
        "0xA0b8...": "30000000"
      }
    }
  ]
}
```

**Field notes**

| Field                    | Type            | Description                                                                 |
| ------------------------ | --------------- | --------------------------------------------------------------------------- |
| `usdDonatedE6`           | string          | Total donated USD in $10^{-6}$ precision (micro-dollars).                   |
| `donationCount`          | string          | Number of donations for this token.                                         |
| `allTimeDonationRank`    | integer \| null | Global all-time rank for this token, or `null` if it has no donations.      |
| `activeConfig`           | object          | Stats for the token's current active config.                                |
| `previousConfigs`        | array           | Stats for configs previously associated with the token.                     |
| `inputVolumeGrossAtomic` | object          | Per-input-token gross volume map: `{ tokenAddress: atomicAmountAsString }`. |

### Error responses

| Status | Code                  | Description                       |
| ------ | --------------------- | --------------------------------- |
| `400`  | `VALIDATION_ERROR`    | Invalid chain ID or token address |
| `400`  | `CHAIN_NOT_SUPPORTED` | Chain is not supported            |
| `404`  | `NOT_FOUND`           | Token not found                   |