OMNITERMINAL / DOCS

Agent guide

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

The public testnet-agent package is isolated from the data SDK and has no configurable Hyperliquid API URL. It resolves live testnet asset IDs, defaults to HOLD or preview, and requires two exact opt-ins before it can place a capped add-liquidity-only order that is verified, cancelled, and verified closed.

At a glance

Strategies
3 examples Momentum, mean-reversion, and Omni-risk research use the same guarded lifecycle.
Default
HOLD / preview No funded order is submitted without both exact testnet opt-ins.
Order cap
$25 maximum ALO prices stay 50–500 basis points away from the live midpoint.

Why It Matters

What traders and researchers should take away

  • A strategy can be tested against live testnet metadata without copying mainnet asset IDs or endpoints.
  • Order placement, open-order verification, cancellation, and post-cancel verification are exercised as one lifecycle.
  • Omni research payment authority and Hyperliquid testnet order authority remain separate secrets.

How it works

What the product uses behind the scenes

  • Node.js 22 is used by the standalone example package; every Hyperliquid call is pinned to api.hyperliquid-testnet.xyz.
  • Signals below TESTNET_MIN_CONFIDENCE become HOLD and notional is bounded by TESTNET_MAX_NOTIONAL_USD.
  • Omni-risk can use x402 REST or native MCP and hard-caps paid research at $0.01 per call.
  • The funded lifecycle uses a testnet master key or approved API wallet plus its owning account address.

Notes

Things to know

  • These are integration demonstrations, not profitable strategies or investment advice.
  • Never reuse a mainnet private key or fund the testnet agent wallet with real assets.
  • The Hyperliquid testnet faucet has its own eligibility requirements; follow the official testnet documentation.
  • Scheduled and pull-request CI never enables the funded order lifecycle.

Guide

Steps

  1. Verify the package without credentials

    Install locked dependencies and run verify:live to exercise public data plus an unfunded signed-contract probe.

  2. Run dry-run strategies

    Run momentum, mean-reversion, and omni-risk:demo; inspect every HOLD decision or capped order plan.

  3. Create a dedicated testnet authority

    Use a testnet-only master or approved API wallet and set its owning testnet account address when required.

  4. Enable one bounded lifecycle deliberately

    Set RUN_TESTNET_ORDERS=true and CONFIRM_TESTNET_ORDER=HYPERLIQUID_TESTNET_ONLY for the single command.

  5. Verify cancellation and remove secrets

    Require the test to confirm the order no longer exists, then unset the execution opt-ins and key.

Safety

Before using this workflow

  • Keep EVM_PRIVATE_KEY and HL_TESTNET_PRIVATE_KEY in separate secret scopes.
  • Reject any runtime that does not identify itself as Hyperliquid testnet.
  • Do not increase caps until the exact place, verify, cancel, and verify-closed flow passes repeatedly.
  • Treat an ambiguous submission or cancellation as a reconciliation event, never as permission to retry with a new intent.

Next

Open the workflow

Run the no-order path

The demo and strategy commands read live testnet data but do not transmit orders.

bash
git clone https://github.com/InTheta/omni-universe-sdks.git
cd omni-universe-sdks/examples/testnet-agents
npm ci
npm run verify:live
npm run example:momentum
npm run example:mean-reversion
npm run example:omni-risk:demo
  • verify:live includes unit checks, live public testnet reads, and an ephemeral unfunded signed-request probe.
  • The three example commands remain HOLD or preview-only unless the exact funded gates are present.

Enable one funded testnet lifecycle

Both exact opt-ins and a dedicated testnet key are required.

dotenv
HL_TESTNET_PRIVATE_KEY=0x...
HL_TESTNET_ACCOUNT_ADDRESS=0x...
RUN_TESTNET_ORDERS=true
CONFIRM_TESTNET_ORDER=HYPERLIQUID_TESTNET_ONLY
TESTNET_MAX_NOTIONAL_USD=15
TESTNET_ORDER_OFFSET_BPS=200
TESTNET_MIN_CONFIDENCE=0.55
  • Leave HL_TESTNET_ACCOUNT_ADDRESS blank only when the key is the master wallet itself.
  • Run npm run test:order and require resting-order plus post-cancel checks to pass.

Add paid Omni research without merging authority

The research wallet can pay for context but cannot sign a Hyperliquid order.

  • Set OMNI_RESEARCH_TRANSPORT=x402 or mcp and RUN_PAID_RESEARCH=true for one intended call.
  • The EVM buyer key goes only to the payment client; the testnet key goes only to Hyperliquid signing.
  • Missing, stale, weak-confidence, or failed research produces HOLD.

References

Implementation references

  • Testnet agent package

    https://github.com/InTheta/omni-universe-sdks/tree/main/examples/testnet-agents

    Canonical scripts, environment gates, strategies, and lifecycle tests.

  • Universe SDK

    https://github.com/InTheta/omni-universe-sdks/tree/main/packages/typescript

    Typed Omni research and payment clients used by the Omni-risk example.

  • Hyperliquid testnet documentation

    https://hyperliquid.gitbook.io/hyperliquid-docs/onboarding/testnet-faucet

    Official network funding and faucet requirements.

Next

  • Agent quickstart

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

  • TypeScript SDK

    One verified release for Omni data, x402, MCP, and guarded agent examples.

  • Agent guide

    Buy one bounded Omni result over standard x402 HTTP.

  • Agent guide

    Discover Omni for free, then approve each paid MCP tool call.