> ## Documentation Index > Fetch the complete documentation index at: https://docs.superform.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Strategy Engine API Reference > Create, order, execute, and inspect SuperVault strategies, intents, fills, and emergency locks. The Strategy Engine evaluates manager-defined rules and dispatches DeFiX intents to the OMS. It owns strategy lifecycle state, lane ordering, live shard state, intent history projections, and emergency locks. **Base URL:** `https://strategy.superform.xyz` **Auth:** `Authorization: Bearer ` `vault_id` uses `{chainId}:{vaultAddress}` format, for example `8453:0xdef...`. Erebor often uses separate `chain_id` and `vault_address` fields. ## Strategies ### List Strategies ```bash theme={null} GET /api/v1/strategies?vault_id={vault_id}&limit=50 ``` Filters: * `kind` — `USER_DEFINED` or `EMERGENCY_EXIT`. * `state` — lifecycle state. * `lane` — `DEPOSIT`, `WITHDRAWAL`, or `REBALANCE`. * `target_address` — lowercased target yield source / route address. * `limit`, `offset`. Emergency strategies are separated by `kind=EMERGENCY_EXIT`; normal editor flows use `USER_DEFINED` by default. ### Create Strategy ```bash theme={null} POST /api/v1/strategies ``` Required fields include `id`, `vault_id`, `name`, `indicators`, `rules`, `action_config`, and `max_concurrent`. Priority is not part of create. Use the reorder endpoint after creation. ### Update Strategy ```bash theme={null} PUT /api/v1/strategies/{strategy_id} ``` `version` is required for optimistic concurrency. A stale version returns `409 Conflict`. Priority is not part of update. Use the reorder endpoint. ### Transition State ```bash theme={null} PATCH /api/v1/strategies/{strategy_id}/state { "target_state": "RUNNING", "version": 12 } ``` Allowed target states include `IDLE`, `RUNNING`, `ARCHIVED`, and `ERROR` depending on current state and policy. For emergency exits, arm requests may include `emergency_arm_reason`. ### Reorder Strategies ```bash theme={null} POST /api/v1/strategies/reorder { "vault_id": "8453:0xdef...", "lane": "DEPOSIT", "ordered_strategy_ids": ["strategy-a", "strategy-b"] } ``` The backend atomically assigns priorities `1..N` inside the `(vault_id, lane)` partition. Rules: * Include every non-archived strategy in that lane exactly once. * Do not include archived strategies. * The lane must match the lane derived from each strategy action. * Reorder is the only priority persistence path. ## Strategy Kinds | Kind | Description | | ---------------- | ------------------------------------------------------------------------- | | `USER_DEFINED` | Manager-authored strategy visible in normal canvas flows | | `EMERGENCY_EXIT` | System-managed withdrawal strategy paired to one whitelisted yield source | `EMERGENCY_EXIT` strategies are controlled from [Pause Operations](/operate/ui/pause). They are read-only in normal strategy editing flows. ## Vault Config and Shards ```bash theme={null} GET /api/v1/vaults/{vault_id} PATCH /api/v1/vaults/{vault_id} GET /api/v1/engine/status GET /api/v1/engine/shards/{vault_id}/state ``` Vault state includes kill-switch / rate-limit settings. Shard state includes live indicator values, active strategy state, yield-source allocations, and active `emergency_locks`. An emergency lock has: ```json theme={null} { "strategy_id": "emergency-8453:0xdef-0xsource...", "target_address": "0xsource...", "started_at": "2026-05-09T14:21:00Z", "reason": "Oracle anomaly" } ``` ## Intent History The Strategy Engine maintains an operator-facing projection of OMS intent execution. ### Search Intents ```bash theme={null} GET /api/v1/intents ``` Common filters: * `vault_id` * `strategy_id` * `action` * `state` * `chain_id` * `tx_hash` * `token_in`, `token_out` * created/completed time ranges * amount-in ranges * `error_code` * free-text search across `intent_id`, `execution_id`, `error_message`, and fill transaction hash Cursor pagination is preferred for large histories. Default sort is newest first. ### Intent Facets ```bash theme={null} GET /api/v1/intents/facets ``` Returns counts by state, action, chain, vault, and strategy for filter UIs. ### Events and Fills ```bash theme={null} GET /api/v1/intents/{intent_id}/events GET /api/v1/intents/{intent_id}/fills GET /api/v1/fills ``` Use events for lifecycle reconstruction and fills for mined transaction evidence. Intent rows may include nullable fields while OMS execution is still in flight. For example, `completed_at`, `terminal_at`, `gas_used_total`, and fill data may be `null` until execution events and receipts arrive. ## Simulations Simulation endpoints let operators test strategy behavior before live execution. They do not publish OMS intents or submit onchain transactions. ```bash theme={null} POST /api/v1/simulations/backtest POST /api/v1/simulations/ahead GET /api/v1/simulations/saved GET /api/v1/simulations/saved/{simulation_id} POST /api/v1/simulations/saved/lookup POST /api/v1/simulations/saved DELETE /api/v1/simulations/saved/{simulation_id} ``` Use backtests for historical replay and forward simulations for current-state what-if analysis. See [Simulation](/operate/ui/simulation) for the operator flow. ## Important Schemas ### StrategyResponse Important fields: * `id` * `vault_id` * `name` * `version` * `state` * `kind` * `indicators` * `rules` * `action_config` * `priority` * `cooldown_ms` * `max_concurrent` ### IntentLogEntry Important fields: * `intent_id` * `execution_id` * `strategy_id` * `vault_id` * `action` * `state` * `source` * `fills_count` * `last_event_seq` * lifecycle timestamps such as `acked_at`, `executing_at`, `completed_at`, `terminal_at` * `error_code`, `error_message` * `total_amount_in`, `total_amount_out` * `gas_used_total` ### IntentFillEntry Important fields: * `fill_id` * `intent_id` * `execution_id` * `chain_id` * `tx_hash` * `amount_in`, `amount_out` * `token_in`, `token_out` * `gas_used` * `fill_time` * `venue` ## Endpoint Inventory | Endpoint | Method | Description | | ------------------------------------------- | ---------- | ----------------------------------------------------- | | `/api/v1/strategies` | GET | List strategies | | `/api/v1/strategies` | POST | Create strategy | | `/api/v1/strategies/{id}` | GET | Get strategy | | `/api/v1/strategies/{id}` | PUT | Update strategy | | `/api/v1/strategies/{id}` | DELETE | Archive strategy | | `/api/v1/strategies/{id}/state` | PATCH | Transition state | | `/api/v1/strategies/reorder` | POST | Persist lane order | | `/api/v1/intents` | GET | Search intent projections | | `/api/v1/intents/facets` | GET | Intent facets | | `/api/v1/intents/{intent_id}/events` | GET | OMS event log | | `/api/v1/intents/{intent_id}/fills` | GET | Fills for one intent | | `/api/v1/fills` | GET | Search fills | | `/api/v1/simulations/backtest` | POST | Run a historical strategy simulation | | `/api/v1/simulations/ahead` | POST | Run a forward-looking simulation | | `/api/v1/simulations/saved` | GET/POST | List or save simulations | | `/api/v1/simulations/saved/{simulation_id}` | GET/DELETE | Read or delete a saved simulation | | `/api/v1/simulations/saved/lookup` | POST | Find an existing saved simulation for the same inputs | | `/api/v1/vaults/{vault_id}` | GET/PATCH | Vault engine config and emergency locks | | `/api/v1/engine/status` | GET | Engine status | | `/api/v1/engine/shards/{vault_id}/state` | GET | Live shard state |