Migrating from v1/v2/v3

How every current endpoint maps onto the unified surface.

The current API grew as an engine×venue matrix: /v1 (legacy freqtrade), /v2 (freqtrade·Hyperliquid), /v3 (Nautilus·Polymarket/Lighter) — about 138 endpoints once aliases are counted. The unified surface is ~30. Old prefixes keep accepting their established operations until a separately announced sunset. New integrations should use the Unified contract and inspect its live capability state; compatibility acceptance does not prove that every Unified runtime or native signing family is operational.

The mapping#

Equivalent operations across the previous API surfaces are grouped together. For Superior Skills, these legacy paths are comparison-only: an agent must not fall back to them when the Unified API has no public equivalent.

Existing account-owned legacy v2 Freqtrade backtests on Hyperliquid have a narrower compatibility boundary than newly created Unified API backtests. GET /runtime/backtests/{id} can read their persisted terminal finished or error record by known ID, including only the summary fields originally stored by the previous API; missing canonical result fields are not synthesized. DELETE /runtime/backtests/{id} can tombstone those terminal records without contacting the retired runtime workload. This path does not expand list behavior, and active queued/running status, logs, cancellation, and lifecycle ownership do not migrate through it.

Native execution migration#

Use a trade-scoped API key and Idempotency-Key:

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

The public schema has no action-type allowlist. Execution still requires an operational provider family, an execution-ready managed wallet, and a supported native signing family. Unsupported families return native_action_unsupported; incomplete runtime configuration returns execution_provider_unavailable. Superior owns credentials, signing, nonce, timestamp, headers, method, path, and endpoint. Never copy signed or credential-bearing fields from a versioned request into the Unified action.

Market search for new integrations is:

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

Deployment lifecycle changes use PUT /runtime/deployments/{id}/status; PATCH /runtime/deployments/{id} updates metadata only.

Slimmed from the public surface#

The remaining custody plumbing — /v2|v3/portfolio transfer/exit variants, /v2|v3/authorize-and-send/*, /v2/bracket, /v3/account/:address/{hyperliquid,polymarket,lighter} bootstrap, /v2/account/login-wallet — remains available only for compatibility or Terminal-owned flows. Do not adopt it in a new integration. The Unified surface replaces it with the managed trading wallet, BYOK, and the native execution envelope.

Timeline#

1. Now — Unified ships alongside v1/v2/v3; established versioned operations remain compatible.
2. Runtime rollout — each Unified capability reports whether its required backend is configured. One-time execution submits supported signing families when operational and otherwise fails closed.
3. Deprecation — old prefixes marked deprecated in their OpenAPI spec with Sunset headers on responses; migration window announced with dates, per-endpoint.
4. Sunset — old prefixes return 410 with a docs_url pointing at this page.

Existing st_live_ keys work on both surfaces throughout — migration never requires re-registering.