Accounts

Every trading session in TestMax operates within an account. Accounts hold your balance, track your P&L, and are referenced by every order, position, and trade endpoint. Before you can place orders or start a replay session, you need to retrieve your account ID.

POST Account/search

Search for trading accounts associated with the authenticated user. The search returns your TopStep prop-firm challenge accounts (up to 100, newest first). Plain replay sessions started via Replay/start are not listed here — their accountId is returned directly in the Replay/start response.

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

Authentication: Bearer token required.

Request body

{
  "onlyActiveAccounts": true
}

Field	Type	Required	Default	Description
`onlyActiveAccounts`	`boolean`	No	`true`	When `true` (the default), returns only active accounts. Pass `false` explicitly to include completed/violated/ended accounts.

Response

{
  "success": true,
  "errorCode": 0,
  "errorMessage": null,
  "accounts": [
    {
      "id": 12345,
      "name": "Topstep 50K Combine",
      "balance": 50000.00,
      "canTrade": true,
      "isVisible": true,
      "simulated": true
    }
  ]
}

Field	Type	Description
`accounts`	`array`	List of account objects
`accounts[].id`	`number`	Unique account identifier. Use this as `accountId` in all other endpoints.
`accounts[].name`	`string`	The challenge name (e.g. `"Topstep 50K Combine"`)
`accounts[].balance`	`number`	Current account balance in USD
`accounts[].canTrade`	`boolean`	`true` while the challenge is active; `false` after a pass, violation, or end
`accounts[].isVisible`	`boolean`	Always `true` (ProjectX schema compatibility)
`accounts[].simulated`	`boolean`	Always `true` — every TestMax account is simulated

Example

# Get all active accounts
result = api("Account/search", {"onlyActiveAccounts": True})

if result["success"]:
    accounts = result.get("accounts", [])
    for acct in accounts:
        print(f"Account {acct['id']}: {acct['name']} — ${acct['balance']:,.2f}")

    # Use the first active account
    if accounts:
        ACCOUNT_ID = accounts[0]["id"]
        print(f"Using account: {ACCOUNT_ID}")
else:
    print(f"Error: {result['errorMessage']}")

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

const response = await fetch(
  "https://api.test-max.com/api/topstep-sim/Account/search",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ onlyActiveAccounts: true }),
  }
);

const data = await response.json();
const accountId = data.accounts[0].id;

Usage notes

The id field is what you pass as accountId to every other endpoint (orders, positions, trades, replay).
Account balances update in real time during a replay session as orders are filled and P&L is realized.
In the Algo Playground, the account is set up automatically and stored in the ACCOUNT_ID global variable.
For plain (non-challenge) backtests, skip Account/search — Replay/start creates the account and returns its accountId.