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

# Reading responses

> Field names, timestamps, money objects, decimals and percentages across the API.

Every endpoint and every stream follows the same conventions. Once you have read one response, you can read them all.

## Field names

Field names and query parameters are **camelCase**: `marketCap`, `priceChangePct`, `countBack`.

Enumerated **values** are case-sensitive strings, such as `"side": "buy"`, `"flags": ["pro_trader"]` and `"metric": "marketCap"`. Send and compare them exactly as these docs spell them.

## Timestamps

Every timestamp is an integer count of **milliseconds** since the Unix epoch, in requests and responses alike.

* Fields that hold an instant end in `At`: `createdAt`, `graduatedAt`, `updatedAt`.
* Some records name the instant directly: a trade's `timestamp`, a candle's `time`.

```json theme={null}
{ "createdAt": 1723180800000 }
```

<CodeGroup>
  ```python Python theme={null}
  from datetime import datetime, timezone

  created = datetime.fromtimestamp(token["createdAt"] / 1000, tz=timezone.utc)
  ```

  ```typescript TypeScript theme={null}
  const created = new Date(token.createdAt);
  ```
</CodeGroup>

## Money objects

A value with a price is an object with two legs:

```json theme={null}
{ "price": { "native": "0.000000121", "usd": "0.0000216" } }
```

| Leg | Meaning |
| - | - |
| `native` | The value in the chain's native gas asset: SOL on Solana, ETH on Base and Robinhood Chain, BNB on BSC. The object's `chain` field names the chain. |
| `usd` | The value in US dollars. `null` when the native asset has no USD price. |

Prices, market caps, liquidity, volumes and fee totals all use this shape. The API never sends a bare `priceUsd` field.

## Decimal strings

Prices, amounts, supplies and percentages are **strings** that hold an exact decimal: `"0.0000216"`, `"1000000000"`.

JSON numbers are floating point, and they lose precision on small prices and on large token amounts. Parse these strings with a decimal type:

<CodeGroup>
  ```python Python theme={null}
  from decimal import Decimal

  usd = token["price"]["usd"]
  price = Decimal(usd) if usd is not None else None
  ```

  ```typescript TypeScript theme={null}
  import Big from "big.js";

  const price = token.price.usd === null ? null : new Big(token.price.usd);
  ```
</CodeGroup>

Counts, such as `holders.count` and `buyCount`, are plain JSON integers.

### The candle exception

Candle values (`open`, `high`, `low`, `close`, `volume`) are **JSON numbers**, because charting libraries consume them as floats. Nothing else in the API sends money as a number.

## Percentages

A field ending in `Pct` holds a percentage on a **0–100 scale**, as a decimal string. The sign is kept.

```json theme={null}
{ "priceChangePct": "-2.5", "top10Pct": "31.7" }
```

`"-2.5"` means a fall of 2.5%, not a factor of -0.025.

Transfer fees are the one exception: `transferFeeBps` is an integer in **basis points**, so `250` means 2.50%.

## Windowed stats

A token's `stats` object holds one entry per trailing window. The keys are `5m`, `30m`, `1h`, `6h` and `24h`. Each window ends now; it is not a calendar bucket.

```json theme={null}
{
  "stats": {
    "1h": {
      "priceChangePct": "1.8",
      "volume": { "native": "4120.5", "usd": "735509" },
      "buyCount": 2210,
      "sellCount": 1984,
      "buyVolume": { "native": "2101.2", "usd": "375064" },
      "sellVolume": { "native": "2019.3", "usd": "360445" }
    }
  }
}
```

## Missing values

* Most values that are not known yet are `null`. For example, `graduatedAt` is `null` until a token leaves its launchpad.
* A few fields use an empty value instead. A trade's `name` and `symbol` are empty strings until the token's metadata resolves, and fields marked "not yet populated" hold `0`.
* A list that would be empty may be left out. On a token, `platforms` and `annotations` are left out when empty. On a trade, `flags`, `platforms` and `identities` are left out when empty. Treat a missing list as empty.

## Values that can grow

Some fields hold a value from a set that grows over time, such as a trade's `flags`, a token's `dexes` and `launchpad`, and an identity's `source`. Keep a value you do not recognize, rather than failing on it.

Also ignore any response field you do not recognize. New fields can appear without a version change. See [Versioning and compatibility](/concepts/versioning).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.