Skip to main content

Sharded Routing

A Sparky deployment can run as several pods with symbol ownership sharded across them: each symbol's matching engine lives on exactly one pod. This is invisible to clients, but worth knowing when debugging latency or batch behaviour.

How it works​

  • You connect to one fixed base URL; the edge gateway distributes requests across pods.
  • Read paths (market data, queries) are served by any pod.
  • Write paths for a symbol owned by another pod — new order, cancel, modify, cancel-all, batch cancel — are forwarded over HTTP to the owner pod. The original query string and therefore your HMAC signature are preserved unchanged; an internal marker header prevents forwarding loops.
  • If the ownership map is in flux (hash drift during scale-out) the receiving pod handles the request locally as a degraded fallback and logs a warning; the request is never dropped.
  • When sharding is disabled (default single-pod deployments) everything is local.

Consequences​

SituationEffect
Single order on a symbol owned elsewhereForwarded; adds one intra-cluster hop of latency
POST /fapi/v1/batchOrders / PUT …/batchOrdersThe batch is pinned to the receiving pod; non-owned symbols run as the degraded local fallback. Keep batches single-symbol on sharded deployments.
Forwarding failure-1001 DISCONNECTED (HTTP 500); safe to retry with the same newClientOrderId (duplicate active ids are rejected with -2014, so you cannot double-place).

Nothing about sharding changes request signing or the response shape.