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

# OMS API — DeFiX Intents & Session Keys

> Submit, track, cancel, and execute DeFiX intents, including session-key readiness for strategy automation.

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:

```text theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
POST /defix/intents/{intent_id}/cancel
```

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

## Intent Events

```bash theme={null}
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

```bash theme={null}
GET /defix/vaults/{vault_id}/session-key/readiness
```

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

### Grant

```bash theme={null}
GET /defix/vaults/{vault_id}/session-key/grant
```

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

### Rotate / Renew

```bash theme={null}
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

```bash theme={null}
GET /defix/vaults/{vault_id}/session-key/revoke
```

Returns calldata to revoke the current session key.

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

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