Node.js

Anthid provides Protocol Buffer definitions that can be used to generate Node.js clients for the Streaming API. This guide demonstrates connecting to the Streaming API and receiving real-time broker order and position updates.

Prerequisites

Install the required dependencies.

npm install @grpc/grpc-js @grpc/proto-loader

Download the Protobuf Definitions

git clone https://github.com/anthid-labs/proto.git anthid-proto

Load the Proto Definitions

const grpc = require("@grpc/grpc-js");
const path = require("node:path");
const protoLoader = require("@grpc/proto-loader");

const protoRoot =
    path.resolve("anthid-proto");

const packageDefinition =
    protoLoader.loadSync(
        path.join(
            protoRoot,
            "trading",
            "trading_service.proto",
        ),
        {
            includeDirs: [protoRoot],
            keepCase: false,
            longs: String,
            enums: String,
            defaults: true,
            oneofs: true,
        },
    );

const proto =
    grpc.loadPackageDefinition(
        packageDefinition,
    );

const trading = proto.trading;

Authentication

Streaming requests authenticate with either a Bearer access token or the x-api-key metadata header. This guide uses an API key.

const metadata = new grpc.Metadata();

metadata.add(
    "x-api-key",
    "YOUR_API_KEY",
);

The SubscribeEvents endpoint provides a server-streaming interface suitable for most applications.

const grpc = require("@grpc/grpc-js");
const path = require("node:path");
const protoLoader = require("@grpc/proto-loader");

const protoRoot =
    path.resolve("anthid-proto");

const packageDefinition =
    protoLoader.loadSync(
        path.join(
            protoRoot,
            "trading",
            "trading_service.proto",
        ),
        {
            includeDirs: [protoRoot],
            keepCase: false,
            longs: String,
            enums: String,
            defaults: true,
            oneofs: true,
        },
    );

const proto =
    grpc.loadPackageDefinition(
        packageDefinition,
    );

const client =
    new proto.trading.TradingService(
        "stream.anthid.com:443",
        grpc.credentials.createSsl(),
    );

const metadata =
    new grpc.Metadata();

metadata.add(
    "x-api-key",
    "YOUR_API_KEY",
);

const stream =
    client.SubscribeEvents(
        {
            tradingAccountId:
                "YOUR_TRADING_ACCOUNT_ID",
            environment: "BROKER_ENVIRONMENT_PAPER",
            subscriptions: [
                "EVENT_TYPE_BROKER_ORDER",
                "EVENT_TYPE_BROKER_POSITION",
            ],
        },
        metadata,
    );

stream.on("data", (event) => {
    if (event.heartbeat) {
        console.log("heartbeat");
    } else if (event.status) {
        console.log(
            "status:",
            event.status.message,
        );
    } else if (event.error) {
        console.log(
            "error:",
            event.error.message,
        );
    } else if (event.primed) {
        console.log("initial state complete:", event.primed.eventType);
    } else if (event.brokerOrder) {
        console.log(
            "order:",
            event.brokerOrder,
        );
    } else if (event.brokerPosition) {
        console.log(
            "position:",
            event.brokerPosition,
        );
    }
});

stream.on("error", (error) => {
    console.error(error);
});

stream.on("end", () => {
    console.log(
        "stream disconnected",
    );
});

Bidirectional Streaming

Backend and long-running services can use StreamEvents to dynamically subscribe and unsubscribe from accounts over an existing connection.

const stream =
    client.StreamEvents(
        metadata,
    );

stream.write({
    subscribe: {
        tradingAccountId:
            "YOUR_TRADING_ACCOUNT_ID",
        environment: "BROKER_ENVIRONMENT_PAPER",
        subscriptions: [
            "EVENT_TYPE_BROKER_ORDER",
            "EVENT_TYPE_BROKER_POSITION",
        ],
    },
});

stream.on("data", (event) => {
    console.log(event);
});

With keepCase: false, request and response fields use camel case: tradingAccountId, environment, orderDelivery, and event.primed.eventType. environment is required on every subscribe and unsubscribe request: "BROKER_ENVIRONMENT_PAPER" or "BROKER_ENVIRONMENT_LIVE", matching the account’s environment. Set orderDelivery: "ORDER_DELIVERY_PRIMED" on the subscribe request to receive retained order snapshots first. Wait for the order primed event before treating that initial delivery as complete. Terminal orders and zero-quantity positions expire from retained stream state after one hour. Rebuild a fresh snapshot set on reconnect so an old cache does not retain entries that no longer replay. See Rebuilding a cached view.

Unsubscribe

To stop receiving events for an account, send an unsubscribe request on the same stream.

stream.write({
    unsubscribe: {
        tradingAccountId:
            "YOUR_TRADING_ACCOUNT_ID",
        environment: "BROKER_ENVIRONMENT_PAPER",
    },
});

Handling Disconnects

Applications should automatically reconnect when a stream closes unexpectedly. After reconnecting:

Create a new stream.
Authenticate using a Bearer access token or API key.
Re-subscribe to required trading accounts.
Resume event processing.

TypeScript

The same approach works in TypeScript. Many teams choose to generate strongly typed TypeScript definitions from the Anthid protobuf files during their build process rather than loading protobuf definitions dynamically at runtime.

Streaming Overview
Python Guide
Rust Guide
Trading Accounts
Orders
Positions
Ledger
Intents

Connections

Organizations

Controls

Accounts

Intents

Ledger

Instruments

Stream

MCP

Billing

Prerequisites

Download the Protobuf Definitions

Load the Proto Definitions

Authentication

Bidirectional Streaming

Unsubscribe

Handling Disconnects

TypeScript

​Prerequisites

​Download the Protobuf Definitions

​Load the Proto Definitions

​Authentication

​Subscribe to Events

​Bidirectional Streaming

​Unsubscribe

​Handling Disconnects

​TypeScript

​Related Resources

Prerequisites

Download the Protobuf Definitions

Load the Proto Definitions

Authentication

Subscribe to Events

Bidirectional Streaming

Unsubscribe

Handling Disconnects

TypeScript

Related Resources