Skip to main content

BSL Bulk Operations

Bulk operations let liquidity providers update many quotes with one request while keeping deterministic acknowledgement and retry behavior.

Signed Action Batch​

The current compact path accepts a batch of signed actions:

{
  "version": 1,
  "actions": [
    {
      "payload": {
        "account": "0x1111111111111111111111111111111111111111",
        "nonce": 42,
        "ts": 1781190000000,
        "action": {
          "SpotQuoteReplace": {
            "market": 1,
            "legs": [
              {
                "side": "Bid",
                "price": 999900,
                "qty": 100000,
                "time_in_force": "post_only"
              }
            ]
          }
        }
      },
      "signature": {
        "scheme": "EcdsaSecp256k1",
        "bytes": [1, 2, 3]
      }
    }
  ],
  "idempotencyKey": "btc-quote-refresh-1842"
}

In private beta, submit through the tested route bundle from the Market Maker Beta Quickstart:

POST /api/order-entry/binary
Content-Type: application/x-senticore-order-entry-batch
X-BSL-Result-Mode: ack
X-Senticore-Response-Mode: detailed
Idempotency-Key: btc-quote-refresh-1842

Nonces: Out-Of-Order Pipelining​

Nonces use a windowed replay-protection model. Any unused nonce in [nonceFloor, nonceFloor + nonceWindow) is accepted. Gaps and out-of-order submission are allowed, so concurrent batches may use arbitrary unused in-window nonces.

On nonce reject, use the returned nonceFloor / nonceWindow and choose a fresh unused nonce. Retry only the rejected action (a QuoteReplace is retried as a whole).

Atomicity​

A batch is checked in two stages:

  • frame, auth, timestamp, schema, market-lifecycle/expiry, nonce-window and rate-limit failures reject the whole batch before enqueue (acceptedActions: 0, nothing sequenced, no nonce consumed),
  • after admission each action is applied on its own: an action that fails in the engine (unfunded ask, below-minimum notional, price above 1.000, tick/lot) is dropped with receipt status: dropped, applied: false, and other actions in the batch are unaffected. A QuoteReplace is one action, so one failing leg drops all its legs, bids included — see Batch atomicity,
  • admitted actions enter the normal sequencer path,
  • terminal state is reconciled from streams, drop-copy, account reads, or receipts where provisioned,
  • QuoteReplace and SpotQuoteReplace are the preferred quote-refresh actions.

Cancel and Replace​

Use QuoteReplace or SpotQuoteReplace legs with cancel_order_id when you want to remove stale quote legs and place new quote legs in one signed action. A leg with cancel_order_id and qty: 0 is cancel-only. A leg without cancel_order_id is place-only.

Legacy facade routes still exist:

POST /api/v1/mm/orders/replace
POST /api/v1/mm/orders/cancel-replace

Use those only when the client is already wired to the compatibility facade.

Idempotency​

Use both Idempotency-Key and idempotencyKey in the body for retriable batches. Retrying the same key should return the existing response when the request hash matches. If the request body changes under the same key, reconcile before submitting new risk.

Last updated on