# Float API

Cardano DEX market data: ranked assets, per-asset and per-market OHLCV candles, venue coverage, and search. Confirmed-chain data only; every response carries meta.as_of ({slot, height, hash}) and meta.finality.

## The #1 integration rule: amounts are base units

All amounts (volume, liquidity, reserves, balances) are BASE-UNIT integer strings — lovelace, not ADA; token base units, not display units. The asset's `decimals` is always in the same response: display value = shift the decimal point left by `decimals`. Prices are numerator/denominator rationals plus a `value` decimal string at base-unit scale; display scale = shift by (decimals_base - decimals_quote). Pass `include=display` to get server-computed `*_display` strings instead of doing the shift yourself. `decimals: null` means not yet derivable — never assume zero.

## Vocabulary (verbatim from API.md — these rules bind every endpoint)

APIs live and die on consistency. These rules bind every endpoint,
frame, and future addition; the OpenAPI generator lints against them.

- **Points.** Any chain reference is a `{ slot, height, hash }` object.
  Field names give the *role* (`as_of`, `point`, `prev_point`); the
  shape never varies. Slot=time, height=ordering, hash=identity
  (principle 5).
- **Retraction.** The field is always `retract`; its payload names the
  granularity: `retract: { blocks: [points] }` (chain-level, consumer
  derives) or `retract: { trades: [ids] }` (resolved, server derived).
  Never `undo` (that is sync-v2's internal wire term), never
  `retracted`, never both.
- **Periods.** One grammar `<n><unit>` (`1m`, `5m`, `1h`, `24h`, `7d`)
  shared by candle intervals, change/volume windows
  (`change: { "1h": …, "24h": …, "7d": … }`), and WS channel names.
- **Counts vs collections.** Counts are `*_count` (`pool_count`,
  `trade_count`); bare resource plurals (`pools`, `trades`) are
  reserved for collections and `links` entries.
- **Transactions** are always `tx_hash` (hex string).
- **Opt-ins** use one grammar: `include=<block>[,<block>]`
  (`sparkline`, `display`, `profile`, `related`); `encoding=compact`
  is the only wire-format switch.

## Endpoints

- https://api.float.sundae.fi/v1 — Directory: every resource, its href, and the API policies
- https://api.float.sundae.fi/v1/health — Service statistics: chain-ingestion latency (and, next, request latency + throughput)
- https://api.float.sundae.fi/v1/assets — Ranked asset list (the screener feed)
- https://api.float.sundae.fi/v1/assets/{asset} — One asset: market data, registry metadata, and its markets
- https://api.float.sundae.fi/v1/assets/{asset}/candles — Token-level OHLCV (deepest pool's series for now)
- https://api.float.sundae.fi/v1/assets/rowstats — Screener row trend cells for every ranked token in one read
- https://api.float.sundae.fi/v1/assets/{asset}/trades — One asset's tape: every swap touching it, across venues
- https://api.float.sundae.fi/v1/assets/{asset}/holders — Holder count, total supply, and FDV
- https://api.float.sundae.fi/v1/assets/{asset}/decomposition — Redemption decomposition: hops, paths, per-hour rate series
- https://api.float.sundae.fi/v1/assets/{asset}/logo — Registry logo (PNG)
- https://api.float.sundae.fi/v1/card.png — Site social card (PNG, 1200x630)
- https://api.float.sundae.fi/v1/assets/{asset}/card.png — Social card (PNG, 1200x630)
- https://api.float.sundae.fi/v1/markets — Ranked market list: reserves, valued liquidity and volume
- https://api.float.sundae.fi/v1/markets/{market} — One pool/book: side assets, reserves, 24h activity
- https://api.float.sundae.fi/v1/markets/{market}/candles — Pool-level OHLCV
- https://api.float.sundae.fi/v1/markets/{market}/trades — One pool's tape: executed swaps, newest first
- https://api.float.sundae.fi/v1/trades — The global tape: recent swaps across every venue and token
- https://api.float.sundae.fi/v1/txs/{tx_hash} — One transaction's trades, in both of its roles
- https://api.float.sundae.fi/v1/markets/{market}/series — Detail-field series for one market (interest, invariants, supply)
- https://api.float.sundae.fi/v1/quotes — Quote series for one asset pair, from the rates facts
- https://api.float.sundae.fi/v1/rates/graph — The redemption graph: which assets redeem into which
- https://api.float.sundae.fi/v1/addresses/{address}/balances — Balance series per asset from the UTxO interval fold
- https://api.float.sundae.fi/v1/addresses/{address}/transitions — Per-transaction net asset movements for an address
- https://api.float.sundae.fi/v1/addresses/{address}/portfolio — Current balances × prices × metadata, joined server-side
- https://api.float.sundae.fi/v1/portfolio — One portfolio over many addresses: combined total plus per-address
- https://api.float.sundae.fi/v1/venues — Coverage registry: adapters, trust badges, per-venue tips
- https://api.float.sundae.fi/v1/stats — Per-venue and total volume, TVL, and a daily volume series
- https://api.float.sundae.fi/v1/search — Assets and markets, ranked
- https://api.float.sundae.fi/v1/openapi.json — This API, as OpenAPI 3.1 — generated from the route table
- https://api.float.sundae.fi/llms.txt — The point-an-AI-at-it entry point

Start at https://api.float.sundae.fi/v1 (the directory document) and follow `links` — every resource links its related resources; URLs never need constructing. Machine-readable spec: https://api.float.sundae.fi/v1/openapi.json