Traders

A Trader is a (Strategy, participant) pair: it represents one of your end users' positions within one Strategy. A Trader is created automatically on that participant's first enrollment and is identified by a trader_id. The same participant enrolled in two Strategies has two independent Traders.

The Trader resource

Field	Type	Description
`id`	string (UUID)	Trader identifier (`trader_id`).
`strategy_id`	string (UUID)	The Strategy this Trader belongs to.
`participant_code`	string (≤ 6)	Platform's end-user identifier.
`account_label`	string	zerohash sub-ledger label for the position.
`auto_rebalance`	boolean	Controls default inclusion in rebalances (see below).
`created_at` / `updated_at`	string (ISO 8601)	Timestamps.

The `auto_rebalance` flag

auto_rebalance governs whether a Trader is picked up by a rebalance that does not name participants explicitly:

true: included when the platform triggers a rebalance without a participants list.
false: skipped from that default scope, but can still be targeted by listing the Trader explicitly in a rebalance request (explicit listing overrides the flag).

The flag is set at enrollment and changed only through PATCH (below). Top-up and partial-sell do not accept it. Liquidation ignores it entirely.

Endpoints

Method	Path	Purpose
`GET`	`/strategies/traders/{trader_id}`	Retrieve one Trader.
`GET`	`/strategies/traders`	List Traders (paginated). Filters: `strategy_id`, `participant_code`, `auto_rebalance`, `page`, `page_size`.
`PATCH`	`/strategies/traders/{trader_id}`	Update a Trader. Synchronous.

Update a Trader

PATCH /strategies/traders/{trader_id}

auto_rebalance is currently the only mutable field. The call is synchronous (the response carries the full resource, no webhook), and the change takes effect on the next rebalance; it does not affect any in-flight Operation.

Request

{ "auto_rebalance": false }

Behavior

Trader must exist (404 otherwise).
Change is synchronous and takes effect on the next rebalance.
To re-include a Trader later, PATCH back to true, or list the Trader explicitly in the next rebalance's participants array.

Lifecycle notes

A Trader is created once per (strategy_id, participant_code). A second enrollment for the same pair runs an Operation against the existing Trader; it does not create a second Trader and does not re-emit trade_strategy.trader.created.
After a liquidation, the Trader record is preserved for audit even though balances go to zero.

Webhooks

Trader creation emits trade_strategy.trader.created, exactly once per (strategy_id, participant_code), on first enrollment:

{
  "id": "f1a2b3c4-d5e6-4789-bcde-f01234567890",
  "strategy_id": "b1c2d3e4-f5a6-4789-bcde-f01234567890",
  "participant_code": "CUST01",
  "account_label": "b1c2d3e4-f5a6-4789-bcde-f01234567890",
  "auto_rebalance": true,
  "created_at": "2026-04-17T10:30:00Z",
  "updated_at": "2026-04-17T10:30:00Z"
}

Trader PATCH updates are synchronous and emit no webhook.