Enums & Types

This page documents all enum values, type constants, and data format conventions used across the TestMax API. Use this as a quick reference when building strategies or integrating with the API.

OrderType

The type of order to place. Used in the type field of Order/place.

Value	Name	Description	Required price fields
1	Limit	Executes at the specified price or better. Rests in the book until filled or canceled.	limitPrice
2	Market	Executes immediately at the current market price.	None
3	StopLimit	Becomes a limit order when the stop price is triggered.	stopPrice, limitPrice
4	Stop	Becomes a market order when the stop price is triggered.	stopPrice

When to use each type

• Market (2): Fast entries and exits where execution certainty matters more than price. Used for scalping, emergency flatten, and momentum entries.
• Limit (1): Entries at a specific price or better. Used for pullback entries, take-profit orders, and scaling into positions.
• Stop (4): Breakout entries and stop-loss protection. Triggers when the market trades through the stop price.
• StopLimit (3): Combines a stop trigger with a limit price to avoid slippage on breakout entries. The limit price controls the worst acceptable fill price.

---

OrderSide

The direction of the order. Used in the side field of Order/place.

Value	Name	Description
0	Buy	Buy to open a long position or close a short position
1	Sell	Sell to open a short position or close a long position

Note

The side determines the direction, not the intent. A Buy order closes a short position (if one exists) before opening a new long. Similarly, a Sell order closes a long position before opening a short. If your current position matches the order side, the order adds to the existing position.

---

OrderStatus

The current state of an order. Returned in the status field of Order/search and Order/searchOpen.

Value	Name	Description
1	Partial	Order is partially filled — some contracts executed, remaining are still working
2	Filled	Order is completely filled — all contracts executed
3	Canceled	Order was canceled before being fully filled
6	Pending	Order is active and waiting to be filled (limit/stop orders resting in the book)

Status transitions

Pending (6) → Partial (1) → Filled (2)
Pending (6) → Filled (2)       (fully filled immediately)
Pending (6) → Canceled (3)     (manually canceled)
Partial (1) → Canceled (3)     (canceled with partial fill)

---

PositionType

The direction of an open position. Returned in the type field of Position/searchOpen.

Value	Name	Description
1	Long	Holding a long position (bought contracts, profit when price rises)
2	Short	Holding a short position (sold contracts, profit when price falls)

Usage in strategy code

positions = get_positions(ACCOUNT_ID)
for pos in positions:
    if pos["type"] == 1:
        print(f"LONG {pos['size']} @ {pos['averagePrice']}")
    elif pos["type"] == 2:
        print(f"SHORT {pos['size']} @ {pos['averagePrice']}")

---

AggregateBarUnit

The time unit for bar aggregation. Used in the unit field of History/retrieveBars.

Value	Name	Description
1	Second	Bars aggregated by seconds
2	Minute	Bars aggregated by minutes
3	Hour	Bars aggregated by hours
4	Day	Bars aggregated by days

Combine unit with unitNumber to define the bar timeframe:

Timeframe	unit	unitNumber
1-second	1	1
30-second	1	30
1-minute	2	1
5-minute	2	5
15-minute	2	15
30-minute	2	30
1-hour	3	1
4-hour	3	4
Daily	4	1

---

Contract ID format

Contract identifiers follow the TopStep ProjectX convention:

CON.F.US.{symbol}.{monthYear}

Component	Description	Example
CON	Fixed prefix (contract)	CON
F	Asset class (futures)	F
US	Exchange/region	US
{symbol}	Internal instrument symbol	ENQ, EP, GC
{monthYear}	Month code + 2-digit year	H25 (March 2025)

The simulator maps symbols as follows: NQ→ENQ, ES→EP, MNQ→MENQ, MES→MEP, MCL→MCL; CL, GC, YM, and RTY keep their own symbols. Generated IDs always carry the current front-month code (e.g. .N26 in July 2026), and the month/year segment is ignored when the simulator resolves an ID you send.

Full examples

Contract ID	Instrument	Expiry
CON.F.US.ENQ.H25	Nasdaq 100 E-mini	March 2025
CON.F.US.EP.H25	S&P 500 E-mini	March 2025
CON.F.US.GC.J25	Gold Futures	April 2025
CON.F.US.CL.F25	Crude Oil Futures	January 2025

Month codes

Code	Month	Code	Month
F	January	N	July
G	February	Q	August
H	March	U	September
J	April	V	October
K	May	X	November
M	June	Z	December

Tip

You do not need to construct contract IDs manually. Use Contract/search with a human-readable symbol like "NQ" and the API returns the correct contract ID. The ID format is documented here for reference and debugging.

---

Standard response format

Every API endpoint returns a response with these three fields:

{
  "success": true,
  "errorCode": 0,
  "errorMessage": null
}

Field	Type	Description
success	boolean	true if the request succeeded
errorCode	number	0 for success, non-zero for errors
errorMessage	string or null	Human-readable error message, or null on success

Additional data fields are included alongside these fields depending on the endpoint. For example:

{
  "success": true,
  "errorCode": 0,
  "errorMessage": null,
  "accounts": [...]
}

Error codes

Error codes are contextual — the same number can mean different things on different endpoints, so always read errorMessage. Rough taxonomy:

Code	Typical meaning
0	Success
1	Not found (account, contract) or invalid session on Auth/validate
2	Invalid state or parameter (order/position not found, no active replay session, missing startDate, invalid unit or time range)
3	Auth failure (invalid credentials/token), unsupported operation (Order/modify), or invalid amount/unit number
4	Account violation (terminal challenge), payout ineligible, or invalid limit
5–7	Endpoint-specific: invalid close size, engine rejections, invalid order size/type
9	Pro subscription required
99	Internal server error
429	Rate limited — arrives as a real HTTP 429 with a Retry-After header

The full per-endpoint list is in Error Codes. Note that simulator errors (other than 429) are returned with HTTP 200 and success: false.

---

Bar data format

OHLCV bars returned by Replay/step and History/retrieveBars use this format:

{
  "t": "2025-01-15T14:30:00Z",
  "o": 21500.25,
  "h": 21505.50,
  "l": 21498.75,
  "c": 21503.00,
  "v": 150
}

Field	Type	Description
t	string	ISO 8601 UTC timestamp for the bar’s open time
o	number	Open price (first traded price in the bar period)
h	number	High price (highest traded price in the bar period)
l	number	Low price (lowest traded price in the bar period)
c	number	Close price (last traded price in the bar period)
v	number	Volume (total contracts traded in the bar period)

Note

All timestamps are in UTC. When comparing bar timestamps to market hours, convert to the appropriate timezone. For example, the US futures market open (9:30 AM ET) corresponds to 14:30 UTC during Eastern Standard Time.

---

Timeframe strings

Timeframe strings are used in Replay/start and Playground API endpoints:

String	Description
"1s"	1-second bars
"5s"	5-second bars
"10s"	10-second bars
"15s"	15-second bars
"30s"	30-second bars
"1m"	1-minute bars
"5m"	5-minute bars
"15m"	15-minute bars
"30m"	30-minute bars
"1h"	1-hour bars
"4h"	4-hour bars
"1d"	Daily bars

Bars are aggregated up from each instrument’s stored resolution, so a timeframe is only available when it is an exact multiple of that resolution. Gold (GC) is stored at 10-second resolution, for example, so "30s" is available on it but "15s" is not.

---

Quick reference card

Enum	Values
OrderType	1=Limit, 2=Market, 3=StopLimit, 4=Stop
OrderSide	0=Buy, 1=Sell
OrderStatus	1=Partial, 2=Filled, 3=Canceled, 6=Pending
PositionType	1=Long, 2=Short
AggregateBarUnit	1=Second, 2=Minute, 3=Hour, 4=Day

Copy-paste this into the top of your strategy for quick reference:

# === Enum Constants ===
# OrderType
LIMIT, MARKET, STOP_LIMIT, STOP = 1, 2, 3, 4

# OrderSide
BUY, SELL = 0, 1

# OrderStatus
PARTIAL, FILLED, CANCELED, PENDING = 1, 2, 3, 6

# PositionType
LONG, SHORT = 1, 2

# AggregateBarUnit
SECOND, MINUTE, HOUR, DAY = 1, 2, 3, 4