Generate account

POST /v1/firm-control/accounts

operationId: generateFirmAccount Onboards a trader (creating the Tradara user if necessary) and provisions one or more evaluation accounts under your firm via the accounts service.

Authentication

Firm API key, or staff JWT with firm scope. Scope is resolved from X-Firm-ID (auto-injected for API keys) or firm_id in the body.

Headers

Header	Notes
`X-Firm-ID`	Firm UUID. Auto-injected for firm API keys.
`X-Firm-Entity-Slug`	Optional RBAC entity slug.

Body

Field	Type	Notes
`email`	string (email)	Trader email. Used to find or create the user.
`user_id`	string	Existing Tradara user UUID. Provide instead of `email` to attach accounts to a known user.
`relationship_type`	enum	`TRADER` or `STAFF`. Defaults to `TRADER`.
`username`	string	Username for a newly created user.
`plan_reference`	string	Plan reference configured for your firm.
`plan_id`	string	Plan UUID. Alternative to `plan_reference`.
`eval_template_id`	string	Evaluation template UUID.
`stage`	string	Initial stage (e.g. `evaluation`).
`status`	string	Initial account status override.
`provider_account_id`	string	External provider account reference, when migrating.
`idempotency_key`	string	Optional de-duplication key, unique among your firm’s accounts. Use your purchase or order id. A repeat of the same key returns the original account and does not create another. At most 255 characters. Cannot be combined with `count` greater than 1.
`price_paid`	string	Optional amount the trader paid for this purchase, in the account currency. Zero or greater, with at most 2 decimal places (`149`, `149.9`, or `149.00`). When `count` is greater than 1, Tradara divides this total across the accounts it creates.
`count`	integer	Number of accounts to provision. Defaults to `1`. Each account in a bulk request gets its own cloned rule rows when overrides are sent.
`initial_balance`	string	Optional starting balance for this account. When omitted, the template value is used.
`currency`	string	Optional ISO-4217 currency (3 letters). When omitted, the template currency is used.
`risk_profile`	object	Optional overlay on the template risk profile. When present, Tradara clones the template profile and applies these fields for this account only.
`passing_criteria`	object	Optional overlay on the starting-phase passing criteria. When present, Tradara clones those criteria for this account only.

plan_reference (or plan_id / eval_template_id) is still required. Position limits, scaling, commissions, and trading sessions always come from the plan. Omitted overlay keys inherit from the template. A later funded upgrade uses the plan’s funded template unless you generate that funded account with its own overlays. Send idempotency_key when one purchase should produce one account. Tradara stores it on that account. A later generate with the same key returns the original account (200) and does not create another, including after the account is closed. The retry body is not applied, so a different price_paid on that call does not change the stored amount. Omit the field when you intend to create another account. The key stays on the original account; Replace account mints a new account and does not move the key. Send price_paid when you want that purchase amount stored for later risk analysis. Tradara keeps it on each account, separate from the plan’s catalog price. For a single account, the account’s price_paid is the amount you sent. For a bulk request, Tradara splits the amount into equal cent shares. Any leftover cents go to the earliest accounts so the shares add up to the total. 149.00 with count: 3 is stored as 49.67, 49.67, and 49.66. Omit the field to leave price_paid null. 0 or 0.00 records a free account. A value with more than two decimal places is rejected.

`risk_profile` fields

Reuse the existing risk-profile contract. Partial overlays are allowed.

Field	Notes
`max_drawdown_mode`	`static`, `end_of_day_balance`, `end_of_day_equity`, `realtime_balance`, `realtime_equity`
`max_drawdown_value`	Dollar allowance
`max_drawdown_limit`	Relative offset from starting balance. Omit or `null` for uncapped trailing. Unused in `static`. Cap at start balance with `"0"`.
`daily_loss_value`	Amount
`daily_loss_value_type`	`DOLLAR` or `PERCENTAGE`
`daily_loss_type`	`start_of_day_balance`, `realtime_balance`, `realtime_equity`
`daily_loss_action`	`do_nothing`, `liquidate`, `liquidate_and_lock`
`daily_loss_is_hard_breach`	`true` fails the account permanently. `false` flattens open positions and blocks new orders until the next session roll, then the account trades again
`weekly_loss_*`	Same shape as daily loss, optional. A soft weekly breach releases at the weekly roll rather than the daily one
`daily_profit_target_*`	Optional daily profit halt

`passing_criteria` fields

Field	Notes
`profit_target_dollars`	Profit amount to pass. `situation=realtime` measures `equity - starting_balance`; otherwise realized PnL
`situation`	`realtime`, `no_positions`, or `no_orders_or_positions`
`min_trading_days`	Optional. Omit to leave the template value
`consistency_percentage`	Omit to inherit. The existing rule is best-day PnL / total realized PnL
`action_on_met`	`notify`, `pass_account`, `do_nothing`, `pass_and_upgrade`

Example

curl -X POST "$TRADARA_BASE_URL/v1/firm-control/accounts" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "relationship_type": "TRADER",
    "plan_reference": "eval-50k",
    "idempotency_key": "order-10091",
    "price_paid": "149.00",
    "count": 1
  }'

Override rules for one account without changing the shared plan:

curl -X POST "$TRADARA_BASE_URL/v1/firm-control/accounts" \
  -H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "plan_reference": "eval-50k",
    "stage": "evaluation",
    "initial_balance": "50000.00",
    "risk_profile": {
      "max_drawdown_mode": "end_of_day_balance",
      "max_drawdown_value": "2000.00",
      "max_drawdown_limit": "0",
      "daily_loss_value": "1000.00",
      "daily_loss_value_type": "DOLLAR",
      "daily_loss_type": "start_of_day_balance",
      "daily_loss_action": "liquidate",
      "daily_loss_is_hard_breach": false
    },
    "passing_criteria": {
      "profit_target_dollars": "3000.00",
      "min_trading_days": 5,
      "consistency_percentage": "40",
      "action_on_met": "pass_and_upgrade"
    }
  }'

Response

201 Created means a new account was minted. 200 OK means idempotency_key already belonged to an account in your firm: the body is the original account and no second account is created.

{
  "user_id": "8e9ad12c-2b1c-4e9a-9d3b-5e6c7a0d1f23",
  "user_created": true,
  "relationship_status": "ACTIVE",
  "accounts": {
    "items": [
      { "account_id": "5b1c8a2e-9f2d-4d3c-b6f0-2b6c5b6e1f9a" }
    ]
  }
}

The accounts payload is forwarded from the accounts service. Generated account rows include idempotency_key and price_paid when you sent them, plus risk_profile_id and, when a passing overlay was sent, passing_criteria_id. On a bulk create, each row’s price_paid is that account’s share, not the request total. Pass id / account_id values to POST /v1/orders. Look the account up later with GET /v1/firm-control/accounts?idempotency_key=. To move the trailing max-loss cap after the account exists, call the account-specific PATCH /v1/firm-control/accounts/{account_id}/max-loss-limit route. It clones a shared profile before writing. Confirm the live floor with GET /v1/firm-control/accounts/{account_id}/risk-state. To close an existing account and mint a fresh one from the same evaluation template, call POST /v1/firm-control/accounts/{account_id}/replace.

Errors

HTTP	Meaning
`400`	Validation failed. This includes a missing or unknown plan, an `idempotency_key` longer than 255 characters, an `idempotency_key` combined with `count` greater than 1, or a `price_paid` that is negative or has more than 2 decimal places.
`403`	Firm key or staff role not permitted to provision accounts.
`502`	Downstream accounts service unreachable.
`503`	Accounts service 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)

Generate account

Authentication

Headers

Body

`risk_profile` fields

`passing_criteria` fields

Example

Response

Errors

​Authentication

​Headers

​Body

​risk_profile fields

​passing_criteria fields

​Example

​Response

​Errors

Authentication

Headers

Body

`risk_profile` fields

`passing_criteria` fields

Example

Response

Errors