OMNITERMINAL / DOCS

Private TWAPs

Two managed executors, one rule: the selected account scope never drifts.

Omni exposes a personal Private · Omni managed TWAP and a separate managed-vault TWAP path. Both schedule ordinary builder-tagged child orders, but they use different sessions, signers, storage, and account scopes. Personal Private TWAP is enabled on mainnet and testnet on Omni dev and production, with isolated endpoints, task stores, leases, and agents for each network. Both paths fail closed when identity, network, task ownership, market scope, builder configuration, or reconciliation is uncertain.

At a glance

Networks
Mainnet + testnet Personal Private TWAP is live on both; managed-vault TWAP retains its own launch policy.
Child orders
ALO or market IOC The server injects the nonzero builder and bounds market IOC slippage; callers cannot override the builder.
State
Durable tasks Task intent, child ownership, fills, remaining size, and VWAP are reconciled server-side.

Why It Matters

What traders and researchers should take away

  • A long-running order does not require an execution key to remain in the browser.
  • Personal and vault balances, positions, fills, and task tables cannot overwrite one another after a scope switch.
  • Cancellation reports the confirmed terminal outcome instead of treating an HTTP success as proof that execution stopped.

How it works

What the product uses behind the scenes

  • Personal Private TWAP uses the purpose-specific omni-ptwap API agent and isolated encrypted server storage; it never falls back to the general trading agent.
  • Managed-vault TWAP uses the short-lived vault session and executor assigned to that vault; tasks appear in the normal TWAP Active and History tables.
  • Personal Private TWAP validates first-DEX and HIP-3 perp identifiers against live metadata, derives HIP-3 asset IDs from the live DEX index, and scopes position and open-order reads to that DEX.
  • Every partial child requires at least $10 of live limit-price notional except an exact verified reduce-only residual close.
  • An optional UTC start is server-enforced. An optional inclusive midpoint trigger delays execution until at_or_below or at_or_above matches, then starts the full runtime.
  • Market mode uses a slippage-bounded IOC limit (default 50 bps, allowed 1–500 bps); post-only mode retains maker-only ALO behavior.
  • The browser supplies strategy inputs, never builder fields, signer material, or an upstream executor URL.
  • Personal Private TWAP uses exact per-network HTTPS endpoints plus isolated Redis namespaces, leases, task indexes, and Mongo agent records, so a network switch cannot redirect or reuse another network's authority.

Notes

Things to know

  • Private TWAP is not Hyperliquid native TWAP and is not a basis strategy; choose post-only ALO or explicitly slippage-bounded market IOC children.
  • A price trigger controls when the schedule begins; it is not a per-slice price cap. PnL-plus-fee triggers remain unavailable until account-versus-position scope and authoritative fee semantics are defined.
  • Personal Private TWAP is available for a personal master account on mainnet and testnet; it is not selectable in a managed-vault workspace.
  • In-place modify remains disabled where builder retention cannot be proven; cancel and replace instead.
  • Mainnet carries real financial risk. Keep notional and concurrency caps conservative, monitor builder-fee reconciliation, and maintain emergency unwind drills and independent review.

Select the executor by account scope

A visible account choice determines every downstream read and write.

  • Personal master: Custom → TWAP → Private · Omni managed; wallet-owned master, purpose-specific omni-ptwap signer.
  • Managed vault: the normal TWAP ticket and private tables remain visible, but all state and writes bind to the selected vault and vault executor.
  • An active vault-leader session is an authenticated terminal identity on desktop, tablet, mobile, and PWA: header identity, Ask Omni, vault-scoped Points, margin mode, account summaries, Assets, and private tables remain available.
  • Trading parity does not grant custody or personal-account authority: funding, transfers, personal agent keys, linked-wallet settings, IBKR, subscriptions, and email/Google profile features stay outside the vault bearer.
  • Changing wallet, network, vault, session, or connection epoch invalidates stale requests and delayed snapshots.
  • Locked vault mode cannot fall through to personal or general-agent execution.

Durable task lifecycle

Intent is persisted before risk and every child is reconciled before terminal status.

  • Persist task schedule and child ownership before submitting risk-accepted work.
  • After the optional UTC and midpoint gates pass, build an ALO maker or slippage-bounded IOC child from live BBO, inject builder configuration, sign server-side, then observe order and fill state.
  • Cancel any remainder, reconcile requested and filled quantity plus VWAP, then publish Active or History state.
  • Treat failed_unreconciled or ambiguous submit/cancel as an error requiring reconciliation—not a successful terminal state.

Security and recovery rules

Signer lifecycle and task recovery remain purpose-specific.

  • Disabling personal Private TWAP removes its ciphertext and cached signer without changing interactive trading authority.
  • Rotation and disable are blocked while the same master retains active child intent, including unreconciled failed tasks.
  • A vault bearer remains in memory, vault-scoped, short-lived, and cannot fund, withdraw, transfer, manage keys, or change the builder.
  • A never-started scheduled task may resume after restart only with zero child intent, zero submitted slices, and zero fills; started schedules still fail closed instead of bursting stale orders.
  • Restart and Redis-loss drills must prove nonce fencing, idempotency, fill backfill, cancel-all, and reduce-only unwind before public-money release.

References

Implementation references

  • Private TWAP account model

    omni-terminal/docs/WALLET_LINKING_MODEL.md

    Purpose-specific signer storage, account scope, builder injection, and lifecycle invariants.

  • Managed vault execution model

    omni-terminal/docs/MANAGED_VAULT_TRADING.md

    Vault session, standard private tables, managed TWAP, gateway, and recovery contract.

  • Vault SDK managed TWAP example

    https://github.com/InTheta/hl-vault-sdk/blob/main/examples/managed-twap.ts

    Public client-side preview and task submission pattern for the vault executor.

Next

  • Vault SDK

    Make a managed vault another account scope in any terminal.

  • Agent quickstart

    Give an agent bounded market intelligence in the way it already works.

  • Agent guide

    Prove the complete decision-to-order lifecycle without creating a mainnet path.

  • Terminal & API Architecture

    A split API and stream chain designed for browser UX and external clients.