# Data schema

Machine-readable data published by the Paycoin Index. Provided as-is; see /terms/.

## `latest.json` — full current snapshot

- `schemaVersion` — integer, currently 1.
- `date` — UTC date of the run, `YYYY-MM-DD`.
- `generatedAt` — ISO timestamp of the run.
- `sources` — per-fetcher status: `{ ok, fetchedAt, stale, error? }`. When a fetch fails, its
  data is carried forward from the previous run and `stale` reflects whether it exceeds the
  staleness threshold (48h).
- `prices` — native token USD prices keyed by symbol (`ETH`, `SOL`, `TRX`, `POL`). Source: CoinGecko.
- `gas` — raw fee inputs keyed by chain id:
  - EVM chains: `{ gasPriceWei }`
  - `solana`: `{ baseFeeLamports, medianPriorityMicroLamportsPerCu, assumedComputeUnits }`
  - `tron`: `{ energyFeeSun, energyPerTransfer }`
- `stablecoins` — per symbol (`USDT`, `USDC`): `{ name, supply, pegMechanism, chains }` where
  `chains` maps chain name → circulating USD amount. Source: DefiLlama.
- `totalStablecoinSupply` — all USD-pegged stablecoins, USD. Source: DefiLlama.
- `regulation` — `[{ source, title, link, date }]` from official regulator RSS feeds.
- `costs` — per chain id: `{ feeUsd }`, the estimated USD fee for one stablecoin transfer
  (formulas: /methodology/).
- `index` — `{ avgFeeUsd, bps1k }`: the Paycoin Index — supply-weighted average transfer fee and
  the same expressed in basis points of $1,000.

## `history/YYYY-MM-DD.json` — one compact record per day, append-only

- `date`, `index`, `prices`, `totalStablecoinSupply` — as above.
- `costs` — per chain id: `feeUsd` (number, not object).
- `stablecoins` — per symbol: `{ supply, chains }` where `chains` is keyed by *chain id* and
  restricted to the chains the index tracks.
- `sources` — per-fetcher boolean (`true` = fetched fresh that day).

The history directory is append-only and is never pruned or rewritten.

## `history.json` — the whole archive in one file

A JSON array of every `history/YYYY-MM-DD.json` record above, oldest first. Identical content,
one request instead of one per day.

## `history.csv` — the whole archive as a flat table

One header row, then one row per day, oldest first. Columns:

- `date` — UTC date, `YYYY-MM-DD`.
- `index_avg_fee_usd`, `index_bps1k` — the Paycoin Index for that day.
- `total_stablecoin_supply_usd` — all USD-pegged stablecoins, USD.
- `fee_usd_<chain id>` — one column per tracked rail, the estimated USD fee for one stablecoin
  transfer that day. Empty when that rail has no observation for the day.

The CSV carries the costs and the index only; per-day prices, per-chain supply and source
provenance are in the JSON.