API documentation

The data API lives at https://api.aggre.org. It is read-only HTTP and JSON. This page covers what every route shares; the dataset references are market data, economic calendar and legal statutes.

Quickstart

Sign in to the console and create an API key. The secret (aggre_sk_…) is shown once; store it like a password.
Check the key and see your remaining quota:

export AGGRE_API_KEY=aggre_sk_…
curl -H "Authorization: Bearer $AGGRE_API_KEY" https://api.aggre.org/v1/whoami
curl -H "Authorization: Bearer $AGGRE_API_KEY" https://api.aggre.org/v1/datasets

Authentication

Send the key as Authorization: Bearer aggre_sk_…; X-API-Key: aggre_sk_… is accepted too. A key is aggre_sk_ followed by 43 URL-safe characters. Aggre stores only a hash of it plus a short display prefix, so a lost key cannot be recovered; revoke it and make a new one.

The API sets no cookies and sends no CORS headers. Call it from a server, not from a web page: a key placed in browser code is visible to every visitor.

Two routes every key can call

`GET /v1/whoami`

Describes the key you present, never its secret: key_id, key_prefix, name, account, rate_policy, ip_allowlist_configured and usage (period, limit, used). It counts as a request. used is flushed in batches, so it can lag a few seconds.

`GET /v1/datasets`

Returns { "data": [ { "id", "title", "path", "store_kind" } ] }. path is where to read the dataset. This is the authoritative list of what the service you are calling serves; the datasets page adds status and scope.

Conventions

Identifiers are strings. A dataset id is {domain}.{category}.{name}, for example finance.market.candles_1m. An instrument id is {VENUE}:{PRODUCT}:{native}, for example OKX:SPOT:SOL-USDC.
Time. Series timestamps are Unix milliseconds, UTC. Event times in meta are RFC 3339.
Numbers. Measured values are JSON numbers. Money and on-chain amounts, where they appear, are decimal strings.
Unknown or repeated query parameters are rejected with 400 invalid_request instead of being ignored, so a typo does not silently change your query.
Envelope. List routes return { "data": …, "meta": …, "next_cursor": … }. meta has source, status (ok, stale or empty), fetchedAt, dataDate and an optional message.
Every response carries x-request-id. Quote it when you report a problem.

Errors

Failures return a JSON envelope with a stable machine code. Branch on error.code, not on the message.

{ "error": { "code": "invalid_request", "message": "…", "request_id": "…" } }

HTTP	code	When
400	`invalid_request`	Unknown or repeated parameter, value out of range, malformed id or cursor.
401	`unauthorized`	No key, a malformed key, an unknown key or a revoked one.
403	`ip_not_allowed`, `forbidden`	The key has an IP allow-list that excludes the caller, or the account is disabled.
404	`not_found`	Well-formed id that does not exist.
429	`rate_limited`	Too many requests from your source IP. Applied before the key is checked. Wait the number of seconds in the Retry-After header, then retry.
429	`usage_limit_exceeded`	The key used up its quota for the current period.
503	`store_unavailable`	The store behind the dataset is not reachable or not configured. Retry later.

Limits and what is logged

There are two limits: a per-IP request rate (with a short burst allowance) and a per-key request quota per period. The exact numbers are tuning and can change; the quota for your key is in /v1/whoami. Per request, Aggre records the method, the matched route template, the dataset id, the HTTP status, the request id and the key. It does not record your IP address or the text of your query, and it never logs a key.

JSON Schemas

The row shapes are published as JSON Schema (draft 2020-12), at the URLs their $id fields name:

Where a schema and the service disagree, the service is right and the schema is a bug; please report it with the request id.

Not documented here because it does not exist

There is no OpenAPI file, no client library and no sandbox key for the data API yet. The route references are the complete description. See also the not-available list.