Skip to content

Gateways

A gateway is a separate executable managed by st-server. GatewayManager starts the process, connects to it over loopback TCP, authenticates the connection, sends the provider configuration and monitors runtime health.

During module initialization the server scans immediate child directories of gates/. A directory enters the immutable adapter catalog only when its manifest is valid, its protocol version is supported, and its declared executable passes path and permission checks. Gateway configurations are instances of these adapters: one adapter binary can be started multiple times for different provider accounts. Every instance has independent credentials, port and runtime state.

Gateways can participate in execution routing and can publish quote batches into the server quote pipeline when supported by the selected adapter.

The MT5 adapter advertises QUOTES. Its MT5 Server Plugin subscribes to tick events after its listener starts, filters ticks by the authenticated account's discovered symbols, coalesces repeated updates by symbol and emits bounded batches. The mt5_gateway process forwards these batches unchanged to GatewayManager; mapping and quote-policy checks then run in the normal server quote pipeline.

Live quote timestamps

For every gateway provider, the main server stamps a live QUOTE_BATCH with UTC Unix seconds captured immediately after the complete frame is read from the gateway connection, before quote processing. All quotes in that frame use the same receipt time. The provider's optional timestamp does not determine the active quote timestamp or live candle time and is not stored in a separate provider-time field. No gateway binary or timezone setting needs to change.

The incoming quote fields are symbol (required string), bid and ask (required numbers), volume (optional number, defaults to zero), and timestamp (optional provider timestamp, ignored for live processing). Existing symbol mapping, quote-policy and price checks still apply.

For example, after receiving this batch at UTC Unix second 1791190800:

{"quotes":[{"symbol":"EURUSD.a","bid":1.08451,"ask":1.08463,"volume":0,"timestamp":1791201600}]}

with a mapping to EURUSD, the complete TCP quote event is:

["t","EURUSD",1.08451,1.08463,1791190800]

Event fields are the t discriminator, internal symbol name, bid, ask and UTC timestamp, in that order. The same timestamp is used for live candle bucketing. Historical candle imports retain their supplied timestamps; feeder input is unchanged. Delayed batches receive delivery time, not market-event time. Receipt stamping does not detect stale provider data or turn it into genuinely fresh prices.

Execution affinity and reconciliation

Routing selects an execution venue only when a position is opened. The trade stores execution_gateway_id: 0 means internal execution and a positive value identifies the originating Gateway. Close, partial close, SL, TP and Stop Out must use that stored venue; changing routing does not move an existing position.

When an MT5 position is absent during close, the plugin checks immutable MT5 deal history for matching OUT, OUT_BY or INOUT deals. A confirmed external close is returned as successful execution with code MT5_ALREADY_CLOSED and its provider deal and price. If history cannot prove the requested close, the adapter returns MT5_RECONCILIATION_REQUIRED; the ST position remains open and is not left in a close-request state.

Lifecycle

STOPPED → STARTING → CONNECTING → HANDSHAKING → CONFIGURING
        → PROVIDER_CONNECTING → READY

On a failure the runtime enters CRASHED. When automatic restart is enabled it continues through RESTART_BACKOFF and starts a new child process. DEGRADED means that the process is connected but the provider reported a non-ready state.

All commands require SESSION_ADMIN.

Configuration

Field Type Description
id integer Server-assigned gateway identifier.
name string Unique display name, 1–128 characters.
description string Optional description, up to 512 characters.
type string Adapter type; must match manifest.json.
binary string Executable path relative to the server's gates/ directory.
enabled boolean Whether the gateway may run.
bind_host string Loopback address; currently 127.0.0.1 or ::1.
port integer Optional fixed TCP port. 0 or an omitted field selects a free loopback port for every process start.
provider_config object Complete adapter-specific configuration, including endpoints and credentials when required.
startup_timeout_ms integer Time allowed to establish the gateway connection. Minimum 100 ms.
heartbeat_interval_ms integer Heartbeat interval. Minimum 100 ms.
heartbeat_timeout_ms integer Receive timeout; must exceed the heartbeat interval.
restart_enabled boolean Enables restart after a crash or disconnect.
restart_initial_delay_ms integer Initial restart delay.
restart_max_delay_ms integer Maximum exponential backoff delay.

In the first protocol iteration provider_config is stored as JSON and is returned only through commands restricted to SESSION_ADMIN. Field-level encryption is intentionally deferred to a later protocol revision. The object is sent to the child gateway only after successful bootstrap authentication and must not be written to logs.

Symbol mapping

A quote-producing gateway has separately managed mapping records:

{"gateway_id":3,"provider_symbol":"EUR/USD","source_name":"EURUSD","quote_enabled":true,"execution_enabled":true}

GatewayManager uses the same record in both directions. Incoming QUOTE_BATCH symbols are converted from provider_symbol to source_name when quote_enabled is true. Outgoing execution symbols are converted from SymbolRecord.source to provider_symbol when execution_enabled is true. Matching is exact and case-sensitive. An unmapped symbol passes unchanged.

Both lookup directions are held in the gateway runtime context, so quote and execution processing do not parse mapping JSON or access the database. The normalized quote source name is then resolved through SymbolRecord.source, which may target one or multiple internal symbols.

These records are separate from provider_config and from an adapter's symbols specifications. Adapter symbol entries may still contain subscription, contract-size, volume, and other provider-specific settings, but server-side symbol-name mapping is managed through the dedicated methods. QuotePolicy itself contains only provider identities and does not contain symbol names or wildcard rules.

Mappings are persisted in gateway_symbol_mappings. Mapping writes restart an enabled gateway so the new immutable runtime lookup is installed.

Commands