Contracts

Contracts represent the trading instruments available in TestMax — futures like NQ (Nasdaq 100 E-mini), ES (S&P 500 E-mini), and GC (Gold), as well as forex pairs like EURUSD. Before placing orders or starting a replay, you need to resolve your desired instrument to a contract ID.

Contract ID format

Contract IDs follow the TopStep ProjectX convention:

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

Component	Description	Example
CON	Fixed prefix	CON
F	Futures	F
US	Exchange/region	US
{symbol}	Instrument symbol	ENQ, EP, GCE
{monthYear}	Contract month and year	H25 (March 2025)

Full example: CON.F.US.ENQ.H25 represents the March 2025 Nasdaq 100 E-mini futures contract.

The simulator generates contract IDs using the current front-month code at call time — in July 2026 a search returns IDs ending in .N26. When resolving a contractId you send in a request, the simulator ignores the month/year segment and matches on the symbol, so example IDs with older month codes still work.

Month codes

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

Note

You do not need to memorize contract IDs. Use Contract/search with a human-readable symbol like "NQ" and the API will return the correct contract ID with all metadata.

---

POST Contract/search

Search for contracts by name, symbol, or description. Returns up to 50 matching active instruments. POST Contract/available is an alias with identical behavior.

URL: POST /api/topstep-sim/Contract/search

Authentication: Bearer token required.

Request body

{
  "searchText": "NQ"
}

Field	Type	Required	Description
searchText	string or null	No	Search query to filter contracts. Matches against symbol, name, and description. Pass null or omit to return all available contracts.

Response

{
  "success": true,
  "errorCode": 0,
  "errorMessage": null,
  "contracts": [
    {
      "id": "CON.F.US.ENQ.N26",
      "name": "NQN26",
      "description": "E-Mini NASDAQ 100 Futures",
      "tickSize": 0.25,
      "tickValue": 5.00,
      "activeContract": true,
      "symbolId": "NQ"
    }
  ]
}

Field	Type	Description
contracts	array	List of matching contract objects
contracts[].id	string	Unique contract identifier. Use this as contractId in order and position endpoints.
contracts[].name	string	Symbol plus the current contract month code (e.g., "NQN26")
contracts[].description	string	Full instrument name
contracts[].tickSize	number	Minimum price increment
contracts[].tickValue	number	Dollar value per tick per contract
contracts[].activeContract	boolean	Always true — only active instruments are returned
contracts[].symbolId	string	Plain instrument symbol (e.g., "NQ", "ES", "GC")

Example

Python

# Search for NQ (Nasdaq 100) contracts
result = api("Contract/search", {"searchText": "NQ"})

if result["success"]:
    contracts = result.get("contracts", [])
    for c in contracts:
        print(f"{c['name']}: {c['id']} — {c['description']}")
        print(f"  Tick: {c['tickSize']} (${c['tickValue']}/tick)")

    # Use the first matching contract
    if contracts:
        CONTRACT_ID = contracts[0]["id"]
        TICK_SIZE = contracts[0]["tickSize"]
        TICK_VALUE = contracts[0]["tickValue"]

cURL

curl -X POST https://api.test-max.com/api/topstep-sim/Contract/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"searchText": "NQ"}'

Common searches

Search text	What it finds
"NQ"	Nasdaq 100 E-mini
"ES"	S&P 500 E-mini
"GC"	Gold Futures
"CL"	Crude Oil Futures
"EURUSD"	Euro/US Dollar
null	All available contracts

---

POST Contract/searchById

Look up a specific contract by its exact contract ID. Use this when you already know the contract ID and need to retrieve its metadata (tick size, tick value, etc.).

URL: POST /api/topstep-sim/Contract/searchById

Authentication: Bearer token required.

Request body

{
  "contractId": "CON.F.US.ENQ.H25"
}

Field	Type	Required	Description
contractId	string	Yes	The exact contract ID to look up

Response

{
  "success": true,
  "errorCode": 0,
  "errorMessage": null,
  "contract": {
    "id": "CON.F.US.ENQ.H25",
    "name": "NQN26",
    "description": "E-Mini NASDAQ 100 Futures",
    "tickSize": 0.25,
    "tickValue": 5.00,
    "activeContract": true,
    "symbolId": "NQ"
  }
}

Unlike Contract/search, the response carries a single contract object (not a contracts array). The id echoes the contract ID you sent; the fields are otherwise the same as Contract/search. An unknown or missing contractId returns errorCode 1, "Contract not found".

Example

Python

# Look up a known contract
result = api("Contract/searchById", {
    "contractId": "CON.F.US.ENQ.H25"
})

if result["success"] and result.get("contract"):
    contract = result["contract"]
    print(f"Found: {contract['name']} — {contract['description']}")
else:
    print("Contract not found")

cURL

curl -X POST https://api.test-max.com/api/topstep-sim/Contract/searchById \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"contractId": "CON.F.US.ENQ.H25"}'

---

Available instruments

TestMax supports a wide range of popular futures and forex instruments:

Symbol	Instrument	Tick Size	Tick Value
NQ	Nasdaq 100 E-mini	0.25	$5.00
ES	S&P 500 E-mini	0.25	$12.50
GC	Gold Futures	0.10	$10.00
CL	Crude Oil Futures	0.01	$10.00
EURUSD	Euro/US Dollar	0.00005	$6.25

Tip

Use Contract/search with null search text to discover all available instruments. The available contracts may expand over time as new instruments are added.

Usage in the Algo Playground

When using the Algo Playground, the contract is resolved automatically based on the instrument you select in the UI. The resolved contract ID is stored in the CONTRACT_ID global variable and passed to the place_order() and close_all_positions() helper functions. You do not need to call Contract/search manually unless you are building a standalone bot.