Stablecoins API v2

Summary

The proposal has three current-data resources and three historical resources. Global and chain pages use the same endpoints; adding chain only changes the scope. Historical data uses [timestamp, value] tuples, with Unix timestamps in seconds as JSON numbers.

Responses contain data and identity metadata, not ECharts options or frontend view names. Total, breakdown, dominance, pie, bar, and treemap are presentations of these resources—not separate API concepts.

Endpoint reference

This is the proposed surface area. Parameters not listed for an endpoint are not accepted; unsupported parameters or combinations return 400 rather than being silently ignored.

Current data

Historical data

Scope and grouping are separate. chain=ethereum limits the dataset; groupBy=asset splits that dataset into asset series. Omit groupBy for one total; add it for the complete breakdown. Scope one asset or chain directly instead of sending a list of selections.

Combination rule: a request cannot scope and group by the same dimension. For example, chain=ethereum&groupBy=chain is invalid because the result could only contain Ethereum. chain=ethereum&groupBy=asset is valid. Supplying both chain and asset returns the total for that exact intersection.

Date parameters accepted by every history endpoint

Example requests

Legacy to v2

The v2 URLs name the resource being requested. Legacy implementation names, special all values, numeric IDs, and frontend chart modes stay out of the public contract.

Response shape

The current app proxy converts upstream records into chart-library configuration. The v2 API should stop at a portable data contract and let each client decide how to render it. There are only three shapes to learn: a current-data list, a historical total, and a grouped historical response.

Grouped history

A series is simply one returned line: one asset when groupBy=asset, one chain when groupBy=chain, or one currency when groupBy=pegCurrency. Timestamps and values are JSON numbers. The request URL already describes the metric, scope, grouping, and selection, so the response does not repeat them.

{
  "unit": "usd",
  "data": [
    [1728345600, 137000000000],
    [1728432000, 137500000000]
  ]
}

{
  "assets": [
    {
      "id": 1,
      "slug": "tether",
      "name": "Tether",
      "symbol": "USDT",
      "pegCurrency": "USD",
      "circulatingUsd": 119000000000
    }
  ]
}

The complete selector data comes from /v2/assets or /v2/chains. A grouped request returns every matching series. For one asset or chain, use the singular asset or chain scope. The frontend can filter a complete breakdown locally or combine individually cached histories; the API does not accept arbitrary selection lists or create an “Other” series.

Keeping responses small

Measurements below are rough, uncompressed JSON estimates captured on July 27, 2026. They are useful for comparing shapes, not performance guarantees.

Full breakdowns are cacheable and compressible. A client that needs only one asset or chain can use the singular scope instead. Date ranges reduce transfer size further without introducing frontend selection concepts into the API.

How the app would use it

Pie, horizontal bar, and treemap views read current table data. Historical endpoints power total, breakdown, and dominance views. The API never receives names such as treemap or dominance.

/stablecoins and /stablecoins/:chain

/stablecoins/chains

/stablecoin/:asset

Decisions in this draft

Identity

Stable URL slugs are public identifiers. Immutable internal IDs remain in responses for joins and migrations.

Global scope

Omitting chain means global. There is no all or all-llama-app sentinel.

Time

Unix timestamps remain seconds on the wire and are always JSON numbers. start and end are inclusive.

Units

Historical responses state their unit once, such as "unit": "usd". Values are raw numbers, never preformatted strings.

Missing values

null means unknown or unavailable. Zero means a measured value of zero; the two are never interchangeable.

Presentation

Colors, encodes, stacks, tooltip settings, and UI view names belong to clients—not the API response.

Cache units

Cache totals, complete breakdowns, and singular asset or chain histories. The API does not create cache entries for arbitrary selector combinations.

Still to decide

1. Market-cap semantics: confirm whether the source is price-adjusted market cap or circulating supply expressed in USD; rename the endpoint and fields if “market cap” is inaccurate.
2. Net flows: define whether this means daily deltas, rolling sums, or transfer-derived flows before proposing an endpoint name or response.
3. Double counting: what is the canonical treatment of bridged representations in global totals and chain breakdowns?
4. Unreleased supply: is includeUnreleased enough, or should released and unreleased amounts always be separate named series?
5. Incomplete periods: should the latest partial day be returned with an explicit completeness flag, or omitted until final?
6. Large breakdowns: should an unfiltered grouped response always return every series, and what response-size safeguards are needed?
7. Rollout: deprecation window, cache headers, rate limits, and whether legacy URLs redirect or run in parallel.