API
Errors and limits
What comes back when something is wrong, and what the API does not do to you.
#Shape
One flat field. error is a stable string you can branch on; message is prose for a human and may change. Some errors add a field naming what was acceptable.
{
"error": "unsupported_format",
"supported": ["positions", "activity", "multipliers", "gains", "koinly"]
}#What you can get back
| Status | `error` | Means |
|---|---|---|
401 | unauthorized | Key missing, revoked, or malformed. A session cookie is never accepted here — see below. |
400 | invalid_address | Not a valid EVM address |
400 | address_required | The call needs an address and none was sent |
400 | invalid_date | Dates are YYYY-MM-DD |
400 | unsupported_currency | Not one of the 20 the ECB set publishes |
400 | unsupported_format | Export format is not one of the five; the list comes back with it |
400 | token_required_with_at | at only means something for one token |
400 | unknown_alert_kind | A webhook kinds entry is not an alert kind; the unknown ones come back with it |
400 | url_required | A webhook needs a URL |
400 | invalid_relationship | Resolving an event needs self, exchange, counterparty, or contract |
400 | no_counterparty | That event has nobody on the other side to label |
400 | active_required | The endpoint must be enabled for this |
400 | rejected | The write was refused; message says why |
404 | not_found | No such wallet, event, or endpoint |
404 | no_rate_for_date | No published rate on or before that date |
A cookie will never authenticate this API
/v1/* accepts a bearer key and nothing else. If a session cookie could authorise it, any site you visited could read your portfolio through your own browser. Sending one returns 401 unauthorized, deliberately, and it is tested.
#Rate limits
There are none yet
This page used to publish three tiers — 120 reads a minute, 20 writes, 10 exports a day. None of them was implemented, and a limit you can rely on is worse than no limit if it is imaginary. Be considerate rather than precise for now: reads hit the chain and the SEC behind the scenes, and both of those do rate-limit us.
Do not poll for income
Multiplier accruals are rare and irregular. Register a webhook on the accrued-income kind instead of polling events on a timer — you will hear about it sooner and read far less.