Order Book

The books (venue + instrument pairs) the workspace holds, most active first, up to 200. Same item shape as instruments in the summary.

Response Body

The distinct client ids found in your events, busiest (most events) first, each with its linked identity (or null) and its tags. The roster is read from the events: there is no separate client list to maintain.

linked and total describe this page only, not the whole workspace (use GET /v1/orderbook/summary for workspace coverage).

status=matched|unmatched cannot be applied when the workspace has more than 20,000 links. The list is then returned unfiltered with filter_applied: false.

Query Parameters

Response Body

One page of the workspace's events, newest first (ts_event descending, ties broken by order_id then event_id), with the total count behind the filters. Every filter is optional and they are combined with AND.

Amounts are returned as strings so no precision is lost. identities maps each client id on the page that is linked to an identity; unlinked client ids are absent from it.

A filter value that fails its format check (for example a venue with spaces, or an unknown event_type) is ignored rather than rejected.

Query Parameters

Response Body

Validates and stores one batch of up to 1000 rows into a RUNNING import. The whole request must stay under 2 MB; a larger body arrives empty and is answered with a 400 telling you to send fewer rows.

Rows that fail validation are skipped and reported in errors; the others are written. A partial batch is a normal outcome and still returns 200. Only the first 50 rejection messages of a run are kept on the import record; each batch response carries all of its own.

record_shape must match the shape the import was opened with, and the parsing options (timezone, decimal_separator) must be sent on every batch, since the server does not remember them between requests. Set first_row to the file line of the batch's first row so error messages point at the original file.

Re-sending a batch (after a timeout, for example) is safe: event ids are derived from the event content, so duplicates collapse in storage.

Response Body

Closes a RUNNING import as DONE (default) or FAILED, and returns the import record. events_written is then replaced by the number of distinct events the table actually holds for this import, which is lower than the running tally when rows were re-sent or duplicated.

Finishing an import that is no longer RUNNING changes nothing and returns its current record.

Response Body

Opens an import run and returns its import_id. Every batch refers to that id, and the run's record_shape is fixed here: batches declaring another shape are refused.

All fields are optional, but the body must be a JSON object (send {} for the defaults). venue is stored uppercased and is only a label on the run; each row still carries its own venue. profile_id, when given, must be a mapping profile of your workspace and is recorded as the provenance of the mapping.

Response Body

Lists the workspace's import runs, newest first, including rolled-back ones. A run still RUNNING long after its created_at is an upload that was never finished.

Query Parameters

Response Body

Deletes the events written by one import and marks it ROLLED_BACK. The import record is kept (with rolled_back_at and events_removed) as an audit trail. Works on RUNNING imports too, which is how an abandoned upload is undone. Links between client ids and identities are not touched.

Events carry no import in their id: if the same file was imported twice, the stored copy of an event belongs to the later import. Rolling back the earlier one may then remove nothing, and rolling back the later one removes events both imports carried. Re-import the file if that was not intended.

Response Body

Points one of your client ids at an identity, replacing any previous link for that client id (linking a client already held by another identity moves it). Several client ids may point at the same identity, which is how one person trading under several ids becomes visible.

The identity must be visible to your workspace (403 otherwise) and the client id must appear in your stored events (400 otherwise). The change is written to the identity's activity log.

Response Body

Removes the link of one client id. Succeeds even when the client id was not linked.

Query Parameters

Response Body

Lists the workspace's saved mapping profiles, most recently updated first. A profile stores how a feed's columns map to canonical fields so the next import of the same feed does not need to be mapped again.

Response Body

Creates a profile, or overwrites the one with the same name in your workspace (its venue and profile are replaced and its id kept). Returns the id of the stored profile.

profile is a free-form JSON object that your client replays; the server never applies it. Only two keys are checked when present: record_shape must be a valid shape and timezone a valid IANA zone. The serialized profile is limited to 64 KB.

Response Body

Deletes one mapping profile of your workspace. Imports that recorded it keep their history. Answers {"deleted": true} even when no profile with this id exists.

Query Parameters

Response Body

Deletes every order-book event of the workspace and its whole import history. Mapping profiles and client-identity links are kept. This cannot be undone; to undo a single file use POST /v1/orderbook/imports/rollback instead.

To confirm, confirm must equal your workspace's exact tenancy key: the organization name shown by GET /v1/hello (Hello, member of <key>!). In the development workspace that key ends in __dev, so a dev key can only purge dev data.

Admin only: a member, or a key created by a member, gets 403.

Response Body

Returns the canonical fields a row may carry for one record shape, with their type, whether they are required, allowed enum values, header aliases (lowercase names commonly used for the column in exchange exports) and enum synonyms (common spellings mapped to the canonical value).

Fields that only apply to the other shape are left out: ts_submitted appears only for ORDER_SNAPSHOT, ts_event and event_type only for ORDER_EVENT.

Synonyms are a hint for building your column mapping. The server does not apply them: a row must already carry the canonical value (FILLED, not COMPLETED).

Query Parameters

Response Body

Totals for the stored order book, the 50 most active books (venue + instrument), and how many clients are linked to an identity.

coverage.matched counts linked clients that still have events; coverage.stale counts links whose client has no event left (typically after a rollback). When the workspace has more than 20,000 links the intersection is not computed: exact is false, matched is 0, and stale and pct are null.

Response Body

Parses and validates up to 500 rows exactly as an import would, and reports what would be stored. Nothing is written. Use it on a sample of the file before opening an import: it is what catches a wrong timezone or a mis-mapped column before thousands of rows are stored.

Each rejected row produces one message in errors, prefixed with its line number (row N: ..., counted from first_row). profile is built from the rows that parsed, so it shows the distribution that would actually be stored.

A snapshot row expands into one NEW event plus, when its status is terminal, the event that ended it, which is why events_would_write can exceed rows_accepted.

Response Body