> ## 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 <jwt>`

<Note>
  `vault_id` uses `{chainId}:{vaultAddress}` format, for example `8453:0xdef...`. Erebor often uses separate `chain_id` and `vault_address` fields.
</Note>

## 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](/curate/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.

## 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/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                        |