> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anthid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Streaming

> Receive real-time order and position updates through Anthid's gRPC streaming APIs.

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. Subscribe requests must include a valid trading account UUID and at least one event type.

## 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](https://github.com/anthid-labs/proto/).

## Service Definition

```proto theme={null}
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 account subscription per stream             |

## Authentication

Streaming requests must include an API key using gRPC metadata.

```text theme={null}
x-api-key: YOUR_API_KEY
```

## 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        |

## Subscription Requests

### Subscribe

```json theme={null}
{
  "trading_account_id": "ACCOUNT_ID",
  "subscriptions": [
    "EVENT_TYPE_BROKER_ORDER",
    "EVENT_TYPE_BROKER_POSITION"
  ]
}
```

### Unsubscribe

`Unsubscribe` is only available on the bidirectional `StreamEvents` RPC.

```json theme={null}
{
  "trading_account_id": "ACCOUNT_ID"
}
```

## 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.

Broker trade events and internal broker heartbeat events are not forwarded on the public stream.

## Connection Lifecycle

1. Connect to the streaming endpoint.
2. Authenticate using an API key.
3. Subscribe to one or more trading accounts.
4. Receive status confirmation.
5. Receive real-time events.
6. 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.

## 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

## Related Resources

* Node.js Guide
* Python Guide
* Rust Guide
* Intents
* Orders
* Positions
* Trading Accounts
* Ledger

## Support

For questions about authentication, request formats, or API behavior, contact [support@anthid.com](mailto:support@anthid.com).