High-Level Workflows

Important Note: Every participant is told what a cross did to their own interest through the JSON-RPCoverWebSockets cross Notification Channel. A Submission is never addressed to a particular cross: it is accepted whenever it arrives, and takes part in every cross that runs while it still has crossings left.

Submit Interest

If you would like to submit interest into the next scheduled cross, you should request the RESToverHTTP [POST] /submissions endpoint.

The request carries the account to settle with, the Legs, how many crosses to stay in, and optionally the venue, the hedge preferences and an idempotency key.

side is the direction of the trade, not of a position you hold on the venue. MPX opens and closes positions alike, and does not read your venue positions.

Read When the Next Crosses Run

If you would like to know when the next crosses run, you should request the RESToverHTTP [GET] /crosses endpoint, optionally with venue to read the crosses of one venue.

It lists the upcoming cutoffs, earliest first, each with its venue and cutoff_at, reaching at most 7 days ahead and at most 64 crosses per venue. The cutoffs are the same for every participant, and a client reads them here rather than deriving them from a cadence, so a cutoff that has been taken back is not listed. A venue MPX does not cross on is refused with error 3611.

Return a Submission

If you would like to read the state of a Submission, you should request the RESToverHTTP [GET] /submissions/{submission_id} endpoint.

The read is where a Submission’s totals live, and is what a client reconciles against. Per Leg it returns quantity (what the Leg offers now, which a reduction lowers), submitted_quantity (what the Leg was submitted with, which a reduction leaves alone), remaining_quantity, pending_quantity (matched and waiting on the venue), available_quantity (what the next cross may offer) and crossings_remaining.

The Submission also carries account_name, the account it settles with, and locked, which says whether a cross holds it. While it is held, locked_reason names the stage: IN_CROSS until the cross has matched, SETTLING while its Block Trade is with the venue, and AWAITING_VENUE when the venue has not answered and is being asked again, which can last hours. It is null when locked is false.

estimated_expiry_at on the Submission is the cutoff at which the last of its Legs is expected to run out of crossings, counted off the cadence in force, so once that cross is within the calendar’s reach it is one of the cutoffs [GET] /crosses lists. It is an estimate and can be null: where nothing is left to expire, where the venue is not crossing, or where a change of cadence makes the count unanswerable.

List Your Submissions

If you would like to read all of your Submissions at once, you should request the RESToverHTTP [GET] /submissions endpoint.

It returns the desk’s own Submissions, newest first, each in the shape [GET] /submissions/{submission_id} returns. Pages follow a cursor: send the next value of one page as cursor to read the following one, and page_size to choose how many Submissions a page holds, up to 100. This is the read a client rebuilds its view from after a reconnect, since the cross Notification Channel cannot be replayed.

• state set to ACTIVE or CANCELLED narrows the list to Submissions in that state.
• live=true narrows it to the Submissions with a Leg still ACTIVE: the interest still waiting to cross or waiting on the venue. A Submission stays ACTIVE after all of its Legs have filled or expired, so state=ACTIVE alone also returns interest that is finished.

Any other value of either parameter is refused with error 3612.

While a Cross Holds Your Submission

From the cutoff that takes a Submission into a cross until the venue has answered for everything the cross took of it, the cross holds the Submission. The fill stands whatever the Legs read, so while the Submission is held, Reduce, Remove and Cancel are refused with error 3609, and the Submission takes no part in the crosses that run meanwhile. A Submission the cross matched nothing for is released as soon as the cross has matched.

locked on the Submission read, on the list and on every cross message says whether it is held, so a client can disable those actions rather than meet the error.

Reduce a Leg

If you would like to offer less on a Leg, you should request the RESToverHTTP [PATCH] /legs/{leg_id} endpoint with the new total.

A reduction keeps the Leg’s place in the queue. The new quantity may not be higher than the current one, may not be below what the Leg has already traded or is waiting on the venue for, and must be a multiple of the instrument’s quantity increment. What the Leg would still offer the next cross, the new quantity less what has traded or is waiting on the venue, must be zero or at least the venue’s minimum Block size, where the venue states that minimum as a quantity. A request that breaks any of these rules is refused with error 3607. To offer nothing, remove the Leg instead.

A Leg that has filled, expired or been withdrawn is refused with error 3608, and a Leg of a Submission a cross holds with error 3609.

Remove a Leg

If you would like to withdraw one Leg while leaving the rest of the Submission standing, you should request the RESToverHTTP [DELETE] /legs/{leg_id} endpoint.

The same rules as a reduction apply: error 3608 for a Leg that has filled, expired or been withdrawn, and error 3609 while a cross holds its Submission.

Cancel a Submission

If you would like to withdraw a Submission entirely, you should request the RESToverHTTP [DELETE] /submissions/{submission_id} endpoint.

A cancel committed before a cross reads its set keeps the interest out of that cross. From that cutoff until the cross has settled what it took, the cross holds the Submission and the cancel is refused with error 3609, so there is no window in which a client can take back quantity a cross has already matched. Canceling a Submission that is already withdrawn is answered as a success.

Cancel All Submissions

If you would like to withdraw every active Submission at once, you should request the RESToverHTTP [DELETE] /submissions endpoint, optionally with account_name to withdraw only the Submissions of one account.

Every ACTIVE Submission it covers is withdrawn in one transaction, each the way a single cancel withdraws one, and the response lists them in cancelled_submission_ids. A Submission a cross holds is skipped rather than failing the request, and listed in locked_submission_ids: it stays ACTIVE, takes no part in the crosses that run while it is held, and can be withdrawn once locked is false. An account_name the desk does not hold is refused with error 3600, so a mistyped account cannot read as a desk with nothing on. As with a single cancel, quantity a cross has already matched still settles.

Return What Your Interest Crossed

If you would like to read what your Legs matched and the hedges your Submissions were given, cross by cross, and what became of them, you should request the RESToverHTTP [GET] /fills endpoint.

This is the catch-up for the cross Notification Channel, which cannot be replayed. Rows come in two kinds, told apart by kind. A LEG row is one of your Legs in one cross, one row per Leg per cross. A HEDGE row is the hedge Add Hedge gave one of your Submissions in one cross, one row per Submission, instrument and side, summed over the counterparties. A hedge belongs to no Leg, so leg_id is null on a HEDGE row and submission_id ties it to the Submission.

On both kinds, matched_quantity is what the cross matched at price, and executed_quantity, returned_quantity and pending_quantity say what became of it and add up to it. A hedge that comes back is not carried: the next cross that matches those Legs sizes a hedge of its own. The window is the cross cutoff and defaults to the last 7 days; a window wider than 31 days is refused.

Nothing on this endpoint names a counterparty, a package or a venue transaction.

Follow a Cross as It Happens

You are able to follow the whole life of your interest with the following steps:

1. Subscribe to the JSON-RPCoverWebSockets Channel cross.
2. Receive one message per Submission per event, with type saying which moment of the cycle the message is about.
3. Reconcile against the RESToverHTTP [GET] /submissions/{submission_id} and [GET] /fills endpoints, and after a reconnect rebuild your view from the [GET] /submissions endpoint.

The channel is scoped to your own desk. A message carries what happened to your own Legs and never your counterparty’s.

Rules Your Interest Has to Obey

• One underlying coin per Submission. Interest on two coins is two Submissions.
• One margin kind per Submission. A coin’s inverse and USDC-linear instruments settle differently and cannot share a Submission, and a hedge preference has to settle the same way as the Legs.
• One Leg per instrument. A second Leg on the same instrument is refused rather than added to the first.
• A Leg below the venue’s minimum Block size is refused at submission, since no cross could settle it. Deribit states its USDC-linear future minimums as a USDC notional, which only the cross’s mark turns into a quantity, so those are applied when the cross runs. In a cross, the minimum is judged on each Block Trade, the option Legs and the futures Legs summed separately and either one enough. A pairing below it is skipped unless both sides asked for Add Hedge, since the hedge can carry it, and a residue below it is finished rather than carried into a cross that could not settle it either.
• Quantities are multiples of the instrument’s increment, on submission and on reduction alike.
• A hedge preference may only be a future or a perpetual on the Submission’s own coin, and may not be an instrument the Submission also trades as a Leg. A Submission asking for a hedge needs at least one option Leg, since a futures-only package has no delta a hedge could neutralize. An empty list is refused; send no list to ask for no hedge.

Retries and Idempotency

An idempotency_key is scoped to your desk. Replaying it returns the original Submission, answered 200 rather than 201, only while that Submission has not been withdrawn and the request still describes the same interest. The same key sent with different interest, or belonging to a Submission that has since been withdrawn, is refused rather than reported as success.