Skip to content
TestMax Docs
Back to App

Gateway Compatibility

The Simulator API supports common futures-gateway request shapes. Changing TESTMAX_API_URL alone does not migrate a bot. TestMax needs its own authentication, replay session and pull-based bar loop.

What the schema shares

TestMax implements the same endpoint names, request bodies and response shapes as the gateway schema:

EndpointBehavior
Account/searchLists simulator-compatible Challenge Mode accounts
Order/placePlaces a trading order (fills against historical data in TestMax)
Position/searchOpenReturns open positions
Trade/searchReturns past trades

When your strategy calls place_order(ACCOUNT_ID, CONTRACT_ID, 0, 1), the same JSON payload is sent regardless of which gateway is behind API_URL.

  • All API endpoint paths — Order/place, Account/search, Position/searchOpen, etc.
  • Request body format — Same JSON structure for all parameters
  • Response body format — Same fields in all responses
  • Authentication — Bearer token in the Authorization header
  • Order types — Market (2), Limit (1), Stop (4) all work identically
  • Side values — Buy (0) and Sell (1) are the same
  • Contract IDs — Same format (e.g., CON.F.US.ENQ.H25)

What is TestMax-only

These parts exist only in the simulator, because they are what turns a trading API into a backtesting engine:

  • Replay Control — Replay/start, Replay/step, Replay/end, Replay/jumpTo, Replay/play and Replay/pause. See Replay Control.
  • Simulated withdrawals — the Payout/* endpoints for performance-phase challenge accounts. See Simulated Withdrawals.
  • Pull-based bars — get_next_bar() fetches the next historical bar over Replay/step; a real-time gateway would push bars to you instead.
  • Speed control — read_speed(), STEP_DELAY and SPEED_FILE pace the replay from the Playground slider.
  • Any historical date — sessions run on the date range you choose, not on market hours.
  • Order/modify — not supported; use the cancel-and-re-place pattern described in Orders.

Adapting a bot

The generated script reads its base URL from one environment variable:

API_URL = os.environ.get("TESTMAX_API_URL", "http://127.0.0.1:8087/api/sim")

Inside the Playground, TestMax injects TESTMAX_API_URL for you. Running the script standalone against a hosted TestMax uses https://api.test-max.com/api/sim with a token from POST Auth/loginKey (see Authentication). Then adapt the replay lifecycle:

  1. Start a session with Replay/start and use the returned account and contract IDs. Inside the Playground, the session is pre-created and those IDs are supplied for you.
  2. Advance historical bars with Replay/step instead of waiting for a live market-data feed. Handle loading refusals and the end of the data window.
  3. Close positions and call Replay/end when the run finishes.

See Replay Control for the request and response fields. Moving a Playground strategy to another gateway also requires replacing these TestMax-only lifecycle calls and its bar source.

Reference