topstepx-api 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,731 @@
+import { HubConnection } from '@microsoft/signalr';
+
+interface HttpClientConfig {
+    baseUrl: string;
+    getToken: () => Promise<string>;
+    timeout?: number;
+}
+interface ApiResponseBase {
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    post<TRequest, TResponse extends ApiResponseBase>(endpoint: string, data: TRequest): Promise<TResponse>;
+}
+
+interface Account {
+    id: number;
+    name: string;
+    canTrade: boolean;
+    isVisible: boolean;
+}
+interface SearchAccountsRequest {
+    onlyActiveAccounts: boolean;
+}
+interface SearchAccountsResponse {
+    accounts: Account[];
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+
+declare class AccountApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    search(request: SearchAccountsRequest): Promise<Account[]>;
+}
+
+/**
+ * Type of order to place.
+ * @category Enums
+ */
+declare enum OrderType {
+    /** Limit order - executes at specified price or better */
+    Limit = 1,
+    /** Market order - executes immediately at current market price */
+    Market = 2,
+    /** Stop order - becomes market order when stop price is reached */
+    Stop = 3,
+    /** Stop-limit order - becomes limit order when stop price is reached */
+    StopLimit = 4
+}
+/**
+ * Side of the order (buy or sell).
+ * @category Enums
+ */
+declare enum OrderSide {
+    /** Buy order - go long or close short position */
+    Buy = 0,
+    /** Sell order - go short or close long position */
+    Sell = 1
+}
+/**
+ * Current status of an order.
+ * @category Enums
+ */
+declare enum OrderStatus {
+    /** Order is pending submission */
+    Pending = 0,
+    /** Order is working (open) in the market */
+    Working = 1,
+    /** Order has been completely filled */
+    Filled = 2,
+    /** Order was cancelled */
+    Cancelled = 3,
+    /** Order was rejected */
+    Rejected = 4,
+    /** Order is partially filled */
+    PartiallyFilled = 5
+}
+/**
+ * Time unit for historical bar data.
+ * @category Enums
+ */
+declare enum BarUnit {
+    /** Second bars */
+    Second = 1,
+    /** Minute bars */
+    Minute = 2,
+    /** Hourly bars */
+    Hour = 3,
+    /** Daily bars */
+    Day = 4,
+    /** Weekly bars */
+    Week = 5,
+    /** Monthly bars */
+    Month = 6
+}
+/**
+ * Type of position (long or short).
+ * @category Enums
+ */
+declare enum PositionType {
+    /** Long position - bought contracts */
+    Long = 0,
+    /** Short position - sold contracts */
+    Short = 1
+}
+/**
+ * Type of trade execution.
+ * @category Enums
+ */
+declare enum TradeType {
+    /** Trade executed at bid price */
+    Bid = 0,
+    /** Trade executed at ask price */
+    Ask = 1
+}
+
+interface Order {
+    id: number;
+    accountId: number;
+    contractId: string;
+    creationTimestamp: string;
+    updateTimestamp: string | null;
+    status: OrderStatus;
+    type: OrderType;
+    side: OrderSide;
+    size: number;
+    limitPrice: number | null;
+    stopPrice: number | null;
+}
+interface PlaceOrderRequest {
+    accountId: number;
+    contractId: string;
+    type: OrderType;
+    side: OrderSide;
+    size: number;
+    limitPrice?: number | null;
+    stopPrice?: number | null;
+    trailPrice?: number | null;
+    customTag?: string | null;
+    linkedOrderId?: number | null;
+}
+interface PlaceOrderResponse {
+    orderId: number;
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+interface SearchOrdersRequest {
+    accountId: number;
+    startTimestamp?: string;
+    endTimestamp?: string;
+}
+interface SearchOrdersResponse {
+    orders: Order[];
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+interface SearchOpenOrdersRequest {
+    accountId: number;
+}
+interface CancelOrderRequest {
+    accountId: number;
+    orderId: number;
+}
+interface CancelOrderResponse {
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+interface ModifyOrderRequest {
+    accountId: number;
+    orderId: number;
+    size?: number;
+    limitPrice?: number | null;
+    stopPrice?: number | null;
+    trailPrice?: number | null;
+}
+interface ModifyOrderResponse {
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+
+/**
+ * API for managing orders - place, cancel, modify, and search.
+ *
+ * @example
+ * ```typescript
+ * // Place a market order
+ * const result = await client.orders.place({
+ *   accountId: 123,
+ *   contractId: 'CON.F.US.ENQ.M25',
+ *   type: OrderType.Market,
+ *   side: OrderSide.Buy,
+ *   size: 1,
+ * });
+ *
+ * // Cancel an order
+ * await client.orders.cancel({ accountId: 123, orderId: result.orderId });
+ * ```
+ *
+ * @category REST API
+ */
+declare class OrderApi {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Search historical orders within a date range.
+     * @param request - Search parameters including accountId and optional date range
+     * @returns Array of orders matching the search criteria
+     */
+    search(request: SearchOrdersRequest): Promise<Order[]>;
+    /**
+     * Get all currently open (working) orders for an account.
+     * @param request - Request containing the accountId
+     * @returns Array of open orders
+     */
+    searchOpen(request: SearchOpenOrdersRequest): Promise<Order[]>;
+    /**
+     * Place a new order.
+     * @param request - Order details including type, side, size, and prices
+     * @returns Response containing the new orderId
+     *
+     * @example
+     * ```typescript
+     * // Market order
+     * await client.orders.place({
+     *   accountId: 123,
+     *   contractId: 'CON.F.US.ENQ.M25',
+     *   type: OrderType.Market,
+     *   side: OrderSide.Buy,
+     *   size: 1,
+     * });
+     *
+     * // Limit order
+     * await client.orders.place({
+     *   accountId: 123,
+     *   contractId: 'CON.F.US.ENQ.M25',
+     *   type: OrderType.Limit,
+     *   side: OrderSide.Buy,
+     *   size: 1,
+     *   limitPrice: 5000.00,
+     * });
+     * ```
+     */
+    place(request: PlaceOrderRequest): Promise<PlaceOrderResponse>;
+    /**
+     * Cancel an existing order.
+     * @param request - Request containing accountId and orderId to cancel
+     * @returns Response indicating success or failure
+     */
+    cancel(request: CancelOrderRequest): Promise<CancelOrderResponse>;
+    /**
+     * Modify an existing order's size or price.
+     * @param request - Request containing orderId and fields to modify
+     * @returns Response indicating success or failure
+     */
+    modify(request: ModifyOrderRequest): Promise<ModifyOrderResponse>;
+}
+
+interface Position {
+    id: number;
+    accountId: number;
+    contractId: string;
+    creationTimestamp: string;
+    type: PositionType;
+    size: number;
+    averagePrice: number;
+}
+interface SearchOpenPositionsRequest {
+    accountId: number;
+}
+interface SearchOpenPositionsResponse {
+    positions: Position[];
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+interface ClosePositionRequest {
+    accountId: number;
+    contractId: string;
+}
+interface ClosePositionResponse {
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+interface PartialClosePositionRequest {
+    accountId: number;
+    contractId: string;
+    size: number;
+}
+interface PartialClosePositionResponse {
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+
+declare class PositionApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    searchOpen(request: SearchOpenPositionsRequest): Promise<Position[]>;
+    close(request: ClosePositionRequest): Promise<ClosePositionResponse>;
+    partialClose(request: PartialClosePositionRequest): Promise<PartialClosePositionResponse>;
+}
+
+interface Trade {
+    id: number;
+    accountId: number;
+    contractId: string;
+    creationTimestamp: string;
+    price: number;
+    profitAndLoss: number | null;
+    fees: number;
+    side: OrderSide;
+    size: number;
+    voided: boolean;
+    orderId: number;
+}
+interface SearchTradesRequest {
+    accountId: number;
+    startTimestamp: string;
+    endTimestamp: string;
+}
+interface SearchTradesResponse {
+    trades: Trade[];
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+
+declare class TradeApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    search(request: SearchTradesRequest): Promise<Trade[]>;
+}
+
+interface Contract {
+    id: string;
+    name: string;
+    description: string;
+    tickSize: number;
+    tickValue: number;
+    activeContract: boolean;
+}
+interface SearchContractsRequest {
+    searchText: string;
+    live: boolean;
+}
+interface SearchContractsResponse {
+    contracts: Contract[];
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+interface SearchContractByIdRequest {
+    contractId: string;
+    live: boolean;
+}
+interface SearchContractByIdResponse {
+    contract: Contract | null;
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+
+declare class ContractApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    search(request: SearchContractsRequest): Promise<Contract[]>;
+    searchById(request: SearchContractByIdRequest): Promise<Contract | null>;
+}
+
+interface Bar {
+    t: string;
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+    v: number;
+}
+interface RetrieveBarsRequest {
+    contractId: string;
+    live: boolean;
+    startTime: string;
+    endTime: string;
+    unit: BarUnit;
+    unitNumber: number;
+    limit: number;
+    includePartialBar: boolean;
+}
+interface RetrieveBarsResponse {
+    bars: Bar[];
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+
+declare class HistoryApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    retrieveBars(request: RetrieveBarsRequest): Promise<Bar[]>;
+}
+
+interface AuthConfig {
+    username: string;
+    apiKey: string;
+    baseUrl?: string;
+    autoRefresh?: boolean;
+    tokenValidityHours?: number;
+}
+interface LoginRequest {
+    userName: string;
+    apiKey: string;
+}
+interface LoginResponse {
+    token: string;
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+interface ValidateResponse {
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+}
+
+declare class AuthService {
+    private sessionToken;
+    private tokenExpiration;
+    private refreshTimer?;
+    private readonly config;
+    constructor(config: AuthConfig);
+    login(): Promise<void>;
+    validate(): Promise<boolean>;
+    getSessionToken(): Promise<string>;
+    get baseUrl(): string;
+    private setTokenExpiration;
+    private isTokenExpired;
+    private scheduleTokenRefresh;
+    destroy(): void;
+}
+
+interface ConnectionManagerConfig {
+    marketHubUrl: string;
+    userHubUrl: string;
+    auth: AuthService;
+    reconnectDelays?: number[];
+}
+declare class ConnectionManager {
+    private marketConn;
+    private userConn;
+    private readonly config;
+    private marketConnectionCallbacks;
+    private userConnectionCallbacks;
+    constructor(config: ConnectionManagerConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    get isConnected(): boolean;
+    get marketConnection(): HubConnection;
+    get userConnection(): HubConnection;
+    onMarketConnection(callback: (conn: HubConnection) => void): void;
+    onUserConnection(callback: (conn: HubConnection) => void): void;
+}
+
+type EventMap = {
+    [key: string]: any;
+};
+type EventCallback<T> = T extends void ? () => void : (data: T) => void;
+declare class TypedEventEmitter<T extends EventMap = EventMap> {
+    private listeners;
+    on<K extends keyof T>(event: K, callback: EventCallback<T[K]>): this;
+    off<K extends keyof T>(event: K, callback: EventCallback<T[K]>): this;
+    once<K extends keyof T>(event: K, callback: EventCallback<T[K]>): this;
+    protected emit<K extends keyof T>(event: K, ...args: T[K] extends void ? [] : [T[K]]): boolean;
+    removeAllListeners<K extends keyof T>(event?: K): this;
+}
+
+interface Quote {
+    symbol: string;
+    lastPrice: number;
+    bestBid: number;
+    bestAsk: number;
+    change: number;
+    changePercent: number;
+    volume: number;
+    lastUpdated: string;
+    timestamp: string;
+}
+interface MarketTrade {
+    symbolId: string;
+    price: number;
+    timestamp: string;
+    type: 0 | 1;
+    volume: number;
+}
+interface MarketDepth {
+    price: number;
+    volume: number;
+    currentVolume: number;
+    type: number;
+    timestamp: string;
+}
+interface MarketEvent<T> {
+    contractId: string;
+    data: T[];
+}
+interface MarketHubEvents {
+    [key: string]: unknown;
+    quote: MarketEvent<Quote>;
+    trade: MarketEvent<MarketTrade>;
+    depth: MarketEvent<MarketDepth>;
+}
+
+declare class MarketHub extends TypedEventEmitter<MarketHubEvents> {
+    private readonly connectionManager;
+    private subscribedQuotes;
+    private subscribedTrades;
+    private subscribedDepth;
+    constructor(connectionManager: ConnectionManager);
+    private setupEventHandlers;
+    subscribe(contractId: string): Promise<void>;
+    unsubscribe(contractId: string): Promise<void>;
+    subscribeQuotes(contractId: string): Promise<void>;
+    unsubscribeQuotes(contractId: string): Promise<void>;
+    subscribeTrades(contractId: string): Promise<void>;
+    unsubscribeTrades(contractId: string): Promise<void>;
+    subscribeDepth(contractId: string): Promise<void>;
+    unsubscribeDepth(contractId: string): Promise<void>;
+}
+
+interface OrderUpdate {
+    id: number;
+    accountId: number;
+    contractId: string;
+    creationTimestamp: string;
+    updateTimestamp: string | null;
+    status: OrderStatus;
+    type: OrderType;
+    side: OrderSide;
+    size: number;
+    limitPrice: number | null;
+    stopPrice: number | null;
+}
+interface PositionUpdate {
+    id: number;
+    accountId: number;
+    contractId: string;
+    creationTimestamp: string;
+    type: PositionType;
+    size: number;
+    averagePrice: number;
+}
+interface TradeUpdate {
+    id: number;
+    accountId: number;
+    contractId: string;
+    creationTimestamp: string;
+    price: number;
+    profitAndLoss: number | null;
+    fees: number;
+    side: OrderSide;
+    size: number;
+    voided: boolean;
+    orderId: number;
+}
+interface AccountUpdate {
+    id: number;
+    name: string;
+    canTrade: boolean;
+    balance: number;
+}
+interface UserHubEvents {
+    [key: string]: unknown;
+    order: OrderUpdate;
+    position: PositionUpdate;
+    trade: TradeUpdate;
+    account: AccountUpdate;
+}
+
+declare class UserHub extends TypedEventEmitter<UserHubEvents> {
+    private readonly connectionManager;
+    private subscribedOrders;
+    private subscribedPositions;
+    private subscribedTrades;
+    constructor(connectionManager: ConnectionManager);
+    private setupEventHandlers;
+    subscribe(accountId: number): Promise<void>;
+    unsubscribe(accountId: number): Promise<void>;
+    subscribeOrders(accountId: number): Promise<void>;
+    unsubscribeOrders(accountId: number): Promise<void>;
+    subscribePositions(accountId: number): Promise<void>;
+    unsubscribePositions(accountId: number): Promise<void>;
+    subscribeTrades(accountId: number): Promise<void>;
+    unsubscribeTrades(accountId: number): Promise<void>;
+}
+
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    errorCode: number;
+    errorMessage: string | null;
+    [key: string]: T | boolean | number | string | null | undefined;
+}
+interface TopstepXClientConfig {
+    username: string;
+    apiKey: string;
+    baseUrl?: string;
+    marketHubUrl?: string;
+    userHubUrl?: string;
+    autoRefresh?: boolean;
+    tokenValidityHours?: number;
+}
+interface TopstepXClientEvents {
+    [key: string]: unknown;
+    connected: void;
+    disconnected: void;
+    error: Error;
+    reconnecting: void;
+    reconnected: void;
+}
+
+/**
+ * Main client for interacting with the TopstepX trading API.
+ *
+ * Provides access to REST APIs for account management, order placement,
+ * position management, trade history, contract search, and historical data.
+ * Also provides real-time WebSocket connections for market data and account updates.
+ *
+ * @example
+ * ```typescript
+ * import { TopstepXClient, OrderType, OrderSide } from 'topstepx-api';
+ *
+ * const client = new TopstepXClient({
+ *   username: process.env.TOPSTEP_USERNAME,
+ *   apiKey: process.env.TOPSTEP_API_KEY,
+ * });
+ *
+ * await client.connect();
+ *
+ * // Get accounts
+ * const accounts = await client.accounts.search({ onlyActiveAccounts: true });
+ *
+ * // Place an order
+ * await client.orders.place({
+ *   accountId: accounts[0].id,
+ *   contractId: 'CON.F.US.ENQ.M25',
+ *   type: OrderType.Market,
+ *   side: OrderSide.Buy,
+ *   size: 1,
+ * });
+ *
+ * // Subscribe to real-time quotes
+ * client.marketHub.on('quote', ({ contractId, data }) => {
+ *   console.log('Quote:', data);
+ * });
+ * await client.marketHub.subscribe('CON.F.US.ENQ.M25');
+ *
+ * await client.disconnect();
+ * ```
+ *
+ * @category Client
+ */
+declare class TopstepXClient extends TypedEventEmitter<TopstepXClientEvents> {
+    private readonly auth;
+    private readonly connectionManager;
+    private readonly httpClient;
+    /** Account management API */
+    readonly accounts: AccountApi;
+    /** Order management API (place, cancel, modify, search) */
+    readonly orders: OrderApi;
+    /** Position management API (search, close) */
+    readonly positions: PositionApi;
+    /** Trade history API */
+    readonly trades: TradeApi;
+    /** Contract/symbol search API */
+    readonly contracts: ContractApi;
+    /** Historical bars/candles API */
+    readonly history: HistoryApi;
+    /** Real-time market data hub (quotes, trades, depth) */
+    readonly marketHub: MarketHub;
+    /** Real-time account data hub (orders, positions, trades) */
+    readonly userHub: UserHub;
+    constructor(config: TopstepXClientConfig);
+    /**
+     * Connect to the TopstepX API.
+     * Authenticates and establishes WebSocket connections.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from all services.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if client is connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Get the current auth token (for advanced use cases).
+     */
+    getToken(): Promise<string>;
+}
+
+declare abstract class TopstepXError extends Error {
+    readonly code?: number | undefined;
+    readonly timestamp: Date;
+    constructor(message: string, code?: number | undefined);
+    toJSON(): Record<string, unknown>;
+}
+
+declare class AuthenticationError extends TopstepXError {
+    constructor(message: string, code?: number);
+}
+
+declare class ApiError extends TopstepXError {
+    readonly endpoint: string;
+    constructor(message: string, code: number, endpoint: string);
+    toJSON(): Record<string, unknown>;
+}
+
+declare class ConnectionError extends TopstepXError {
+    constructor(message: string);
+}
+
+export { type Account, AccountApi, type AccountUpdate, ApiError, type ApiResponse, type AuthConfig, AuthService, AuthenticationError, type Bar, BarUnit, type CancelOrderRequest, type CancelOrderResponse, type ClosePositionRequest, type ClosePositionResponse, ConnectionError, ConnectionManager, type ConnectionManagerConfig, type Contract, ContractApi, HistoryApi, HttpClient, type HttpClientConfig, type LoginRequest, type LoginResponse, type MarketDepth, type MarketEvent, MarketHub, type MarketHubEvents, type MarketTrade, type ModifyOrderRequest, type ModifyOrderResponse, type Order, OrderApi, OrderSide, OrderStatus, OrderType, type OrderUpdate, type PartialClosePositionRequest, type PartialClosePositionResponse, type PlaceOrderRequest, type PlaceOrderResponse, type Position, PositionApi, PositionType, type PositionUpdate, type Quote, type RetrieveBarsRequest, type RetrieveBarsResponse, type SearchAccountsRequest, type SearchAccountsResponse, type SearchContractByIdRequest, type SearchContractByIdResponse, type SearchContractsRequest, type SearchContractsResponse, type SearchOpenOrdersRequest, type SearchOpenPositionsRequest, type SearchOpenPositionsResponse, type SearchOrdersRequest, type SearchOrdersResponse, type SearchTradesRequest, type SearchTradesResponse, TopstepXClient, type TopstepXClientConfig, type TopstepXClientEvents, TopstepXError, type Trade, TradeApi, TradeType, type TradeUpdate, TypedEventEmitter, UserHub, type UserHubEvents, type ValidateResponse };