List accounts

GET /v1/firm-control/accounts
GET /v1/firm-control/accounts?user_id=<uuid>

operationId: listFirmAccounts Returns trading accounts in your active firm. Omit user_id to page through every firm account. Pass user_id to recover only that member’s accounts. Use this endpoint to rebuild your local account mapping if you did not persist IDs returned during provisioning. The list includes copy-trading shadow accounts. Check is_shadow and skip rows where it is true when adopting accounts into your system.

Authentication

Use a firm API key or staff JWT with firm scope and the accounts:read permission. Firm scope is resolved from X-Firm-ID, which the API gateway injects for firm API keys, or from the optional firm_id query parameter for multi-firm JWT sessions. When user_id is set, that user must have a relationship with the active firm. The endpoint never returns accounts from another firm.

Query parameters

Parameter	Required	Notes
`user_id`	No	Tradara Identity user UUID. When omitted, all accounts in the firm are returned.
`firm_id`	No	Firm UUID for a multi-firm JWT session. Omit when the gateway supplies `X-Firm-ID`.
`limit`	No	Page size from 1 to 100. Defaults to 50.
`cursor`	No	Opaque cursor returned by the previous page.
`status`	No	Account status, such as `active` or `pending_acceptance`.
`product_type`	No	Product type, such as `FUTURES`.
`account_type`	No	Account type filter.
`idempotency_key`	No	Exact match on the de-duplication key sent to Generate account. Use this to recover the account for a purchase id.

Examples

List every account in the firm:

curl -sS "$TRADARA_BASE_URL/v1/firm-control/accounts?limit=50" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY"

Look up the account for a purchase id:

curl -sS \
  "$TRADARA_BASE_URL/v1/firm-control/accounts?idempotency_key=order-10091" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY"

List accounts for one user:

curl -sS \
  "$TRADARA_BASE_URL/v1/firm-control/accounts?user_id=8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23&limit=50" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY"

Response — `200 OK`

{
  "items": [
    {
      "id": "5b1c8a2e-9f2d-4d3c-b6f0-2b6c5b6e1f9a",
      "account_id": "5b1c8a2e-9f2d-4d3c-b6f0-2b6c5b6e1f9a",
      "owner_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
      "firm_id": "6d941c08-b82d-4ec2-9bdd-ab2b4820d884",
      "status": "active",
      "account_type": "evaluation",
      "product_type": "FUTURES",
      "account_name": "ONYXEVABCDE00001",
      "is_shadow": false,
      "plan_reference": "eval-50k",
      "idempotency_key": "order-10091",
      "price_paid": "149.00",
      "risk_profile_id": "9d4e8c1a-0b2f-4a91-8e3d-1c2b3a4d5e6f",
      "initial_balance": "50000.00",
      "currency": "USD",
      "successor_account_id": null,
      "predecessor_account_id": null
    }
  ],
  "limit": 50,
  "next_cursor": null
}

Key fields:

Field	Notes
`id` / `account_id`	Account UUID. Use this on the Trading API and account-specific operations such as Set max loss limit, Read live risk state, and Replace account.
`account_type`	e.g. `evaluation`, `sim_funded`.
`account_name`	Generated display name (useful prefixes like `ONYXEV` / `ONYXSF`).
`is_shadow`	`true` for an internal copy-trading shadow account. Exclude these from account adoption.
`plan_reference`	Firm plan reference when the account is linked to an evaluation plan.
`idempotency_key`	De-duplication key stored at creation, when you sent one. Null otherwise.
`price_paid`	This account’s share of the purchase price, in `currency`. Null when you omitted `price_paid` on Generate account. On a bulk create this is the proportional share, not the request total.
`risk_profile_id`	Catalog id for the account’s max-loss and daily-loss rules. You do not need it for account-specific max-loss cap updates.
`initial_balance`	Starting balance on the account row (not live equity).
`successor_account_id`	On an upgraded evaluation, the funded account minted from it.
`predecessor_account_id`	On a funded account, the evaluation it came from.

Account objects may contain additional account columns. For live balances and ops projections, use Firm Backoffice Reads. When next_cursor is present, send it unchanged in the next request. See Pagination.

Errors

HTTP	Meaning
`400`	Firm scope, pagination, `user_id`, or another filter is invalid.
`403`	The caller does not have `accounts:read`.
`404`	`user_id` was provided and that user does not belong to the active firm.
`502`	The accounts service returned an error or could not be reached.
`503`	The accounts service is not configured or temporarily unavailable.

Overview

Account Provisioning

Terminal Embed

Firm & Users

Staff & RBAC

Offerings & Acceptance

API Keys

Webhooks

Realtime WebSocket

Operations

Firm Backoffice Reads

Terminal Onboarding (JWT)

Authentication

Query parameters

Examples

Response — `200 OK`

Errors

​Authentication

​Query parameters

​Examples

​Response — 200 OK

​Errors

Authentication

Query parameters

Examples

Response — `200 OK`

Errors