Skip to main content
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 has cursor, type, reference, occurred_at and payload; meta has next_cursor and has_more. Treat an unknown type as informational.

Read it

  1. Start with no after to read from the oldest event kept, or start=latest to start from now (an empty page whose next_cursor is the head).
  2. Read a page: GET /api/v1/events?after=<cursor>&limit=100. limit is 1 to 500, 100 by default.
  3. Skip any cursor you already processed.
  4. Store meta.next_cursor, not your last event’s cursor: it can move past your last event, even on an empty page.
  5. has_more: true: ask again at once; that page can be empty. false: nothing more now; wait before polling again.
A cursor is opaque. After a 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_at to 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 late order.created shows the order as it is when written.
The feed belongs to your account, not your key: a replacement key reads the same feed.

Recover from a refused cursor

  • 422 invalid_cursor: the feed never issued that after, blank included, or the store was restored under it (in the sandbox, after a reseed). Start over with no after, or start=latest. start and after together, or a bad limit or start, answer 422 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:
    1. Send start=latest and keep its next_cursor.
    2. Rebuild from GET /orders, GET /ledger and GET /withdrawals.
    3. Read on from the cursor of step 1, skipping events already in your rebuild.
The same loop in six languages and four frameworks: Follow events.