OMNITERMINAL / DOCS

Agent guide

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

The public testnet-agent package uses the source SDK’s shared guarded executor and has no configurable Hyperliquid API URL. It resolves live testnet asset IDs and defaults to HOLD or preview. A separately authorized funded run requires both exact opt-ins, explicit owning account, persistent journal, sufficient collateral and existing builder approval before submitting a capped add-liquidity-only order.

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 Dry-run plans allow 50–500 bps offsets; funded execution requires exactly 200 bps.

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.
  • A separately authorized funded run exercises order placement, open-order verification, cancellation, and post-cancel verification 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.12 or newer is required by the standalone example package; build its sibling source SDK before installing the examples. 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

    Build the pinned sibling SDK, install locked dependencies and follow the no-order commands below. They explicitly disable trading and paid research and omit the signed-request 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. Always set the exact owning testnet account address, including for a master signer. The instrument must start flat, with full-notional testnet collateral and existing approval for the configured Omni builder fee.

  4. Enable one bounded lifecycle deliberately

    Provision a private persistent journal for the first run, then reuse it for reconciliation. Set the exact funded prerequisites below and both execution opt-ins only for the authorized 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
# Node.js 22.12+; source verified 15 October 2026
git clone https://github.com/InTheta/omni-universe-sdks.git
git -C omni-universe-sdks checkout --detach 763bbd2e85a248118be0a45d391326a02a24de2d
cd omni-universe-sdks/examples/testnet-agents
npm --prefix ../../packages/typescript ci
npm --prefix ../../packages/typescript run build
npm ci
export RUN_TESTNET_ORDERS=false CONFIRM_TESTNET_ORDER= RUN_PAID_RESEARCH=false
export HL_TESTNET_PRIVATE_KEY= EVM_PRIVATE_KEY=
npm run verify
npm run test:live
npm run example:momentum
npm run example:mean-reversion
npm run example:omni-risk:demo
  • These commands force trading and paid research off even if your shell or .env previously enabled them. They do not run test:signed or submit an order request.
  • The broader verify:live script additionally sends a signed request from a newly generated unfunded wallet and expects rejection. It is no-spend, not a strictly read-only test; it is deliberately omitted here.

Enable one funded testnet lifecycle

Only after separate authorization: exact owner, dedicated testnet key, persistent journal and all venue prerequisites are required.

dotenv
HL_TESTNET_PRIVATE_KEY=0x...
HL_TESTNET_ACCOUNT_ADDRESS=0x...
TESTNET_JOURNAL_DIRECTORY=/absolute/private/testnet-agent-journal
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
  • The no-order shell intentionally overrides .env. A separately authorized funded run needs a separate protected session with these managed values; editing .env alone will not override exported false or blank variables. Never put a private key in shell history.
  • HL_TESTNET_ACCOUNT_ADDRESS must always identify the owning account; never leave it blank, including for a master key.
  • The exact instrument must start flat with full-notional testnet collateral and pre-existing Omni builder approval of at least 25 tenths of a basis point (2.5 bps). This example does not create that approval.
  • Set TESTNET_ORDER_OFFSET_BPS=200 exactly. Keep the journal private and persistent; never delete or replace it to retry an ambiguous submission.
  • Only for the separately authorized run, use npm run test:order and require resting-order plus post-cancel checks to pass. Restore the no-order environment afterward.

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

    Choose a pinned SDK release or current source, then verify the integration.

  • Agent guide

    Buy one bounded Omni result over standard x402 HTTP.

  • Agent guide

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

Omni Terminal / Universe community

Join Omni Discord for product tutorials, support, feedback, Universe research, x402 agents, points and referrals, and roadmap discussions. Pinned walkthroughs cover Ask Omni, basket trading, scaled orders, private TWAPs, liquidation buckets, trader profiles, L4, and mobile.

Complete Sledgehammer verification inside the server. Verification never requires a wallet connection, payment, seed phrase, or private key. Moderation logs stay private; captcha does not guarantee protection from human scammers. Confirm links here and treat unsolicited DMs with caution.

Docs live at /docs/*. The /terminal/docs/* paths show the same pages inside the terminal.