topstepx-api

A framework-agnostic TypeScript client for the TopstepX trading API with REST and SignalR data feeds via WebSocket.

Features

Full REST API coverage (accounts, orders, positions, trades, contracts, history)
Real-time WebSocket data via SignalR (quotes, trades, market depth)
Automatic token management and refresh
TypeScript-first with complete type definitions
Works with any Node.js framework (Express, Fastify, NestJS, etc.)
Dual ESM/CommonJS support

Installation

npm install topstepx-api

Environment Setup

Create a .env file in your project root:

TOPSTEP_USERNAME=your_username
TOPSTEP_API_KEY=your_api_key

Get your API key from your TopstepX account settings.

Quick Start

import { TopstepXClient, OrderTypeEnum, OrderSideEnum } from 'topstepx-api';

const client = new TopstepXClient({
  username: process.env.TOPSTEP_USERNAME!,
  apiKey: process.env.TOPSTEP_API_KEY!,
});

await client.connect();

// Get accounts
const response = await client.accounts.search({ onlyActiveAccounts: true });
console.log('Accounts:', response.accounts);

// Place a market order
const order = await client.orders.place({
  accountId: response.accounts[0].id,
  contractId: 'CON.F.US.ENQ.M25',
  type: OrderTypeEnum.Market,
  side: OrderSideEnum.Buy,
  size: 1,
});
console.log('Order placed:', order.orderId);

// Disconnect when done
await client.disconnect();

API Reference

TopstepXClient

The main client class that provides access to all APIs.

Constructor

const client = new TopstepXClient({
  username: string;          // Required: TopstepX username
  apiKey: string;            // Required: TopstepX API key
  baseUrl?: string;          // Optional: API base URL (default: https://api.topstepx.com)
  marketHubUrl?: string;     // Optional: Market WebSocket URL
  userHubUrl?: string;       // Optional: User WebSocket URL
  autoRefresh?: boolean;     // Optional: Auto-refresh tokens (default: true)
  tokenValidityHours?: number; // Optional: Token validity period (default: 24)
});

Methods

Method	Description
`connect()`	Authenticate and establish WebSocket connections
`disconnect()`	Close all connections and cleanup
`getToken()`	Get the current session token
`isConnected`	Check if WebSocket connections are active

Events

client.on('connected', () => console.log('Connected'));
client.on('disconnected', () => console.log('Disconnected'));
client.on('error', (error) => console.error('Error:', error));

Accounts API

Access via client.accounts

search

Search for accounts.

const response = await client.accounts.search({
  onlyActiveAccounts: boolean;
});

// Returns: SearchAccountsResponseInterface
interface SearchAccountsResponseInterface {
  accounts: AccountInterface[];
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

interface AccountInterface {
  id: number;
  name: string;
  canTrade: boolean;
  isVisible: boolean;
}

Orders API

Access via client.orders

place

Place a new order.

import { OrderTypeEnum, OrderSideEnum } from 'topstepx-api';

const result = await client.orders.place({
  accountId: number;
  contractId: string;
  type: OrderTypeEnum;       // Market, Limit, Stop, StopLimit
  side: OrderSideEnum;       // Buy, Sell
  size: number;
  limitPrice?: number;       // Required for Limit/StopLimit
  stopPrice?: number;        // Required for Stop/StopLimit
  trailPrice?: number;       // Optional trailing stop price
  customTag?: string;        // Optional custom identifier
  linkedOrderId?: number;    // Optional linked order (OCO)
});

// Returns: PlaceOrderResponseInterface
interface PlaceOrderResponseInterface {
  orderId: number;
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

cancel

Cancel an existing order.

const response = await client.orders.cancel({
  accountId: number;
  orderId: number;
});

// Returns: CancelOrderResponseInterface
interface CancelOrderResponseInterface {
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

modify

Modify an existing order.

const response = await client.orders.modify({
  accountId: number;
  orderId: number;
  size?: number;
  limitPrice?: number;
  stopPrice?: number;
  trailPrice?: number;
});

// Returns: ModifyOrderResponseInterface
interface ModifyOrderResponseInterface {
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

search

Search historical orders.

const response = await client.orders.search({
  accountId: number;
  startTimestamp?: string;   // ISO 8601 format
  endTimestamp?: string;
});

// Returns: SearchOrdersResponseInterface
interface SearchOrdersResponseInterface {
  orders: OrderInterface[];
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

interface OrderInterface {
  id: number;
  accountId: number;
  contractId: string;
  creationTimestamp: string;
  updateTimestamp: string | null;
  status: OrderStatusEnum;
  type: OrderTypeEnum;
  side: OrderSideEnum;
  size: number;
  limitPrice: number | null;
  stopPrice: number | null;
}

searchOpen

Get currently open orders.

const response = await client.orders.searchOpen({
  accountId: number;
});

// Returns: SearchOpenOrdersResponseInterface
interface SearchOpenOrdersResponseInterface {
  orders: OrderInterface[];
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

Positions API

Access via client.positions

searchOpen

Get open positions.

const response = await client.positions.searchOpen({
  accountId: number;
});

// Returns: SearchOpenPositionsResponseInterface
interface SearchOpenPositionsResponseInterface {
  positions: PositionInterface[];
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

interface PositionInterface {
  id: number;
  accountId: number;
  contractId: string;
  creationTimestamp: string;
  type: PositionTypeEnum;    // Long, Short
  size: number;
  averagePrice: number;
}

close

Close a position entirely.

const response = await client.positions.close({
  accountId: number;
  contractId: string;
});

// Returns: ClosePositionResponseInterface
interface ClosePositionResponseInterface {
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

partialClose

Partially close a position.

const response = await client.positions.partialClose({
  accountId: number;
  contractId: string;
  size: number;              // Number of contracts to close
});

// Returns: PartialClosePositionResponseInterface
interface PartialClosePositionResponseInterface {
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

Trades API

Access via client.trades

search

Search trade history.

const response = await client.trades.search({
  accountId: number;
  startTimestamp: string;    // ISO 8601 format
  endTimestamp: string;
});

// Returns: SearchTradesResponseInterface
interface SearchTradesResponseInterface {
  trades: TradeInterface[];
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

interface TradeInterface {
  id: number;
  accountId: number;
  contractId: string;
  creationTimestamp: string;
  price: number;
  profitAndLoss: number | null;
  fees: number;
  side: OrderSideEnum;
  size: number;
  voided: boolean;
  orderId: number;
}

Contracts API

Access via client.contracts

search

Search for contracts/symbols.

const response = await client.contracts.search({
  searchText: string;        // e.g., "ES", "NQ", "CL"
  live: boolean;             // true for live, false for sim
});

// Returns: SearchContractsResponseInterface
interface SearchContractsResponseInterface {
  contracts: ContractInterface[];
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

interface ContractInterface {
  id: string;
  name: string;
  description: string;
  tickSize: number;
  tickValue: number;
  activeContract: boolean;
}

searchById

Get a specific contract by ID.

const response = await client.contracts.searchById({
  contractId: string;        // e.g., "CON.F.US.ENQ.M25"
  live: boolean;
});

// Returns: SearchContractByIdResponseInterface
interface SearchContractByIdResponseInterface {
  contract: ContractInterface | null;
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

History API

Access via client.history

retrieveBars

Get historical OHLCV bars.

import { BarUnitEnum } from 'topstepx-api';

const response = await client.history.retrieveBars({
  contractId: string;
  live: boolean;
  startTime: string;         // ISO 8601 format
  endTime: string;
  unit: BarUnitEnum;         // Second, Minute, Hour, Day, Week, Month
  unitNumber: number;        // e.g., 5 for 5-minute bars
  limit: number;             // Max bars to return
  includePartialBar: boolean;
});

// Returns: RetrieveBarsResponseInterface
interface RetrieveBarsResponseInterface {
  bars: BarInterface[];
  success: boolean;
  errorCode: number;
  errorMessage: string | null;
}

interface BarInterface {
  t: string;   // timestamp
  o: number;   // open
  h: number;   // high
  l: number;   // low
  c: number;   // close
  v: number;   // volume
}

Market Hub (Real-time Market Data)

Access via client.marketHub

Subscribe to real-time market data via WebSocket.

Subscribing

// Subscribe to all market data for a contract
await client.marketHub.subscribe('CON.F.US.ENQ.M25');

// Or subscribe selectively
await client.marketHub.subscribeQuotes('CON.F.US.ENQ.M25');
await client.marketHub.subscribeTrades('CON.F.US.ENQ.M25');
await client.marketHub.subscribeDepth('CON.F.US.ENQ.M25');

Unsubscribing

await client.marketHub.unsubscribe('CON.F.US.ENQ.M25');

// Or unsubscribe selectively
await client.marketHub.unsubscribeQuotes('CON.F.US.ENQ.M25');
await client.marketHub.unsubscribeTrades('CON.F.US.ENQ.M25');
await client.marketHub.unsubscribeDepth('CON.F.US.ENQ.M25');

Events

// Quote updates
client.marketHub.on('quote', ({ contractId, data }) => {
  for (const quote of data) {
    console.log(`${contractId}: Bid ${quote.bestBid} / Ask ${quote.bestAsk}`);
  }
});

// Trade updates
client.marketHub.on('trade', ({ contractId, data }) => {
  for (const trade of data) {
    console.log(`${contractId}: ${trade.volume} @ ${trade.price}`);
  }
});

// Market depth updates
client.marketHub.on('depth', ({ contractId, data }) => {
  for (const level of data) {
    console.log(`${contractId}: ${level.volume} @ ${level.price}`);
  }
});

Event Types

interface RealtimeMarketQuoteEventInterface {
  symbol: string;
  lastPrice: number;
  bestBid: number;
  bestAsk: number;
  change: number;
  changePercent: number;
  volume: number;
  lastUpdated: string;
  timestamp: string;
}

interface RealtimeMarketTradeEventInterface {
  symbolId: string;
  price: number;
  timestamp: string;
  type: 0 | 1;        // 0 = Bid, 1 = Ask
  volume: number;
}

interface RealtimeMarketDepthEventInterface {
  price: number;
  volume: number;
  currentVolume: number;
  type: number;
  timestamp: string;
}

User Hub (Real-time Account Data)

Access via client.userHub

Subscribe to real-time account updates via WebSocket.

Subscribing

// Subscribe to all account updates
await client.userHub.subscribe(accountId);

// Or subscribe selectively
await client.userHub.subscribeOrders(accountId);
await client.userHub.subscribePositions(accountId);
await client.userHub.subscribeTrades(accountId);

Unsubscribing

await client.userHub.unsubscribe(accountId);

Events

// Order updates
client.userHub.on('order', (order) => {
  console.log(`Order ${order.id}: ${order.status}`);
});

// Position updates
client.userHub.on('position', (position) => {
  console.log(`Position: ${position.size} contracts @ ${position.averagePrice}`);
});

// Trade executions
client.userHub.on('trade', (trade) => {
  console.log(`Trade: ${trade.size} @ ${trade.price}, P&L: ${trade.profitAndLoss}`);
});

// Account updates
client.userHub.on('account', (account) => {
  console.log(`Account ${account.name}: Can trade = ${account.canTrade}`);
});

Enums

import {
  OrderTypeEnum,
  OrderSideEnum,
  OrderStatusEnum,
  BarUnitEnum,
  PositionTypeEnum,
  TradeTypeEnum,
} from 'topstepx-api';

// OrderTypeEnum
OrderTypeEnum.Limit      // 1
OrderTypeEnum.Market     // 2
OrderTypeEnum.Stop       // 3
OrderTypeEnum.StopLimit  // 4

// OrderSideEnum
OrderSideEnum.Buy        // 0
OrderSideEnum.Sell       // 1

// OrderStatusEnum
OrderStatusEnum.Pending        // 0
OrderStatusEnum.Working        // 1
OrderStatusEnum.Filled         // 2
OrderStatusEnum.Cancelled      // 3
OrderStatusEnum.Rejected       // 4
OrderStatusEnum.PartiallyFilled // 5

// BarUnitEnum
BarUnitEnum.Second       // 1
BarUnitEnum.Minute       // 2
BarUnitEnum.Hour         // 3
BarUnitEnum.Day          // 4
BarUnitEnum.Week         // 5
BarUnitEnum.Month        // 6

// PositionTypeEnum
PositionTypeEnum.Long    // 0
PositionTypeEnum.Short   // 1

Error Handling

The library provides typed errors for different failure scenarios:

import {
  TopstepXError,
  AuthenticationError,
  ApiError,
  ConnectionError,
} from 'topstepx-api';

try {
  await client.connect();
  await client.orders.place({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message, error.code);
  } else if (error instanceof ApiError) {
    console.error(`API error on ${error.endpoint}:`, error.message);
  } else if (error instanceof ConnectionError) {
    console.error('WebSocket error:', error.message);
  }
}

All errors extend TopstepXError and include:

message - Error description
code - Error code (if applicable)
timestamp - When the error occurred
toJSON() - Serialize for logging

Complete Example

import {
  TopstepXClient,
  OrderTypeEnum,
  OrderSideEnum,
  BarUnitEnum,
  ApiError,
} from 'topstepx-api';
import 'dotenv/config';

async function main() {
  const client = new TopstepXClient({
    username: process.env.TOPSTEP_USERNAME!,
    apiKey: process.env.TOPSTEP_API_KEY!,
  });

  try {
    // Connect
    await client.connect();
    console.log('Connected to TopstepX');

    // Get accounts
    const accountsResponse = await client.accounts.search({ onlyActiveAccounts: true });
    const account = accountsResponse.accounts[0];
    console.log(`Using account: ${account.name} (${account.id})`);

    // Search for ES contract
    const contractsResponse = await client.contracts.search({
      searchText: 'ES',
      live: false,
    });
    const esContract = contractsResponse.contracts.find(c => c.activeContract);
    console.log(`Found contract: ${esContract?.id}`);

    // Get historical data
    const endTime = new Date();
    const startTime = new Date(endTime.getTime() - 24 * 60 * 60 * 1000);

    const barsResponse = await client.history.retrieveBars({
      contractId: esContract!.id,
      live: false,
      startTime: startTime.toISOString(),
      endTime: endTime.toISOString(),
      unit: BarUnitEnum.Hour,
      unitNumber: 1,
      limit: 24,
      includePartialBar: false,
    });
    console.log(`Retrieved ${barsResponse.bars.length} hourly bars`);

    // Subscribe to real-time quotes
    client.marketHub.on('quote', ({ contractId, data }) => {
      const quote = data[0];
      console.log(`${contractId}: ${quote.bestBid} / ${quote.bestAsk}`);
    });
    await client.marketHub.subscribeQuotes(esContract!.id);

    // Subscribe to account updates
    client.userHub.on('order', (order) => {
      console.log(`Order update: ${order.id} - ${order.status}`);
    });
    await client.userHub.subscribe(account.id);

    // Place a limit order
    const order = await client.orders.place({
      accountId: account.id,
      contractId: esContract!.id,
      type: OrderTypeEnum.Limit,
      side: OrderSideEnum.Buy,
      size: 1,
      limitPrice: barsResponse.bars[barsResponse.bars.length - 1].c - 10, // 10 points below last close
    });
    console.log(`Placed order: ${order.orderId}`);

    // Check open orders
    const openOrdersResponse = await client.orders.searchOpen({ accountId: account.id });
    console.log(`Open orders: ${openOrdersResponse.orders.length}`);

    // Cancel the order
    await client.orders.cancel({
      accountId: account.id,
      orderId: order.orderId,
    });
    console.log('Order cancelled');

    // Keep running for real-time updates
    await new Promise(resolve => setTimeout(resolve, 30000));

  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`API Error [${error.endpoint}]: ${error.message}`);
    } else {
      console.error('Error:', error);
    }
  } finally {
    await client.disconnect();
    console.log('Disconnected');
  }
}

main();

TypeScript Support

All types are exported for full TypeScript support:

import type {
  // Config
  TopstepXClientConfig,
  TopstepXClientEvents,

  // REST domain models
  AccountInterface,
  OrderInterface,
  PositionInterface,
  TradeInterface,
  ContractInterface,
  BarInterface,

  // Response interfaces
  SearchAccountsResponseInterface,
  PlaceOrderResponseInterface,
  CancelOrderResponseInterface,
  ModifyOrderResponseInterface,
  SearchOrdersResponseInterface,
  SearchOpenOrdersResponseInterface,
  SearchOpenPositionsResponseInterface,
  ClosePositionResponseInterface,
  PartialClosePositionResponseInterface,
  SearchTradesResponseInterface,
  SearchContractsResponseInterface,
  SearchContractByIdResponseInterface,
  RetrieveBarsResponseInterface,

  // Request interfaces
  PlaceOrderRequestInterface,
  ModifyOrderRequestInterface,
  SearchOrdersRequestInterface,
  RetrieveBarsRequestInterface,

  // WebSocket interfaces
  RealtimeMarketQuoteEventInterface,
  RealtimeMarketTradeEventInterface,
  RealtimeMarketDepthEventInterface,
  RealtimeUserOrderUpdateInterface,
  RealtimeUserPositionUpdateInterface,
  RealtimeUserTradeUpdateInterface,
} from 'topstepx-api';

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.github/workflows		.github/workflows
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
MIGRATION.md		MIGRATION.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
typedoc.json		typedoc.json
vitest.config.ts		vitest.config.ts
yarn.lock		yarn.lock

hunter547/TopstepX-API

Folders and files

Latest commit

History

Repository files navigation

topstepx-api

Features

Installation

Environment Setup

Quick Start

API Reference

TopstepXClient

Constructor

Methods

Events

Accounts API

search

Orders API

place

cancel

modify

search

searchOpen

Positions API

searchOpen

close

partialClose

Trades API

search

Contracts API

search

searchById

History API

retrieveBars

Market Hub (Real-time Market Data)

Subscribing

Unsubscribing

Events

Event Types

User Hub (Real-time Account Data)

Subscribing

Unsubscribing

Events

Enums

Error Handling

Complete Example

TypeScript Support

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages