One-Time Venue Executions

Submit one native venue action through a managed wallet.

A one-time execution submits one native venue action through Superior's managed-wallet boundary. New integrations use one stable envelope:

json
{
  "venue": "hyperliquid",
  "action": {
    "type": "updateLeverage",
    "asset": 0,
    "isCross": true,
    "leverage": 3
  }
}

venue and action are required. action is a non-empty native venue object; the public OpenAPI and MCP schemas do not impose an action-type allowlist. Schema acceptance does not guarantee that every action can run. The configured venue provider must recognize a supported signing family and be able to canonicalize, sign, submit, and classify the action safely. Otherwise the API returns native_action_unsupported. Adapter validation happens before an execution record is claimed, a wallet is resolved, or signing begins, so only actions that pass preflight enter the durable idempotency lifecycle.

Existing integrations that use the established Hyperliquid order/cancel or Polymarket market-order/cancel shapes remain compatible. Treat those as compatibility behavior, not as a complete list of native actions.

Use the venue's native field names and formats:

POST/runtime/executions

Use an API key with trade or all permission and send Idempotency-Key. account_address is optional and selects one of your account-owned managed wallets; when omitted, Superior uses the default active account.

Hyperliquid native action

bash
curl -X POST https://api.superior.trade/runtime/executions \
  -H "x-api-key: st_live_…" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: leverage-20260909-001" \
  -d '{
    "venue": "hyperliquid",
    "action": {
      "type": "updateLeverage",
      "asset": 0,
      "isCross": true,
      "leverage": 3
    }
  }'

Polymarket native action

json
{
  "venue": "polymarket",
  "action": {
    "type": "placeMarketOrder",
    "tokenID": "1234567890",
    "side": "BUY",
    "amount": "10",
    "price": 0.55,
    "orderType": "FOK"
  }
}

This example uses a provider-supported Polymarket CLOB signing family. Other structurally valid native objects can still return native_action_unsupported when no faithful serializer and signing family are available.

Managed-wallet security boundary

Superior owns server-side signing and transport construction. Do not send credentials, private keys, API secrets, passphrases, signatures, nonces, signing timestamps, authorization data, headers, HTTP methods, paths, hosts, URLs, or endpoints anywhere inside action. These fields are rejected recursively with server_owned_field before provider submission. The server selects the managed key, credentials, signing domain, nonce, timestamp, headers, method, path, and endpoint.

Caller-supplied executable code and additional top-level fields are also rejected. Responses, stored records, and errors are sanitized and never expose signing material or venue credentials.

Submission, idempotency, and reconciliation

The request remains synchronous through the initial venue call:

  1. Superior validates the envelope and claims the durable idempotency record.
  2. It resolves an execution-ready managed wallet and a configured venue provider.
  3. It prepares and signs the native action, persists submission identity, and submits exactly once.
  4. A definite result is stored before the response. An uncertain result stays durable for reconciliation.

Reusing the same Idempotency-Key with the same body returns the same execution record without signing or submitting again. Reusing it with different input returns 409 idempotency_key_conflict.

  • 201 means the action reached a terminal result.
  • 202 means submission identity is durable while the venue outcome is being reconciled.

After 202, poll GET /runtime/executions/{id}. A timeout, disconnect, rate limit, or malformed venue response after submission is treated as an unknown outcome and is never blindly resubmitted. If the provider cannot prove the outcome by the reconciliation deadline, status becomes reconciliation_required; resolve that state operationally before attempting another action.

json
{
  "id": "exec_01k…",
  "status": "succeeded",
  "venue": "hyperliquid",
  "action_type": "updateLeverage",
  "account_address": "0x1234…",
  "created_at": "2026-09-09T00:00:00Z",
  "finished_at": "2026-09-09T00:00:01Z",
  "result": { "status": "ok", "response": {} }
}

Runtime availability

Returns durable one-time venue execution records in { "executions": [...], "next_cursor": null }. These database-backed reads remain available when live venue execution is not configured. Results are sanitized and never include signing material or venue credentials.

One-time execution is operational only when the execution repository, managed-wallet service, venue providers, and reconciliation worker are configured together. If that provider family is incomplete, capability discovery reports execution as unavailable and calls return execution_provider_unavailable without claiming an execution. A configured runtime submits supported signing families and records their durable outcomes; the open native schema alone is not evidence that a particular action family is operational.

Older versioned execution operations remain available for compatible clients until a separately announced sunset. New integrations should use /runtime/executions and should check live capability and wallet readiness instead of inferring support from an older endpoint.

Read execution records

Returns one owned execution record from durable storage without triggering venue reconciliation. There is no execution logs endpoint because the API runs typed venue operations, not scripts.

GET /runtime/executions returns { "executions": [...], "next_cursor": null }. GET /runtime/executions/{id} returns one owned record. There is no execution logs endpoint because the API submits venue actions, not scripts.

Venue rejections return 422 exchange_rejected. error.details.exchange_error contains the sanitized exchange response; fields containing credentials, secrets, passwords, authorization data, signatures, private keys, or tokens are removed, and sensitive-looking string values are redacted. The same sanitized details are stored on the durable execution and returned by subsequent execution reads.

json
{
  "error": {
    "code": "exchange_rejected",
    "message": "The venue rejected the execution",
    "docs_url": "https://docs.superior.trade/runtime/executions",
    "details": {
      "exchange_error": {
        "status": "err",
        "response": "Order could not immediately match against any resting orders."
      }
    }
  }
}

Other common errors include 400 validation_failed, 400 native_action_invalid, 400 server_owned_field, 403 insufficient_permissions, 403 account_not_owned, 409 idempotency_key_conflict, 409 account_not_ready, 422 native_action_unsupported, 502/503 execution_provider_unavailable, and 503 execution_store_unavailable.

Market search documents only query and limit:

http
GET /context/markets?query=BTC%20perpetual&limit=20

Deployment lifecycle changes use:

http
PUT /runtime/deployments/{id}/status

PATCH /runtime/deployments/{id} remains the metadata-update route.

Previous
Frameworks
Next
Deployments