Siebly.ioSiebly.io - Cryptocurrency Exchange SDKs
Reference

Trading System Glossary

Shared terms for execution modes, testing environments, WebSockets, exchange state, runtime workflows, and durable order context.

EXECUTION_MODE=DRY_RUN_PRIVATE

The single runtime switch that separates public, read-only, dry-run, demo, testnet, and live behavior.

PUBLIC

Public-only mode. It uses no API keys, creates no private clients, and cannot build or submit exchange write requests.

DEMO

Write-capable mode for an exchange-supported demo or sandbox venue. It must fail closed if the selected exchange or product does not support that venue. Usually requires dedicated API keys that only work in the demo environment.

TESTNET

Write-capable mode for an exchange-supported testnet venue. It must not silently route to production.

READ_ONLY_PRIVATE

Private credentials may read account, order, fill, balance, native position, or local position-derivation state, but cannot mutate exchange state.

DRY_RUN_PRIVATE

The default order-capable mode. Private state may be read, and final order requests are built and logged without submitting to the exchange.

  • This is not paper trading. It does not imply simulated fills, balances, positions, or PnL.
  • This mode should still process incoming account state events so local state stays in sync with exchange state.
LIVE

Production write-capable mode. It requires explicit configuration, scoped credentials, review gates, confirmation handling, recovery behavior, tests or fixtures, and operator acknowledgement.

Testing Environments

Paper Trading

A local simulation mode that models intended orders, fills, balances, positions, fees, and PnL without real exchange writes.

  • Paper trading is the local simulation of fills & balance changes based on available market data.
  • Paper trading needs its own fill, balance, position, fee, and PnL model. It is separate from dry-run request planning and does not replace demo, testnet, or live exchange-state testing.
  • Agents should not build paper trading unless it is explicitly asked for by the prompt/user.

Demo Trading

An exchange-supported simulated trading venue for testing order flows, private streams, and account-state handling when the selected exchange supports it.

  • Demo trading is not available on every exchange or product. If unsupported, the system should fail closed when demo mode is selected.

Testnet

Also: CEX testnet, testnet

An exchange-operated sandbox with fake funds in fake markets, useful for API and integration testing without risking real money.

  • Testnet order books are not real-money markets
  • They are simulated environments with fake money and cannot be used to evaluate the performance of a trading strategy.
  • Use testnet for API integration, order formatting, and workflow checks without risking real funds.
  • To evaluate strategy performance, use historical backtesting, paper trading with real market data (simulate your own fills) or, if the exchange supports it, demo trading.

Validation Artifacts

Conformance Pack

Also: conformance packs, fixture pack, validation pack

A versioned, machine-readable set of behavior-contract fixtures, expected outcomes, and runner requirements for a generated integration.

  • Use conformance packs after the implementation shape exists. They are validation fixture sources, not first-read design prose.
  • A pack may include fixture metadata, expected planner outputs, golden traces, failure log markers, execution-mode gates, schemas, and runner requirements.
  • Applicable fixtures are the checks relevant to the selected exchange, product, execution mode, and feature scope. Unsupported cases should be recorded as explicit non-claims instead of silently ignored.

Behavior-Contract Fixture

Also: behavior-contract fixtures, conformance fixture, conformance fixtures, validation fixture, fixture check

An executable or replayable validation scenario that proves integration behavior from inputs through expected state, logs, blocks, and forbidden actions.

  • A behavior-contract fixture should be precise enough to become a local test, replay case, or harness scenario.
  • It should include the relevant initial state, input events or REST snapshots, expected state transitions, expected logs or counters, expected blocks, and forbidden actions.
  • Applicable fixtures are the checks relevant to the selected exchange, product, execution mode, and feature scope. Unsupported cases should be recorded as explicit non-claims instead of silently ignored.

WebSockets

WsKey

Also: WS_KEY_MAP, wsKey, WebSocket key, websocket connection key

A WebsocketClient lookup key used by each SDK to track state for one WebSocket connection family.

  • Every SDK WebsocketClient uses WsKey values as unique keys for persisting context around individual WebSocket connections, such as connection state, subscribed topics, authentication state, active workflows (& workflow locks), and related per-connection bookkeeping.
  • Each SDK exports a WS_KEY_MAP enum as the clear reference for the WsKey values available in that package.
  • Different SDKs have different WsKey values because exchanges split WebSocket endpoints differently.

Subscription Acknowledgement

Also: subscription ack, exchange acknowledgement, subscribe acknowledgement

Exchange-visible evidence that a specific WebSocket subscription request or topic was accepted.

  • A socket open event, sent subscription request, or local subscribe() return is not subscription acknowledgement by itself.
  • Use the package-specific acknowledgement event and match the selected topic, channel, request id, or success payload required by the exchange.
  • A Readiness Gate may require subscription acknowledgement before backfill replay, live-processing enablement, or downstream workflow side effects can run.

Readiness Gate

Also: readiness, live readiness, workflow readiness, live-processing gate

A runtime latch that prevents downstream work until the required subscriptions, acknowledgements, REST hydration or backfill, buffered replay, and state-trust prerequisites are complete.

  • A WebSocket open event or subscribe() return is not a readiness gate by itself. Verify Subscription Acknowledgement separately when the workflow depends on a subscribed stream.
  • For historical backfill plus live streams, readiness gates usually include subscription acknowledgement, historical backfill, buffered replay, and live-processing enablement.
  • For private account-state workflows, readiness depends on the subjects needed by the next action, such as order trust, position trust, asset trust, filters, or durable context.

Exchange State

Account State

Also: account state cache, account state store, accountstate

The local account-state store used for planning. It tracks orders, fills, positions, balances, filters, and durable context, with trust tracked per subject. After startup, healthy private WebSocket events should keep the store current without routine REST polling.

Ingest

REST hydration

Startup, reconnect, and scoped recovery fill missing state.

Private WebSocket events

The normal running path keeps state current.

Account State

Orders, fills, positions, balances, filters, and context.

Trust is tracked by subject.

Consume

Planner / risk / submitter

Reads trusted state before choosing actions.

Exchange write adapter

Places, amends, or cancels orders only after workflow checks pass.

Startup and Reconnect

  • Subscribe to private account streams and apply incoming events to the local account state store.
  • Use startup REST hydration as needed to fill gaps that would prevent planning or reconciliation from private events alone.
  • After reconnect, refresh the affected account state with scoped REST hydration, then return to the event-driven workflow.

Normal Running Path

  • Once the system is running, private events are the normal source for keeping account state current.
  • Do not rely on REST polling after startup when private events are healthy and complete enough for the affected scope.
  • If private events stop, conflict, or leave required state unresolved, use scoped REST hydration to recover and return to private-event-driven state.

Subject Trust

  • Order, fill, position, balance, filters, and durable context can each have different trust status.
  • Native futures or perpetual position rows can use private position updates for position trust.
  • Spot products, or products without native position rows, need fills/executions, fees, account events, and documented matching rules to derive local position state.
  • Use REST hydration at startup, reconnect, recovery, or conflict boundaries. Do not poll REST during normal running when private events are healthy.

Position

Also: position state, native position, local position, spot position

The product, symbol, side, size, entry or cost basis, and exposure state that a trading system manages. It can be exchange-native or locally derived.

  • Derivatives exchanges often provide native position rows. In that case, private position updates and scoped REST hydration can populate local position state.
  • Spot products usually do not provide native position rows. A system can still maintain position state by replaying fills/executions, fees, account events, balance updates, and documented matching rules.
  • Balances are evidence and reconciliation input, not the position concept itself. A position manager should plan from trusted position state, whether the position was exchange-managed or locally derived.
  • A trusted size change can trigger managed-order updates such as TP, SL, or DCA replacement.

Trusted State

A subject-specific state view that is current enough to plan from. Order, position, market data, filters, and durable context can each have different trust status.

  • Trust is a per-workflow threshold. A fast-moving workflow may accept bounded uncertainty; a slower workflow may wait for stronger evidence before planning.
  • Use REST hydration at startup, reconnect, recovery, or conflict boundaries. Healthy private events should carry the normal running path.
  • Many systems can function purely with position updates, if available, for position trust.
  • Trusted state should not time out if streams are healthy.

Order Trust

Evidence that an app-owned order is active, terminal, absent, filled, rejected, or still pending. REST acceptance alone is not order trust.

  • Matching WebSocket order events can establish order state. REST submit responses are provisional because they do not prove exchange execution or later terminal state.
  • If app-owned order state is unclear, one recovery tactic is to cancel app-owned orders for the affected symbol and side, then reset expected orders from trusted account state.
  • Cancelling unowned manual orders must remain opt-in. Cancel-and-reset requires order events, durable context, and ownership proof.

Position Trust

Evidence that position state has updated and can be used for size, entry or cost basis, exposure, and dependent replacement planning.

  • Some exchanges have native position rows that can be used for position trust. When available, private position updates are the best source for position trust.
  • If the product has no native position row, derive local position state from fills/executions, fees, account events, balance updates, and documented matching rules. Balance events help reconcile that local state, but they do not replace the derived position state.
  • Position state should not time out if streams are healthy. Use REST hydration at startup, reconnect, or recovery boundaries, not as routine polling.

Asset Trust

Also: balance, wallet, assets, position reconciliation balance

Balance or wallet evidence used for account reconciliation. Track whether private events update it, whether it includes PnL, and how it reconciles with position state.

Private Stream Confirmation

Also: private stream reconciliation, private confirmation, user data stream confirmation

Private order, fill, balance, wallet or position evidence that confirms what happened after a submitted request or external account event.

  • Confirmations can arrive for different subjects at different times. Order evidence may arrive before fill, balance, wallet, or position evidence.
  • Use matching private events first when planning dependent actions.
  • If private confirmation is missing, use scoped REST hydration to repair the affected state. Do not poll REST during normal running when private events are healthy and complete enough for the affected scope.

Pending Confirmation

Also: ACK, acknowledgement, accepted but pending confirmation

A state after request acceptance where the system has evidence that the exchange received a command, but not enough evidence to plan dependent actions.

Durable Context

Persisted local intent/order metadata keyed by Custom Order ID and scope. It lets the app recover order meaning after retries, restarts, and private events.

  • Store local order meaning here, not in exchange-visible lookup fields.
  • Write the context before submission. Use it later for planning and reconciliation when the order is filled, partially filled, rejected, or canceled.

Order Intent

Also: OrderIntent, order-intent, parent intent

A local app-level request to execute an approved entry, exit, or order action. Strategy or risk code creates it; an execution adapter turns it into one or more exchange order requests.

  • Created by a strategy, operator, or risk layer before an execution adapter sees it.
  • It should carry the product, symbol, side, role, quantity, price or slippage bounds, time limits, execution mode, and risk approval needed to build bounded child order requests.
  • Execution adapters may turn one order intent into one or more child order requests.

App-Owned Order

An exchange order that the application can prove it created or explicitly adopted, with matching local durable context.

Custom Order ID

Also: client order ID, custom client order ID, opaque client order ID, exchange-visible order ID, newClientOrderId, clientAlgoId, orderLinkId

This is a user-provided property to define a custom order ID value before an order is sent to the exchange.

  • Examples include Binance newClientOrderId, Binance USD-M Algo clientAlgoId, and Bybit orderLinkId.
  • Do not store state within this property. Keep it short, random, and unique enough to be a lookup key for local state store.
  • Use `generateNewOrderID()` to create a random ID that satisfies exchange rules, especially on Binance & HTX.
  • Do not store state in the custom order ID field. Keep strategy/system state locally instead. Use Custom Order IDs as a randomised lookup key for that local state.
  • Keep product, symbol, role, side, step, order kind, lifecycle, generation, recovery state, and other strategy state out of the ID text.

Workflow

  • Plan the order from trusted local state and create the order intent or child-order context.
  • Generate one random Custom Order ID that satisfies exchange prefix, length, and character rules.
  • Before submit, store product, symbol, side or position identity, role, step, order kind, request summary, local generation or parent intent when needed, and pending action in durable local order context.
  • Submit the exchange order with that ID and mark the local context pending confirmation.
  • On REST response or private order, execution, or fill event, look up the context record by echoed ID and update local state.
  • Unknown ID: treat it as external or unresolved unless explicit adoption is configured. Do not parse meaning from the string.

Local Store

  • Store context in a local order-context table that survives retries and restarts. The exchange-visible ID only points to that record.
  • For a small runtime, keep the table beside account state. Larger runtimes can use SQLite, Postgres, Redis, or another durable store.
  • Use one context record per attempted exchange order. Index by custom order ID plus the local account, product, or symbol scope when an exchange can reuse IDs across scopes.

Exchange Boundary

  • Use exchange-specific prefixes, length limits, and character sets as formatting constraints only.
  • Do not add a custom ID when the workflow does not need to correlate later exchange events with local context.
  • If the local context write fails, fail closed and do not submit the exchange order.

Runtime Workflows

Safe Command

Also: safe commands, diagnostic command, verification command

A diagnostic, inspection, verification, or readback command that must force PUBLIC or READ_ONLY_PRIVATE behavior and cannot inherit a write-capable EXECUTION_MODE from the environment.

  • Examples include doctor, inspect, status, and readback commands.
  • Safe commands may read configuration or public/read-only exchange state, but they must not place, amend, cancel, borrow, transfer, lever, or otherwise mutate exchange state.

Risk Gate

Also: risk check, risk limit, safety gate, kill switch

A deterministic condition that blocks a signal, order intent, order submission, replacement, or startup path when market, account, exposure, loss, stream, or operator-stop conditions are unsafe.

  • Risk gates include stale-data stops, sequence-gap blocks, spread or slippage limits, exposure and notional limits, daily loss limits, reject-rate limits, rate-limit pressure, and explicit operator stops.
  • A kill switch is a hard risk gate. It should block the affected workflow before any exchange write can be sent.

Readiness Gate

Also: readiness, live readiness, workflow readiness, live-processing gate

A runtime latch that prevents downstream work until the required subscriptions, acknowledgements, REST hydration or backfill, buffered replay, and state-trust prerequisites are complete.

  • A WebSocket open event or subscribe() return is not a readiness gate by itself. Verify Subscription Acknowledgement separately when the workflow depends on a subscribed stream.
  • For historical backfill plus live streams, readiness gates usually include subscription acknowledgement, historical backfill, buffered replay, and live-processing enablement.
  • For private account-state workflows, readiness depends on the subjects needed by the next action, such as order trust, position trust, asset trust, filters, or durable context.

Event-Driven Workflow

An architecture where private events drive the main workflow.

  • If initial state is synchronized on startup, and private events are healthy and complete enough for the affected scope, then the system can rely on private events to drive the main workflow.
  • In this architecture, the normal running path is private event -> Account State update -> affected scope -> event-burst wait -> one action family -> approved exchange mutation(s) -> private confirmation or scoped recovery.

Affected Scope

The smallest account, product, symbol, side, or position scope that changed and needs reconciliation.

  • Private events, startup hydration, reconnect repair, and recovery should record affected scopes instead of triggering broad account-wide replanning by default.
  • A precise affected scope helps the workflow owner reconcile only the work that changed while still allowing bounded fallback scopes when an event is ambiguous.

Event Burst Wait

A short bounded delay after applying private events to account state, used to give related order, fill, position, and wallet events time to arrive before planning.

  • The delay is not a reason to postpone account-state ingestion; events should still update local state immediately.
  • It is also not a reason to call REST. REST hydration remains for startup, reconnect, missing prerequisites, unknown outcomes, conflicts, and explicit recovery.

Workflow Owner

The single runtime owner that drains affected scopes and serializes replay, planning, submission, and follow-up reconciliation for a product or account.

  • Timers, private events, reconnect handlers, and startup hooks can all schedule work, but only one owner should run the state-to-action workflow for the same product or account at a time.
  • When work is already active, later triggers should record bounded follow-up reasons instead of starting overlapping planners or duplicate submitters.

Action Family

The one kind of action a reconciliation pass chooses before letting account state settle again: recovery, cleanup, protective, DCA, noop, or blocked.

  • Choosing one action family per pass keeps recovery, cleanup, protection, exposure-increasing work, and waiting states from being mixed against stale account state.
  • A later pass can run after private confirmation, scoped recovery, or trusted state change requeues the affected scope.

REST Hydration

A scoped REST read that initializes or repairs local state. It is for startup, reconnect, missing prerequisites, unknown outcomes, or conflicting evidence, not healthy-event polling.

  • A healthy connected system only uses REST hydration for startup or reconnect.
  • Private WebSocket events should be sufficient from there to keep local state in sync with exchange state.
  • Use scoped REST hydration when private events stop, conflict, or leave a required subject unresolved. Healthy private events should carry the normal running path.

Scoped Recovery

A bounded state repair for the affected account/product/symbol/side scope after reconnect, timeout, unknown outcome, missing prerequisites, or conflicting evidence. For app-owned order uncertainty, this can include cancelling owned orders for the affected scope, then resetting expected orders from trusted account state.