Data Caveats - Allium Documentation Hub

Data Formats & Conventions

Understanding these data conventions will help you work more effectively with Allium’s APIs:

Timestamps

All timestamps are in Coordinated Universal Time (UTC) using ISO 8601 format.

Prices

All price-related data are in USD denomination unless otherwise stated.

Address Casing

All EVM addresses are returned in lowercase.

Native Token Addresses

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

Value	Meaning
`{"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
`null`	No liquidity information available for this token

Our liquidity calculation process:

Identify all pools associated with the token
Check if the token has very high liquidity (returns LIQUIDITY_TOO_HIGH)
Calculate the total amount of tokens across all pools
Multiply by the token price to get total_liquidity_usd

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.

Overview Chain & Endpoint Availability

⌘I

​Data Formats & Conventions

​Token Liquidity Filtering

​How It Works

​Example: Filtering by Liquidity

Data Formats & Conventions

Token Liquidity Filtering

How It Works

Example: Filtering by Liquidity