Skip to main content

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.

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>
vault_id uses {chainId}:{vaultAddress} format, for example 8453:0xdef.... Erebor often uses separate chain_id and vault_address fields.

​
Strategies

​
List Strategies

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

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

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

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

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

KindDescription
USER_DEFINEDManager-authored strategy visible in normal canvas flows
EMERGENCY_EXITSystem-managed withdrawal strategy paired to one whitelisted yield source
EMERGENCY_EXIT strategies are controlled from Pause Operations. They are read-only in normal strategy editing flows.

​
Vault Config and Shards

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: 
{
  "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

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

GET /api/v1/intents/facets
Returns counts by state, action, chain, vault, and strategy for filter UIs.

​
Events and Fills

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

EndpointMethodDescription
/api/v1/strategiesGETList strategies
/api/v1/strategiesPOSTCreate strategy
/api/v1/strategies/{id}GETGet strategy
/api/v1/strategies/{id}PUTUpdate strategy
/api/v1/strategies/{id}DELETEArchive strategy
/api/v1/strategies/{id}/statePATCHTransition state
/api/v1/strategies/reorderPOSTPersist lane order
/api/v1/intentsGETSearch intent projections
/api/v1/intents/facetsGETIntent facets
/api/v1/intents/{intent_id}/eventsGETOMS event log
/api/v1/intents/{intent_id}/fillsGETFills for one intent
/api/v1/fillsGETSearch fills
/api/v1/vaults/{vault_id}GET/PATCHVault engine config and emergency locks
/api/v1/engine/statusGETEngine status
/api/v1/engine/shards/{vault_id}/stateGETLive shard state