Token Endpoints
Endpoints for retrieving token information including USD pricing and holder data across supported blockchain networks.
Get Token USD Price
Retrieve current USD pricing for any ERC-20 token.
Endpoint: GET /{chainId}/tokens/{tokenAddress}/usdPrice
Path Parameters
- chainId (required): Network identifier such as
1, mainnet, 100, or gnosis
- tokenAddress (required): Token contract address (checksummed or lowercase); use
- for native tokens
Response
| Field | Type | Description |
|---|
| price | number | Current token value in USD |
Code Examples
curl https://api.cow.fi/1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/usdPrice
const response = await fetch(
'https://api.cow.fi/1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/usdPrice'
);
const data = await response.json();
console.log(data.price);
import requests
response = requests.get(
'https://api.cow.fi/1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/usdPrice'
)
data = response.json()
print(data['price'])
Response Example
{
"price": 3561.1267842
}
Error Response (404)
{
"message": "Price not found"
}
Get Token Top Holders
Retrieve the list of principal token holders.
Endpoint: GET /{chainId}/tokens/{tokenAddress}/topHolders
Path Parameters
- chainId (required): Network identifier like
1, 100, or 11155111
- tokenAddress (required): Token contract address in any standard format
Response
Returns an array of holder objects:
| Field | Type | Description |
|---|
| address | string | Holder wallet address |
| balance | string | Token quantity in wei-equivalent units |
Code Examples
curl https://api.cow.fi/1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/topHolders
const response = await fetch(
'https://api.cow.fi/1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/topHolders'
);
const holders = await response.json();
console.log(`Found ${holders.length} holders`);
import requests
response = requests.get(
'https://api.cow.fi/1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/topHolders'
)
holders = response.json()
print(f"Found {len(holders)} holders")
Response Example
[
{
"address": "0x1234567890abcdef1234567890abcdef12345678",
"balance": "1000000000000000000000"
},
{
"address": "0xabcdef1234567890abcdef1234567890abcdef12",
"balance": "500000000000000000000"
}
]
Error Response (404)
{
"message": "Token holders not found"
}
Notes
Native Token Pricing
For native assets like ETH or xDAI, substitute - as the token address:
curl https://api.cow.fi/1/tokens/-/usdPrice
Caching Behavior
Price data responses implement caching. Examine the Cache-Control header for cache duration details.
Network Support
Available on all supported networks with varying data completeness:
| Network | Coverage |
|---|
| Ethereum Mainnet | Complete |
| Gnosis Chain | Complete |
| Sepolia | Partial |
Error Handling
| Status | Cause | Recommended Action |
|---|
| 404 | Token not located | Confirm token address and chain ID |
| 404 | Pricing unavailable | Token may lack oracle-provided price |
| 400 | Malformed address | Provide valid Ethereum address format |
| 500 | Server issue | Attempt request again after brief delay |
Last modified on March 4, 2026
