Streaming

Anthid provides real-time broker updates through gRPC streaming. While REST APIs are used for creating intents and querying historical data, the Streaming API delivers live order and position updates as they occur. Streaming allows applications to react immediately to broker activity without polling REST endpoints.

Availability

Streaming is available on all plans. Organizations may maintain multiple concurrent stream connections subject to plan limits. API-key connection limits are resolved from the organization’s billing limits.

Access

Streaming requests must be authenticated and associated with an organization. Client examples use the x-api-key gRPC metadata header. Subscriptions are scoped to trading accounts owned by the authenticated principal’s organization. Every request must name a broker environment, paper or live, and include at least one event type. A request may name one valid trading account UUID in that environment, or omit trading_account_id to subscribe across the organization’s accounts in that environment. API-key callers need paper:intent:read or live:intent:read for the environment subscribed to.

Subscriptions

Once connected, your client can subscribe to message types for a trading account. The subscription messages are defined in protobuf via the proto repository: anthid-labs/proto.

Service Definition

service TradingService {
  rpc StreamEvents(stream StreamEventsRequest)
      returns (stream TradingEvent);

  rpc SubscribeEvents(Subscribe)
      returns (stream TradingEvent);
}

Streaming Models

Anthid supports two streaming patterns.

StreamEvents

A bidirectional gRPC stream intended for backend and native applications. Clients can dynamically subscribe and unsubscribe from trading accounts over an existing connection.

SubscribeEvents

A server-streaming endpoint intended for clients with a fixed subscription. The subscription is established when the request is created and remains active for the lifetime of the stream.

Endpoints

RPC	Request	Response	Use case
`StreamEvents`	Client stream of `StreamEventsRequest` messages	Server stream of `TradingEvent` messages	Dynamic subscribe and unsubscribe over one connection
`SubscribeEvents`	Single `Subscribe` message	Server stream of `TradingEvent` messages	One fixed subscription per stream

Authentication

Streaming requests authenticate with either a Bearer access token or an API key in gRPC metadata. The examples use an API key.

x-api-key: YOUR_API_KEY

authorization: Bearer YOUR_ACCESS_TOKEN

Event Types

Applications can subscribe to one or more event types.

Event Type	Description
EVENT_TYPE_BROKER_ORDER	Real-time order lifecycle updates
EVENT_TYPE_BROKER_POSITION	Real-time position updates
EVENT_TYPE_BROKER_TRADE	Individual executions against an order
EVENT_TYPE_INTENT_ACTION	A command Anthid has committed before the broker responds

Subscription Requests

{
  "trading_account_id": "ACCOUNT_ID",
  "environment": "BROKER_ENVIRONMENT_PAPER",
  "subscriptions": [
    "EVENT_TYPE_BROKER_ORDER",
    "EVENT_TYPE_BROKER_POSITION"
  ]
}

Field	Description
`environment`	Required. `BROKER_ENVIRONMENT_PAPER` or `BROKER_ENVIRONMENT_LIVE`. An unspecified environment is refused with an error event.
`trading_account_id`	A trading account UUID in that environment, or empty for the organization. An account in the other environment is refused.
`subscriptions`	One or more event types.
`order_delivery`	`ORDER_DELIVERY_LIVE` (default) or `ORDER_DELIVERY_PRIMED`.
`instrument_key`, `instrument_class`	Optional instrument filter for a named account.

Leave trading_account_id out, or send it empty, to subscribe to every trading account your organization has in the requested environment. Each event names the account it belongs to, so one stream can carry the whole organization. The organization is taken from the credentials on the request, never from the request body, so this is still only ever your own accounts. The account set is fixed when the subscription is made: an account added afterwards is not included until you subscribe again. An organization with no accounts in the environment is refused. Organization-wide subscriptions are one per environment, so a client can hold paper and live side by side.

{
  "environment": "BROKER_ENVIRONMENT_PAPER",
  "subscriptions": [
    "EVENT_TYPE_BROKER_ORDER",
    "EVENT_TYPE_BROKER_POSITION"
  ]
}

Initial state and live delivery

Event kind	On each subscription
Orders, default or `ORDER_DELIVERY_LIVE`	New updates after attachment
Orders, `ORDER_DELIVERY_PRIMED`	Latest retained snapshot per order, then live updates
Positions	Latest retained snapshot per instrument, then live updates
Trades and intent actions	New events after attachment

Request primed orders when you need to rebuild a view of retained order state:

{
  "trading_account_id": "ACCOUNT_ID",
  "environment": "BROKER_ENVIRONMENT_PAPER",
  "subscriptions": ["EVENT_TYPE_BROKER_ORDER", "EVENT_TYPE_BROKER_POSITION"],
  "order_delivery": "ORDER_DELIVERY_PRIMED"
}

The server sends a primed event with event_type once each requested primed kind has finished its initial delivery, including when there are no retained messages. Positions always receive this marker; orders receive it only with primed delivery. A status confirmation acknowledges the subscription and does not mean initial state is complete. Working orders and nonzero positions remain in current stream state until updated. Terminal-order snapshots and zero-quantity position snapshots expire one hour after publication. Initial snapshots can therefore include recently completed orders and recently flat positions, but not a complete history. Expiry does not emit a public deletion event. Upsert them by order ID and filter by order state for a working-order view. A snapshot is not a new execution. Priming does not replay all historical transitions or provide a resume cursor. Use the ledger to reconcile history beyond retained stream state.

Rebuilding a cached view

Build a fresh snapshot set for each subscription scope. Upsert initial and subsequent messages by order ID or account and instrument, then use the primed marker to complete that kind’s initial view. Merging primed messages into an old cache without removing stale entries can leave orders or positions that expired while disconnected. For a live-only order subscription, reconcile through REST instead. Keep processing live updates during REST reconciliation. Do not let an older REST snapshot overwrite a newer stream update; compare received_at. Page through all results and filter order state for a working-order view. The ledger retains terminal orders after their stream snapshots expire.

Instrument filters

For a named trading account, set instrument_key to narrow orders and positions to an instrument. instrument_class uses lowercase subject values such as equity, unlike REST catalog asset classes such as EQUITY. Leave instrument_class empty to match any class, or specify a class supported by the protobuf model. An instrument class alone does not select an instrument. Until instrument metadata is resolved consistently, specifying a class can exclude otherwise matching updates. Organization-wide subscriptions ignore these filters. Trades and intent actions remain account-scoped even when an instrument filter is set, so filter those payloads in your client if needed.

Unsubscribe

Unsubscribe is only available on the bidirectional StreamEvents RPC.

{
  "trading_account_id": "ACCOUNT_ID",
  "environment": "BROKER_ENVIRONMENT_PAPER"
}

environment is required, as on Subscribe. An empty trading_account_id unsubscribes the organization-wide subscription for the named environment, matching how it was subscribed; the other environment’s subscription stays. It does not cancel the per-account subscriptions, which are separate and are each unsubscribed by name.

Stream Events

The server may emit the following event types.

Heartbeat

Indicates that the connection remains healthy. The server emits heartbeats approximately every 5 seconds.

Status

Returned when a subscription is added or removed successfully. Successful messages are subscribed and unsubscribed.

Error

Returned when a request cannot be processed.

BrokerOrder

Represents a real-time order lifecycle update. Events may include:

New orders
Accepted orders
Partial fills
Filled orders
Cancelled orders
Rejected orders

BrokerPosition

Represents a real-time position update received from a broker. Position updates are emitted whenever Anthid receives a change in account holdings.

BrokerTrade

Represents one execution against an order. An order can fill in many pieces, so this is the fill-by-fill record that BrokerOrder aggregates into filled_quantity and average_price.

Field	Holds
`account_id`, `organization_id`	Which trading account and organization the execution belongs to
`order_id`	The broker’s own order id
`client_order_id`	The platform order id the execution belongs to
`intent_id`	Optional intent the execution belongs to, the same id `BrokerOrder` carries. Absent for executions on orders Anthid did not place, such as a manual trade at the broker
`symbol`, `side`	What traded, and in which direction
`quantity`	Instrument units in this execution, not the order’s cumulative quantity
`price`	Price of this execution, not the order’s average price
`received_at`	When Anthid observed the execution
`exec_id`	Optional broker execution ID; identifies the fill rather than the order
`cumulative_quantity`, `order_quantity`, `leaves_quantity`	Optional order totals as of this execution
`broker_sent_at`	Optional timestamp from the broker’s clock, for reporting
`instrument`	Optional resolved instrument metadata
`command_seq`	Optional sequence of the last command applied to the order when this fill executed

Optional fields depend on the broker and producer. Use the execution’s own totals and command_seq when present: an independently received order update may describe a replacement that raced the fill. An accepted replacement is not necessarily applied yet. Absent command_seq means the applied command is unknown, not zero. Use received_at for local ordering. broker_sent_at is the broker’s reported time and can disagree with other reports of the same event. Keep decimal quantities and prices as strings or exact decimals. Scope execution IDs by account and broker order when deduplicating; an order ID alone cannot distinguish multiple fills.

Subscribe to this only if you need per-fill detail, such as building a VWAP or reconciling against a broker’s execution report. If you want to know how much of an order has traded, read filled_quantity on BrokerOrder, which already aggregates these.

IntentAction

Represents a create, replace, or cancel command Anthid has durably accepted. It is the platform’s account of what it was asked to do, before and independently of any broker response. Internal broker heartbeat events are not forwarded on the public stream.

Connection Lifecycle

Connect to the streaming endpoint.
Authenticate using a Bearer access token or API key.
Subscribe to one or more trading accounts.
Receive status confirmation.
Receive real-time events.
Reconnect and resubscribe if the connection is interrupted.

Streams are connection-oriented. If a stream closes, create a new stream and resubscribe to the required trading accounts.

Reconnecting does not replay every missed event. Orders default to live delivery. Request ORDER_DELIVERY_PRIMED to receive their latest retained snapshots before following live updates. Trades and intent actions are live-only.Positions are always primed. On subscribing you receive the latest retained position for each instrument in scope, then a primed marker and live updates. Treat the initial messages as state rather than as changes that just happened.After any disconnect, reconcile against the ledger’s current endpoints rather than assuming continuity. GET /v1/orders?environment=live and GET /v1/positions?environment=live return the latest known state and are what close the gap. environment is required on both. See Reconciling after a stream disconnect.

Recommended Usage

Use the Streaming API for:

Live order monitoring
Position synchronization
Trading dashboards
Notifications
Automated trading workflows

Use REST APIs for:

Intent submission
Historical queries
Search and filtering
Reporting
Reconciliation workflows

Support

For questions about authentication, request formats, or API behavior, contact support@anthid.com.

Connections

Organizations

Controls

Accounts

Intents

Ledger

Instruments

Stream

MCP

Billing

Availability

Access

Subscriptions

Service Definition

Streaming Models

StreamEvents

SubscribeEvents

Endpoints

Authentication

Event Types

Subscription Requests

Initial state and live delivery

Rebuilding a cached view

Instrument filters

Unsubscribe

Stream Events

Heartbeat

Status

Error

BrokerOrder

BrokerPosition

BrokerTrade

IntentAction

Connection Lifecycle

Recommended Usage

Support

​Availability

​Access

​Subscriptions

​Service Definition

​Streaming Models

​StreamEvents

​SubscribeEvents

​Endpoints

​Authentication

​Event Types

​Subscription Requests

​Subscribe

​Initial state and live delivery

​Rebuilding a cached view

​Instrument filters

​Unsubscribe

​Stream Events

​Heartbeat

​Status

​Error

​BrokerOrder

​BrokerPosition

​BrokerTrade

​IntentAction

​Connection Lifecycle

​Recommended Usage

​Related Resources

​Support

Availability

Access

Subscriptions

Service Definition

Streaming Models

StreamEvents

SubscribeEvents

Endpoints

Authentication

Event Types

Subscription Requests

Subscribe

Initial state and live delivery

Rebuilding a cached view

Instrument filters

Unsubscribe

Stream Events

Heartbeat

Status

Error

BrokerOrder

BrokerPosition

BrokerTrade

IntentAction

Connection Lifecycle

Recommended Usage

Related Resources

Support