GET /api/v1/events (scope events:read) is one feed of what happened on your account, oldest first. Reading it replaces polling every order and your balance.
What is in the feed?
Each item hascursor, type, reference, occurred_at and payload; meta has next_cursor and has_more.
Treat an unknown
type as informational.
Read it
- Start with no
afterto read from the oldest event kept, orstart=latestto start from now (an empty page whosenext_cursoris the head). - Read a page:
GET /api/v1/events?after=<cursor>&limit=100.limitis 1 to 500, 100 by default. - Skip any
cursoryou already processed. - Store
meta.next_cursor, not your last event’s cursor: it can move past your last event, even on an empty page. has_more: true: ask again at once; that page can be empty.false: nothing more now; wait before polling again.
500, ask again with the cursor you hold.
Guarantees
- No gaps. A replay from any cursor shows every later event, in the same order.
- At least once. After a lost answer you read events again: de-duplicate on
cursor. - Feed order is commit order. Use
occurred_atto tell which of two changes came last. - Late events. An event that could not be written at the time is written once, later, with its original
occurred_at. A lateorder.createdshows the order as it is when written.
Recover from a refused cursor
422 invalid_cursor: the feed never issued thatafter, blank included, or the store was restored under it (in the sandbox, after a reseed). Start over with noafter, orstart=latest.startandaftertogether, or a badlimitorstart, answer422 invalid_parameter.410 cursor_expired(details.resync: true): the cursor is older than what the feed keeps. Events are kept unless Mart sets a retention period for your account. Recover in this order:- Send
start=latestand keep itsnext_cursor. - Rebuild from
GET /orders,GET /ledgerandGET /withdrawals. - Read on from the cursor of step 1, skipping events already in your rebuild.
- Send
