topstepx-api 1.0.3 → 2.0.1

package/README.md

@@ -31,7 +31,7 @@ Get your API key from your TopstepX account settings.
 ## Quick Start
 
 ```typescript
-import { TopstepXClient, OrderType, OrderSide } from 'topstepx-api';
+import { TopstepXClient, OrderTypeEnum, OrderSideEnum } from 'topstepx-api';
 
 const client = new TopstepXClient({
   username: process.env.TOPSTEP_USERNAME!,
@@ -41,15 +41,15 @@ const client = new TopstepXClient({
 await client.connect();
 
 // Get accounts
-const accounts = await client.accounts.search({ onlyActiveAccounts: true });
-console.log('Accounts:', 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: accounts[0].id,
+  accountId: response.accounts[0].id,
   contractId: 'CON.F.US.ENQ.M25',
-  type: OrderType.Market,
-  side: OrderSide.Buy,
+  type: OrderTypeEnum.Market,
+  side: OrderSideEnum.Buy,
   size: 1,
 });
 console.log('Order placed:', order.orderId);
@@ -106,12 +106,19 @@ Access via `client.accounts`
 Search for accounts.
 
 ```typescript
-const accounts = await client.accounts.search({
+const response = await client.accounts.search({
   onlyActiveAccounts: boolean;
 });
 
-// Returns: Account[]
-interface Account {
+// Returns: SearchAccountsResponseInterface
+interface SearchAccountsResponseInterface {
+  accounts: AccountInterface[];
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
+
+interface AccountInterface {
   id: number;
   name: string;
   canTrade: boolean;
@@ -130,13 +137,13 @@ Access via `client.orders`
 Place a new order.
 
 ```typescript
-import { OrderType, OrderSide } from 'topstepx-api';
+import { OrderTypeEnum, OrderSideEnum } from 'topstepx-api';
 
 const result = await client.orders.place({
   accountId: number;
   contractId: string;
-  type: OrderType;           // Market, Limit, Stop, StopLimit
-  side: OrderSide;           // Buy, Sell
+  type: OrderTypeEnum;       // Market, Limit, Stop, StopLimit
+  side: OrderSideEnum;       // Buy, Sell
   size: number;
   limitPrice?: number;       // Required for Limit/StopLimit
   stopPrice?: number;        // Required for Stop/StopLimit
@@ -145,7 +152,13 @@ const result = await client.orders.place({
   linkedOrderId?: number;    // Optional linked order (OCO)
 });
 
-// Returns: { orderId: number, success: boolean, ... }
+// Returns: PlaceOrderResponseInterface
+interface PlaceOrderResponseInterface {
+  orderId: number;
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
 ```
 
 #### cancel
@@ -153,10 +166,17 @@ const result = await client.orders.place({
 Cancel an existing order.
 
 ```typescript
-await client.orders.cancel({
+const response = await client.orders.cancel({
   accountId: number;
   orderId: number;
 });
+
+// Returns: CancelOrderResponseInterface
+interface CancelOrderResponseInterface {
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
 ```
 
 #### modify
@@ -164,7 +184,7 @@ await client.orders.cancel({
 Modify an existing order.
 
 ```typescript
-await client.orders.modify({
+const response = await client.orders.modify({
   accountId: number;
   orderId: number;
   size?: number;
@@ -172,6 +192,13 @@ await client.orders.modify({
   stopPrice?: number;
   trailPrice?: number;
 });
+
+// Returns: ModifyOrderResponseInterface
+interface ModifyOrderResponseInterface {
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
 ```
 
 #### search
@@ -179,22 +206,29 @@ await client.orders.modify({
 Search historical orders.
 
 ```typescript
-const orders = await client.orders.search({
+const response = await client.orders.search({
   accountId: number;
   startTimestamp?: string;   // ISO 8601 format
   endTimestamp?: string;
 });
 
-// Returns: Order[]
-interface Order {
+// 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: OrderStatus;
-  type: OrderType;
-  side: OrderSide;
+  status: OrderStatusEnum;
+  type: OrderTypeEnum;
+  side: OrderSideEnum;
   size: number;
   limitPrice: number | null;
   stopPrice: number | null;
@@ -206,9 +240,17 @@ interface Order {
 Get currently open orders.
 
 ```typescript
-const openOrders = await client.orders.searchOpen({
+const response = await client.orders.searchOpen({
   accountId: number;
 });
+
+// Returns: SearchOpenOrdersResponseInterface
+interface SearchOpenOrdersResponseInterface {
+  orders: OrderInterface[];
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
 ```
 
 ---
@@ -222,17 +264,24 @@ Access via `client.positions`
 Get open positions.
 
 ```typescript
-const positions = await client.positions.searchOpen({
+const response = await client.positions.searchOpen({
   accountId: number;
 });
 
-// Returns: Position[]
-interface Position {
+// Returns: SearchOpenPositionsResponseInterface
+interface SearchOpenPositionsResponseInterface {
+  positions: PositionInterface[];
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
+
+interface PositionInterface {
   id: number;
   accountId: number;
   contractId: string;
   creationTimestamp: string;
-  type: PositionType;        // Long, Short
+  type: PositionTypeEnum;    // Long, Short
   size: number;
   averagePrice: number;
 }
@@ -243,10 +292,17 @@ interface Position {
 Close a position entirely.
 
 ```typescript
-await client.positions.close({
+const response = await client.positions.close({
   accountId: number;
   contractId: string;
 });
+
+// Returns: ClosePositionResponseInterface
+interface ClosePositionResponseInterface {
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
 ```
 
 #### partialClose
@@ -254,11 +310,18 @@ await client.positions.close({
 Partially close a position.
 
 ```typescript
-await client.positions.partialClose({
+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;
+}
 ```
 
 ---
@@ -272,14 +335,21 @@ Access via `client.trades`
 Search trade history.
 
 ```typescript
-const trades = await client.trades.search({
+const response = await client.trades.search({
   accountId: number;
   startTimestamp: string;    // ISO 8601 format
   endTimestamp: string;
 });
 
-// Returns: Trade[]
-interface Trade {
+// Returns: SearchTradesResponseInterface
+interface SearchTradesResponseInterface {
+  trades: TradeInterface[];
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
+
+interface TradeInterface {
   id: number;
   accountId: number;
   contractId: string;
@@ -287,7 +357,7 @@ interface Trade {
   price: number;
   profitAndLoss: number | null;
   fees: number;
-  side: OrderSide;
+  side: OrderSideEnum;
   size: number;
   voided: boolean;
   orderId: number;
@@ -305,13 +375,20 @@ Access via `client.contracts`
 Search for contracts/symbols.
 
 ```typescript
-const contracts = await client.contracts.search({
+const response = await client.contracts.search({
   searchText: string;        // e.g., "ES", "NQ", "CL"
   live: boolean;             // true for live, false for sim
 });
 
-// Returns: Contract[]
-interface Contract {
+// Returns: SearchContractsResponseInterface
+interface SearchContractsResponseInterface {
+  contracts: ContractInterface[];
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
+
+interface ContractInterface {
   id: string;
   name: string;
   description: string;
@@ -326,12 +403,18 @@ interface Contract {
 Get a specific contract by ID.
 
 ```typescript
-const contract = await client.contracts.searchById({
+const response = await client.contracts.searchById({
   contractId: string;        // e.g., "CON.F.US.ENQ.M25"
   live: boolean;
 });
 
-// Returns: Contract | null
+// Returns: SearchContractByIdResponseInterface
+interface SearchContractByIdResponseInterface {
+  contract: ContractInterface | null;
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
 ```
 
 ---
@@ -345,21 +428,28 @@ Access via `client.history`
 Get historical OHLCV bars.
 
 ```typescript
-import { BarUnit } from 'topstepx-api';
+import { BarUnitEnum } from 'topstepx-api';
 
-const bars = await client.history.retrieveBars({
+const response = await client.history.retrieveBars({
   contractId: string;
   live: boolean;
   startTime: string;         // ISO 8601 format
   endTime: string;
-  unit: BarUnit;             // Second, Minute, Hour, Day, Week, Month
+  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: Bar[]
-interface Bar {
+// Returns: RetrieveBarsResponseInterface
+interface RetrieveBarsResponseInterface {
+  bars: BarInterface[];
+  success: boolean;
+  errorCode: number;
+  errorMessage: string | null;
+}
+
+interface BarInterface {
   t: string;   // timestamp
   o: number;   // open
   h: number;   // high
@@ -428,7 +518,7 @@ client.marketHub.on('depth', ({ contractId, data }) => {
 #### Event Types
 
 ```typescript
-interface Quote {
+interface RealtimeMarketQuoteEventInterface {
   symbol: string;
   lastPrice: number;
   bestBid: number;
@@ -440,7 +530,7 @@ interface Quote {
   timestamp: string;
 }
 
-interface MarketTrade {
+interface RealtimeMarketTradeEventInterface {
   symbolId: string;
   price: number;
   timestamp: string;
@@ -448,7 +538,7 @@ interface MarketTrade {
   volume: number;
 }
 
-interface MarketDepth {
+interface RealtimeMarketDepthEventInterface {
   price: number;
   volume: number;
   currentVolume: number;
@@ -513,43 +603,43 @@ client.userHub.on('account', (account) => {
 
 ```typescript
 import {
-  OrderType,
-  OrderSide,
-  OrderStatus,
-  BarUnit,
-  PositionType,
-  TradeType,
+  OrderTypeEnum,
+  OrderSideEnum,
+  OrderStatusEnum,
+  BarUnitEnum,
+  PositionTypeEnum,
+  TradeTypeEnum,
 } from 'topstepx-api';
 
-// OrderType
-OrderType.Limit      // 1
-OrderType.Market     // 2
-OrderType.Stop       // 3
-OrderType.StopLimit  // 4
-
-// OrderSide
-OrderSide.Buy        // 0
-OrderSide.Sell       // 1
-
-// OrderStatus
-OrderStatus.Pending        // 0
-OrderStatus.Working        // 1
-OrderStatus.Filled         // 2
-OrderStatus.Cancelled      // 3
-OrderStatus.Rejected       // 4
-OrderStatus.PartiallyFilled // 5
-
-// BarUnit
-BarUnit.Second       // 1
-BarUnit.Minute       // 2
-BarUnit.Hour         // 3
-BarUnit.Day          // 4
-BarUnit.Week         // 5
-BarUnit.Month        // 6
-
-// PositionType
-PositionType.Long    // 0
-PositionType.Short   // 1
+// 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
 ```
 
 ---
@@ -593,9 +683,9 @@ All errors extend `TopstepXError` and include:
 ```typescript
 import {
   TopstepXClient,
-  OrderType,
-  OrderSide,
-  BarUnit,
+  OrderTypeEnum,
+  OrderSideEnum,
+  BarUnitEnum,
   ApiError,
 } from 'topstepx-api';
 import 'dotenv/config';
@@ -612,33 +702,33 @@ async function main() {
     console.log('Connected to TopstepX');
 
     // Get accounts
-    const accounts = await client.accounts.search({ onlyActiveAccounts: true });
-    const account = accounts[0];
+    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 contracts = await client.contracts.search({
+    const contractsResponse = await client.contracts.search({
       searchText: 'ES',
       live: false,
     });
-    const esContract = contracts.find(c => c.activeContract);
+    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 bars = await client.history.retrieveBars({
+    const barsResponse = await client.history.retrieveBars({
       contractId: esContract!.id,
       live: false,
       startTime: startTime.toISOString(),
       endTime: endTime.toISOString(),
-      unit: BarUnit.Hour,
+      unit: BarUnitEnum.Hour,
       unitNumber: 1,
       limit: 24,
       includePartialBar: false,
     });
-    console.log(`Retrieved ${bars.length} hourly bars`);
+    console.log(`Retrieved ${barsResponse.bars.length} hourly bars`);
 
     // Subscribe to real-time quotes
     client.marketHub.on('quote', ({ contractId, data }) => {
@@ -657,16 +747,16 @@ async function main() {
     const order = await client.orders.place({
       accountId: account.id,
       contractId: esContract!.id,
-      type: OrderType.Limit,
-      side: OrderSide.Buy,
+      type: OrderTypeEnum.Limit,
+      side: OrderSideEnum.Buy,
       size: 1,
-      limitPrice: bars[bars.length - 1].c - 10, // 10 points below last close
+      limitPrice: barsResponse.bars[barsResponse.bars.length - 1].c - 10, // 10 points below last close
     });
     console.log(`Placed order: ${order.orderId}`);
 
     // Check open orders
-    const openOrders = await client.orders.searchOpen({ accountId: account.id });
-    console.log(`Open orders: ${openOrders.length}`);
+    const openOrdersResponse = await client.orders.searchOpen({ accountId: account.id });
+    console.log(`Open orders: ${openOrdersResponse.orders.length}`);
 
     // Cancel the order
     await client.orders.cancel({
@@ -705,27 +795,42 @@ import type {
   TopstepXClientConfig,
   TopstepXClientEvents,
 
-  // REST types
-  Account,
-  Order,
-  Position,
-  Trade,
-  Contract,
-  Bar,
-
-  // Request types
-  PlaceOrderRequest,
-  ModifyOrderRequest,
-  SearchOrdersRequest,
-  RetrieveBarsRequest,
-
-  // WebSocket types
-  Quote,
-  MarketTrade,
-  MarketDepth,
-  OrderUpdate,
-  PositionUpdate,
-  TradeUpdate,
+  // 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';
 ```