Skip to main content

​
Data Formats & Conventions

Understanding these data conventions will help you work more effectively with Allium’s APIs:
All timestamps are in Coordinated Universal Time (UTC) using ISO 8601 format.
All price-related data are in USD denomination unless otherwise stated.
All EVM addresses are returned in lowercase.
Native tokens are represented by the zero address for most chains:
  • Ethereum & most EVM chains: 0x0000000000000000000000000000000000000000
  • Solana: So11111111111111111111111111111111111111112
  • Tron: T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

​
Token Liquidity Filtering

Some endpoints support a with_liquidity_info=true query parameter to help filter out spam or scam tokens from your application.

​
How It Works

When enabled, liquidity data is returned in the total_liquidity_usd field with one of the following values:
  • Return Values
  • Methodology
ValueMeaning
{"amount": 123, "details": null}The USD value of total liquidity across all pools for this token
{"amount": null, "details": "LIQUIDITY_TOO_HIGH"}Token is very popular (e.g., WETH on Ethereum) and very likely legitimate
nullNo liquidity information available for this token

​
Example: Filtering by Liquidity

This example filters for tokens with at least $5,000 USD in liquidity: 
balances = requests.post(
    "https://api.allium.so/api/v1/developer/wallet/balances",
    params={"with_liquidity_info": True},
    headers={"X-API-KEY": "your-api-key"},
    # other parameters...
).json()["items"]

balances_with_high_liquidity = []
for balance in balances:
    liquidity = balance["token"].get("attributes", {}).get("total_liquidity_usd")
    
    # Filter for high liquidity tokens
    if liquidity is not None and (
        liquidity.get("details") == "LIQUIDITY_TOO_HIGH"
        or liquidity.get("amount", 0) >= 5000
    ):
        balances_with_high_liquidity.append(balance)

# Use filtered results...
Adjust the threshold based on your needs. A higher threshold (e.g., $10,000+) will be more conservative, while a lower threshold will include more tokens.
⌘I