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 Access: The paths below are an upstream service inventory. SuperformOS reaches OMS through its session- and role-checked BFF, which supplies server-side service authentication. Direct integrations require explicit onboarding; these are not curator bearer-JWT endpoints. See Authentication. 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