Skip to main content

BSL API

BSL is the Business Line interface for latency-sensitive order entry. It is the client contract for professional quoting, cancel/replace, execution replay, and session controls. The older market-maker and binary names remain as compatibility routes, but new integrations should use BSL names and headers.

BSL is not a separate matching engine. Orders still pass through the same auth, risk, sequencing, WAL, matching, event ring, and recovery model as the rest of the venue. The difference is that the interface exposes that hotpath truth directly instead of hiding it behind read-plane polling.

Core Endpoints​

EndpointPurpose
POST /api/v1/bsl/orders/batchJSON signed action batch with explicit result mode
POST /api/v1/bsl/orders/compactCompact byte batch for latency-sensitive clients
POST /api/v1/bsl/orders/replaceAtomic cancel/new replace facade
POST /api/v1/bsl/orders/cancel-replaceAlias for replace-style order flow
GET /api/v1/bsl/receiptsReceipt and acknowledgement replay
GET /api/v1/bsl/limitsCurrent BSL rate, batch, backlog, and lane limits
GET /api/v1/bsl/sessionsAuthenticated BSL session state
POST /api/v1/bsl/sessions/cancel-on-disconnectStale-order cleanup trigger
GET /api/v1/bsl/markets/{marketId}/quote-obligationsTwo-sided quote obligation state
GET /api/v1/bsl/executionsExecution stream contract metadata
GET /api/v1/bsl/accounts/{account}/executions?fromSeq=...Private execution gap-fill
GET /api/v1/ws/bsl/{account}Private execution stream over WebSocket

Result Modes​

BSL result mode is selected with x-bsl-result-mode or the JSON resultMode field.

ModeMeaningUse
ackSequencer accepted the request boundary.Quote refreshes where stream reconciliation is primary.
durableWAL/durable LSN boundary reached.Slower control flows where persistence acknowledgement matters.
fullEngine-applied result returned from the hotpath.IOC/FOK, cancel, replace, and any flow where the client needs the terminal result immediately.

full responses include actionResults when the request reaches the engine. Each result includes the client order id, order id, status, filled quantity, leaves quantity, average price, fee, reject code, market, shard, seq, and engine timestamps when available.

Response Contract​

Every BSL JSON response carries a bsl object:

{
  "bsl": {
    "contract": "BSL_ORDER_ENTRY_V1",
    "contractVersion": 1,
    "surface": "orderEntry",
    "transport": "json",
    "requestedResultMode": "full",
    "resultMode": "full",
    "streamTruth": "engine_execution_ring",
    "privateWsPath": "/api/v1/ws/bsl/{account}",
    "executionReplayPath": "/api/v1/bsl/accounts/{account}/executions?fromSeq={seq}",
    "rejectCode": null,
    "timing": {
      "gatewayReceivedTs": 1781715570085,
      "authDoneTs": 1781715570085,
      "riskDoneTs": 1781715570085,
      "sequencedTs": 1781715570085,
      "engineAppliedTs": 1781715570086,
      "durableTs": null,
      "responseSentTs": 1781715570086,
      "durationsUs": {
        "total": 1072,
        "auth": 3,
        "routing": 12,
        "risk": 0,
        "enqueue": 0,
        "ackResolution": 0,
        "responseEmit": 58
      }
    }
  }
}

Compact byte responses expose the same contract through x-bsl-* headers.

Fast Rejects​

BSL clients should treat fast rejection as healthy backpressure. A quick reject is better than letting a quote age silently in an overloaded queue.

Stable BSL reject codes include:

CodeMeaning
SHARD_BUSYThe target market shard is overloaded.
QUEUE_LIMITThe BSL lane or ingress queue is full.
RISK_CREDIT_LIMITRisk or credit policy blocked the action.
KILL_SWITCHAccount, market, or venue kill-switch is active.
MARKET_HALTEDMarket state does not allow the requested action.
AUTH_REQUIREDMissing or invalid BSL credentials.
PERMISSION_DENIEDCredential lacks the requested scope.
DUPLICATE_OR_STALENonce, idempotency, or duplicate replay state rejected the request.
INVALID_REQUESTFrame, schema, or request payload is invalid.