OMS API — DeFiX Intents & Session Keys

The OMS implements the DeFiX intent execution path. The Strategy Engine publishes intents; OMS validates authorization, builds execution, submits hook transactions, and emits lifecycle events / fills back to operators. Base URL: https://oms.superform.xyz Auth: Authorization: Bearer <jwt> In normal dashboard operations, managers do not submit intents directly. They configure strategies and monitor the resulting intent history.

Intent Lifecycle

OMS intent state is explicit and event-driven:

RECEIVED → ACKED → STAGED → PLANNED → EXECUTING → COMPLETED
                                      ↘ ABORTED
                                      ↘ EXPIRED
                                      ↘ FAILED
                                      ↘ CANCELED

State values:

State	Meaning
`RECEIVED`	OMS received the intent
`ACKED`	Intent accepted for processing
`STAGED`	Intent staged for planning/execution
`PLANNED`	Route or execution plan built
`EXECUTING`	Transaction execution in progress
`COMPLETED`	Execution completed
`ABORTED`	OMS aborted before success
`EXPIRED`	Intent expired before execution
`FAILED`	Execution failed
`CANCELED`	Intent cancelled before terminal execution

Terminal states cannot be modified.

Submit Intent

POST /defix/intents

Typical requests include:

vault_id
strategy_id
action
objective
action_config
auth
merkle proof / root data
account mode (OMS, EIP4337, EIP4337_COMPANION, or EIP7702)

OMS validates the intent and authorization before execution.

Get Intent

GET /defix/intents/{intent_id}

Returns the current OMS state, latest sequence number, timestamps, and completion timestamp when available. Fields such as completed_at may be null before terminal execution.

Cancel Intent

POST /defix/intents/{intent_id}/cancel

Cancellation is only valid before the intent reaches a terminal state.

Intent Events

GET /defix/intents/{intent_id}/events

Events are the source of truth for lifecycle reconstruction. Each event has:

event_id
intent_id
execution_id
message_type
seq_num
event-specific payload
created_at

The Strategy Engine consumes these events and projects them into operator-friendly intent history.

Fills and Mined Transactions

Fills represent confirmed onchain execution evidence. In the operator UI, fills may include:

tx_hash
chain_id
amount_in
amount_out
token_in
token_out
venue
gas_used
mined / fill timestamp

Pre-receipt rows can have null gas or missing fill fields until the transaction is mined and backfilled.

Hook Transactions and Account Modes

OMS supports native hook transaction execution and smart-account/user-operation modes. Account mode controls how execution is signed and submitted:

Mode	Meaning
`OMS`	OMS-managed delegated signer path
`EIP4337`	ERC-4337 user operation path
`EIP4337_COMPANION`	Companion 4337 path
`EIP7702`	EIP-7702 account path

The hook transaction adapter handles execution against SuperVault hooks once session-key and merkle authorization are valid.

Session Keys

Strategy automation requires a valid session key for the vault.

Readiness

GET /defix/vaults/{vault_id}/session-key/readiness

Returns whether the vault has a valid session key and whether a rotation is pending.

Grant

GET /defix/vaults/{vault_id}/session-key/grant

Returns calldata to grant a session key. The manager signs and submits the transaction.

Rotate / Renew

GET /defix/vaults/{vault_id}/session-key/rotation
POST /defix/vaults/{vault_id}/session-key/rotation/complete
POST /defix/vaults/{vault_id}/session-key/rotation/cancel

Complete rotation after the grant/revoke transactions have mined.

Revoke

GET /defix/vaults/{vault_id}/session-key/revoke

Returns calldata to revoke the current session key.

Session-key endpoints return transaction data for wallet signing. They do not bypass onchain permission checks.

Endpoint Inventory

Endpoint	Method	Description
`/defix/intents`	POST	Submit intent
`/defix/intents/{intent_id}`	GET	Current intent state
`/defix/intents/{intent_id}/cancel`	POST	Cancel non-terminal intent
`/defix/intents/{intent_id}/events`	GET	Intent event log
`/defix/vaults/{vault_id}/session-key/readiness`	GET	Session-key readiness
`/defix/vaults/{vault_id}/session-key/grant`	GET	Prepare grant calldata
`/defix/vaults/{vault_id}/session-key/rotation`	GET	Prepare rotation calldata
`/defix/vaults/{vault_id}/session-key/rotation/complete`	POST	Complete rotation
`/defix/vaults/{vault_id}/session-key/rotation/cancel`	POST	Cancel pending rotation
`/defix/vaults/{vault_id}/session-key/revoke`	GET	Prepare revoke calldata

Getting Started

Vault Setup

Vault Operations

Access & Settings

Distribution

Safety & Incident Response

Automation

API Reference

OMS API — DeFiX Intents & Session Keys

Intent Lifecycle

Submit Intent

Get Intent

Cancel Intent

Intent Events

Fills and Mined Transactions

Hook Transactions and Account Modes

Session Keys

Readiness

Grant

Rotate / Renew

Revoke

Endpoint Inventory

​Intent Lifecycle

​Submit Intent

​Get Intent

​Cancel Intent

​Intent Events

​Fills and Mined Transactions

​Hook Transactions and Account Modes

​Session Keys

​Readiness

​Grant

​Rotate / Renew

​Revoke

​Endpoint Inventory

Intent Lifecycle

Submit Intent

Get Intent

Cancel Intent

Intent Events

Fills and Mined Transactions

Hook Transactions and Account Modes

Session Keys

Readiness

Grant

Rotate / Renew

Revoke

Endpoint Inventory