---
title: "Screen coins inside market boundaries (rank band, volume, sectors)"
method: GET
path: "/api/agent/universe"
tags: ["reads"]
---

# Screen coins inside market boundaries (rank band, volume, sectors)

`GET /api/agent/universe`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/agent/universe`
- Auth: HTTP bearer

Returns up to `limit` active coins inside the caller's boundaries:
market-cap rank band, minimum 24h USD volume, optional stablecoin
exclusion and curated sectors in/out (ids from
/api/agent/universe/sectors). Coins flagged market-cap-suspect and
coins whose live price is older than 72 h are never included. Sorts
that need a change or volume value exclude coins where it is null.
Ties break on market-cap rank, then UCID, so equal data gives equal
order. A sector both included and excluded is excluded.

Pass `ucids` to check whether specific coins are inside the same
boundaries (membership check, at most 50 ids). Unknown query
parameters are ignored. Pure market data on a shared 60 s URL-keyed
cache, so `priceAgeHours` can lag the response time by up to a
minute. Requires scope `read`.

## Query parameters

- `rankMin` integer
- `rankMax` integer
- `minVolume24hUsd` number
- `excludeStablecoins` 'true' | 'false' | '1' | '0'
- `includeSectors` string
- `excludeSectors` string
- `sort` 'gainers_24h' | 'losers_24h' | 'abs_change_24h' | 'abs_change_1h' | 'volume_24h' | 'rank'
- `ucids` string
- `limit` integer

## Response `200`

OK

- AgentUniverseResponse
  - `rows` AgentUniverseRow[], required
    - `ucid` string, required: Coin UCID
    - `symbol` string, required
    - `name` string, required
    - `slug` string, required
    - `marketCapRank` integer, required
    - `priceUsd` number, required
    - `change1h` number, nullable, required: Percent change.
    - `change24h` number, nullable, required: Percent change.
    - `change7d` number, nullable, required: Percent change.
    - `volume24hUsd` number, required
    - `marketCapUsd` number, nullable, required
    - `priceUpdatedAt` string, date-time, required: Last write of the coin's live price row.
    - `sectors` string[], required: Curated sector/ecosystem ids the coin belongs to (may be empty).
    - `priceAgeHours` number, nullable, required: Hours since priceUpdatedAt, one decimal, computed when the response was built.
    - `priceStale` boolean, required
    - `priceStaleAfterHours` integer, required
  - `observation` AgentObservation, required: Compact provenance block for an agent-facing market observation. It is also stored in the private ledger responseSummary when the request uses agentTrace/run headers, giving run exports a verifiable snapshot of what the agent observed without creating a full market archive.
    - `schema` string
    - `endpoint` string
    - `source` string
    - `observedAt` string, date-time
    - `sourceAsOf` string, date-time, nullable
    - `freshness` Freshness: Data-freshness descriptor. Futures + spot use ageSeconds; PM uses ageMinutes. `status` is a freshness label; `basis` (PM only) names which timestamp the age was measured against.
      - `asOf` string, date-time, nullable
      - `ageSeconds` number, nullable: futures / spot
      - `ageMinutes` number, nullable: PM
      - `status` 'fresh' | 'lagging' | 'stale' | 'unknown' | 'null', nullable: fresh | lagging (PM only) | stale | unknown. PM lagging>=45m & stale>=2h; spot/futures stale>120s.
      - `basis` 'latest_snapshot' | 'source_update' | 'processed' | 'event_update' | 'unknown', nullable: PM only — which timestamp the age was measured against.
    - `inputs` object
    - `dataset` object
    - `rowCount` integer, nullable
    - `hash` string: Short SHA-256 digest of the observed payload metadata.

## Other responses

- `400`: Invalid query (out-of-range number, unknown sector id, rankMin > rankMax, bad ucids, repeated parameter).
- `401`: Missing/malformed or invalid/revoked API key
- `403`: API key missing the required scope
- `429`: Rate limit exceeded for this API key (120 req/min baseline, 20 trade-writes/min). Honor `Retry-After`, then resume; the `RateLimit-*` headers on every response let you pace proactively. (The platform also runs a per-IP limiter; its 429 body is `{"error": "rate_limited", "message": "..."}`.)
- `500`: Server error

---

[API](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api.md) · [All operations](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/revisions/28fb59f285fe?raw)