Skip to main content
The OMS (Order Management System) implements the DeFiX v0.1 protocol: a standardized intent interface for DeFi vault operations. It receives intents from the Strategy Engine and executes them onchain. Base URL: https://oms.superform.xyz Auth: Authorization: Bearer <jwt> OpenAPI spec: oms-openapi.json ✅
The OMS is primarily backend-facing. In normal operations, the Strategy Engine submits intents automatically when strategies trigger. Direct OMS access is relevant for custom strategy implementations or advanced automation.

​
Intent Lifecycle

Submit → Processing → Completed
                   ↘ Failed
                   ↘ Cancelled (only while Processing)
Terminal states (Completed, Failed) cannot be modified.

​
Endpoints

​
Submit Intent

POST /defix/intents

{
  "vault_id": "8453:0xdef...",
  "action": "DEPOSIT",
  "action_config": {
    "size_expr": "1000000000",
    "execution_name": "MorphoDepositHook",
    "execution_address": "0xHookContract...",
    "target_address": "0xMorphoVault...",
    "from_address": "0xVaultContract...",
    "max_slippage_bps": 50,
    "execution_params": {}
  },
  "auth_signing": {
    "proof": "0xmerkleproof...",
    "root": "0xmerkleroot..."
  }
}
Response: 
{
  "id": "intent-uuid",
  "status": "Processing",
  "created_at": "2025-03-01T10:00:00Z"
}

​
Get Intent

GET /defix/intents/{intent_id}

{
  "id": "intent-uuid",
  "vault_id": "8453:0xdef...",
  "action": "DEPOSIT",
  "status": "Completed",
  "created_at": "2025-03-01T10:00:00Z",
  "completed_at": "2025-03-01T10:01:32Z",
  "tx_hash": "0xabc...",
  "gas_used": 180000,
  "error": null
}

​
Cancel Intent

POST /defix/intents/{intent_id}/cancel
Only Processing intents can be cancelled. Returns 409 Conflict if the intent is already terminal.

​
Get Intent Events

GET /defix/intents/{intent_id}/events
State transition log: 
{
  "events": [
    { "timestamp": "2025-03-01T10:00:00Z", "event_type": "submitted", "details": {} },
    { "timestamp": "2025-03-01T10:01:00Z", "event_type": "processing", "details": { "attempt": 1 } },
    { "timestamp": "2025-03-01T10:01:32Z", "event_type": "completed", "details": { "tx_hash": "0xabc...", "gas_used": 180000 } }
  ]
}

​
Intent Status Values

StatusDescription
ProcessingQueued or being executed
CompletedSuccessfully executed onchain
FailedExecution failed (see error in intent detail)
CancelledCancelled before execution

​
DeFiX v0.1 Protocol Notes

  • Intents are idempotent: submitting the same intent twice returns the existing intent (based on vault + action + config hash)
  • The OMS handles nonce management, gas estimation, and transaction broadcasting
  • Failed intents include error messages and may be retried by the Strategy Engine
  • The OMS validates the merkle proof in auth_signing before broadcasting

​
Session Keys

Strategy automation requires a session key — a delegated signing key that authorises the OMS to execute intents on behalf of a vault. The Strategy Canvas shows an omsCanvasGate overlay when the session key is not ready, blocking automation until the key is granted or renewed. vault_id format: {chainId}:{normalizedVaultAddress} (same convention as the Strategy Engine).

​
Check Readiness

GET /defix/vaults/{vault_id}/session-key/readiness
Returns whether the vault has a valid, non-expired session key. Polled automatically by the UI every 45 seconds (25 s stale time); polling accelerates to every 20 s while the signing popover is open. 
{
  "vault_id": "8453:0xdef...",
  "is_ready": true,
  "session_key_address": "0xsessionkey...",
  "expires_at": "2026-04-10T00:00:00Z",
  "pending_rotation": false
}

​
Grant Session Key

GET /defix/vaults/{vault_id}/session-key/grant
Returns calldata to grant a new session key. Pass ?requested_expiry=168h to set a custom duration (defaults to server default). Response: { "to": "0x...", "data": "0x...", "value": "0" } — sign and submit with your wallet.

​
Rotate (Renew) Session Key

GET /defix/vaults/{vault_id}/session-key/rotation
Returns calldata to rotate an existing session key. Used for key renewal before expiry.

​
Complete Rotation

POST /defix/vaults/{vault_id}/session-key/rotation/complete
Finalises a pending rotation after the signed transaction is submitted onchain.

​
Cancel Rotation

POST /defix/vaults/{vault_id}/session-key/rotation/cancel
Cancels a pending rotation that has not yet been completed.

​
Revoke Session Key

GET /defix/vaults/{vault_id}/session-key/revoke
Returns calldata to revoke the current session key immediately.
Grant, rotation, and revoke endpoints return raw EVM calldata — the same prepare pattern used elsewhere in the API. Your wallet signs and submits; no Erebor or OMS endpoint is called for the actual onchain action.

​
Summary

EndpointMethodDescription
/defix/intentsPOSTSubmit DeFiX intent
/defix/intents/{id}GETGet intent state
/defix/intents/{id}/cancelPOSTCancel pending intent
/defix/intents/{id}/eventsGETIntent event log
/defix/vaults/{vault_id}/session-key/readinessGETSession key readiness check
/defix/vaults/{vault_id}/session-key/grantGETGet grant calldata
/defix/vaults/{vault_id}/session-key/rotationGETGet rotation calldata
/defix/vaults/{vault_id}/session-key/rotation/completePOSTComplete pending rotation
/defix/vaults/{vault_id}/session-key/rotation/cancelPOSTCancel pending rotation
/defix/vaults/{vault_id}/session-key/revokeGETGet revoke calldata