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

# Data Caveats

> Important information about data formats and conventions used in Allium's Developer APIs.

## Data Formats & Conventions

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

<AccordionGroup>
  <Accordion title="Timestamps" icon="clock">
    All timestamps are in **Coordinated Universal Time (UTC)** using ISO 8601 format.
  </Accordion>

  <Accordion title="Prices" icon="dollar-sign">
    All price-related data are in **USD denomination** unless otherwise stated.
  </Accordion>

  <Accordion title="Address Casing" icon="text">
    All EVM addresses are returned in **lowercase**.
  </Accordion>

  <Accordion title="Native Token Addresses" icon="coins">
    Native tokens are represented by the **zero address** for most chains:

    * **Ethereum & most EVM chains:** `0x0000000000000000000000000000000000000000`
    * **Solana:** `So11111111111111111111111111111111111111112`
    * **Tron:** `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb`
  </Accordion>
</AccordionGroup>

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

<Tabs>
  <Tab title="Return Values">
    | 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                         |
  </Tab>

  <Tab title="Methodology">
    Our liquidity calculation process:

    1. Identify all pools associated with the token
    2. Check if the token has very high liquidity (returns `LIQUIDITY_TOO_HIGH`)
    3. Calculate the total amount of tokens across all pools
    4. Multiply by the token price to get `total_liquidity_usd`
  </Tab>
</Tabs>

### Example: Filtering by Liquidity

This example filters for tokens with at least \$5,000 USD in liquidity:

```python theme={null}
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...
```

<Tip>
  **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.
</Tip>