Executions

An Execution is the per-Trader slice of an Operation. Every participant in an enroll, top-up, partial-sell, rebalance, or liquidate call gets exactly one Execution, and each Execution is processed independently: one participant's failure never affects the others in the same Operation.

Inside each Execution is an instructions[] array. Each Instruction is a single per-asset leg (one buy or one sell of one asset).

The Execution resource

Field	Type	Description
`id`	string (UUID)	Execution identifier.
`strategy_id`	string (UUID)	Parent Strategy.
`operation_id`	string (UUID)	Parent Operation.
`trader_id`	string (UUID)	The Trader this Execution belongs to.
`participant_code`	string	Platform's end-user identifier.
`account_label`	string	zerohash sub-ledger label for the position.
`status`	string	`awaiting_execution`, `settled`, `skipped`, or `rejected`.
`status_reason`	string	Free-form short reason on non-clean terminal states.
`instructions[]`	array	Per-asset legs (see below).
`created_at` / `updated_at`	string (ISO 8601)	Timestamps. `updated_at` is the canonical sequencing timestamp.

Execution status machine

Status	Description
`awaiting_execution`	Created; waiting for the parent Operation to reach `settling` and instructions to fire.
`settled`	Terminal. All instructions executed cleanly.
`skipped`	Terminal. No instructions had work to do (already-aligned, or no holdings on liquidation).
`rejected`	Terminal. The Execution failed (credit-check failure, all instructions below minimum, and similar). `status_reason` carries a short explanation, for example `insufficient BTC balance for sell leg`, `below_instrument_minimum`, `no_holdings`, `dust`, or `already_aligned`.

Instruction fields

Field	Description
`underlying_currency`	Asset traded.
`quoted_currency`	Fiat side; always the parent Strategy's `quoted_currency`.
`side`	`buy` or `sell`.
`amount`	The driver. With `amount_type = notional`, fiat to spend. With `amount_type = quantity`, crypto units to sell.
`amount_type`	`notional` or `quantity`.
`status`	`pending`, `waiting_proceeds`, `executed`, `skipped`, or `failed`.
`status_reason`	Set on non-clean states.
`price`, `quantity`, `total_notional`, `trade_ids`, `executed_at`	Populated only after `status = executed`.

Instruction status machine

Status	Description
`pending`	Created; not yet executed.
`waiting_proceeds`	Sell-side proceeds not yet available to fund this buy leg.
`executed`	Terminal. Post-trade fields populated.
`skipped`	Terminal. Below threshold or no-op.
`failed`	Terminal. Per-leg failure.

Endpoints

Method	Path	Purpose
`GET`	`/strategies/executions/{execution_id}`	Retrieve one Execution, including the full `instructions[]` snapshot.
`GET`	`/strategies/executions`	List Executions (paginated). Filters: `strategy_id`, `operation_id`, `participant_code`, `status`, `page`, `page_size`.

Get an Execution

GET /strategies/executions/{execution_id}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "strategy_id": "b1c2d3e4-f5a6-4789-bcde-f01234567890",
  "operation_id": "d1e2f3a4-b5c6-4789-abcd-ef0123456789",
  "trader_id": "f1a2b3c4-d5e6-4789-abcd-ef0123456789",
  "participant_code": "CUST01",
  "account_label": "b1c2d3e4-f5a6-4789-bcde-f01234567890",
  "status": "settled",
  "status_reason": "",
  "instructions": [
    {
      "underlying_currency": "BTC",
      "quoted_currency": "USD",
      "side": "sell",
      "amount": "797.00",
      "amount_type": "notional",
      "status": "executed",
      "status_reason": "",
      "price": "62000.00",
      "quantity": "0.0129",
      "total_notional": "797.00",
      "trade_ids": ["7a3d2e1f-4b6c-4789-abcd-ef0123456789"],
      "executed_at": "2026-04-17T12:00:15Z"
    }
  ],
  "created_at": "2026-04-17T12:00:00Z",
  "updated_at": "2026-04-17T12:00:22Z"
}

List responses use the shared pagination envelope. Each Execution includes its full instructions[] inline, so narrow with filters where possible.

Webhooks and polling

An Execution emits exactly one trade_strategy.execution.status_changed event, on its terminal transition (awaiting_execution → settled | skipped | rejected). Intermediate states are not delivered.

Instruction transitions are never delivered as webhooks. For real-time per-leg progress, poll GET /strategies/executions/{execution_id}; it is the only source of per-Instruction visibility. The terminal Execution webhook carries the final instructions[] snapshot.