Reading the manifest

Base URL https://purser.report/api/v1. Every response is { data, generatedAt }. generatedAt is when the response was built, not when the chain was read — that is observedAt on the observation itself.

Addresses are accepted in any case and always returned lowercase. An address that is tracked but has no record yet returns 404 not_found; a malformed one is rejected rather than guessed at.

A /tokens row is the token record plus two additions: fundedPools, the number of its pools actually holding liquidity, and latest, its most recent observation — or null for a token discovered and verified but not yet read. The caveats in §02 apply to latest exactly as they do on the detail endpoint; a field never means one thing on the list and another on the record.

const { data } = await (await fetch(
  'https://purser.report/api/v1/tokens'
)).json()

const tradeable = data.filter(t =>
  t.fundedPools > 0 &&            // there is a market at all
  t.latest &&                     // it has been read
  t.latest.priceUsd !== null      // the price is per-share, not raw
)

// Do NOT rank by cost alone. The figure only holds inside the band.
const fragile = tradeable.filter(t =>
  !t.latest.bandFullRange &&
  t.latest.bandPct !== null &&
  t.latest.bandPct < 5            // book runs out before the 5% it prices
)

That is one request. Before this endpoint carried latest, the same result took 179 — a six-minute sweep at 30 requests a minute, against an indexer that re-reads each token every ten. Any client written against that older shape could not keep up with the data it was being offered.

These are the ones worth understanding before you trade on anything here. Each is null in a specific, meaningful circumstance.

/events is a change log, not a status poll. A row means something changed; a condition that merely persists is visible in the token and pool records instead. Severities: critical, high, medium, info.

let cursor = 0
setInterval(async () => {
  const url = 'https://purser.report/api/v1/events'
    + '?afterId=' + cursor + '&limit=500'
  const { data } = await (await fetch(url)).json()
  for (const e of data) handle(e)
  if (data.length) cursor = Math.max(...data.map(e => Number(e.id)))
}, 60_000)   // the indexer writes at most once a minute

30 requests per minute per IP, fixed window, no key required. Over quota returns 429 with Retry-After.

Responses are cached at the edge for 30 seconds. The indexer runs every minute, so a cached reading is at worst half a cycle behind one that was already up to a minute old. Because a cached response is shared, X-RateLimit-Remaining and X-RateLimit-Reset appear only on uncached responses — errors and 429s — where they describe you rather than whoever populated the cache. X-RateLimit-Limit is a policy constant and is always present.

Retention. Observations are kept for 3 days and then deleted, so?hours= is capped at 72. That is a storage limit, not a design preference: the indexer writes roughly 7,000 observations an hour, about 78 MB a day, and the database behind this service is a 512 MB tier. Asking for a longer window returns the capped one rather than a silent partial answer.

CORS is open to all origins for GET and OPTIONS. Integers that exceed IEEE-754 range — supplies, reserves — are serialised as decimal strings, not numbers. Parse them with BigInt; a token supply is around 10²³ and reading it as a float loses precision silently.