TypeScript SDK
One verified release for Omni data, x402, MCP, and guarded agent examples.
The public repository includes typed clients, validation, bounded retries, settlement checks, no-spend live tests, broker examples, and a separate Hyperliquid testnet-agent package. Install the verified v0.8.0 GitHub tarball for a pinned SDK; repository main currently contains unreleased v0.8.1 source.
At a glance
- x402
- 9 methods Every paid HTTP product has a validated client method and receipt check.
- MCP
- 5 tools One free catalog plus five paid research tools through Streamable HTTP.
- Examples
- 10+ commands REST, WebSockets, x402, MCP, brokers, plus three guarded Hyperliquid testnet agents.
Why It Matters
What traders and researchers should take away
- Typed methods reduce route, parameter, and schema mistakes before a payment or downstream decision.
- The public-boundary tests make it explicit which calls use Omni and which call Hyperliquid directly.
- Broker examples demonstrate a safe research/execution split instead of handing order authority to a data seller.
How it works
What the product uses behind the scenes
- Node.js 20 or newer is required by the package; the root Omni web application uses its own Node version policy.
- OmniClient covers keyed REST, OmniWebSocketClient covers ticketed AI News, and HyperliquidPublicClient/HyperliquidWebSocketClient call public Hyperliquid directly.
- OmniX402Client validates inputs before payment and verifies service/schema discriminants plus PAYMENT-RESPONSE after settlement.
- OmniMcpClient denies paid calls by default and requires an approvePayment callback in addition to the independent per-call cap.
Notes
Things to know
- npm install @omni-terminal/sdk will not work until registry publication; use the v0.8.0 GitHub release tarball or repository source.
- test:live is no-spend, but RUN_PAID_EXAMPLES=true authorizes the example purchase set when a funded EVM_PRIVATE_KEY is present.
- Broker examples require broker credentials even in dry-run where an authenticated preview or signed payload is produced.
- LIVE_TRADING=true changes broker behavior and must remain absent during initial setup.
Install the verified release or verify source
Build the exact package and examples currently reviewed in the public repository.
npm install https://github.com/InTheta/omni-universe-sdks/releases/download/v0.8.0/omni-terminal-sdk-0.8.0.tgz
# Or verify the current source tree:
git clone https://github.com/InTheta/omni-universe-sdks.git
cd omni-universe-sdks/packages/typescript
npm ci
npm run typecheck
npm test
npm run build
npm run test:boundary
npm run test:live- Copy .env.example to .env only when you are ready to add credentials locally.
- The boundary check rejects private hosts and credentials embedded in the distributable package.
- The live suite verifies public contracts and unpaid challenges without setting RUN_PAID_EXAMPLES.
Client map
Choose the narrow client that owns the resource you need.
- HyperliquidPublicClient and HyperliquidWebSocketClient: direct public Hyperliquid instruments, candles, mids, trades, and books; no Omni key.
- OmniClient and OmniWebSocketClient: Omni-owned AI News, Ask Omni, and ticketed public WebSocket products; Omni API key where documented.
- OmniX402Client: ten pay-per-request JSON products with official x402 v2 signing and receipt validation.
- OmniMcpClient: free discovery and five paid native tools with application-owned payment approval.
- CoinbaseAdvancedTradeClient and RobinhoodCryptoClient: optional broker adapters kept separate from Omni research.
Environment and spending controls
Start with no secrets, then add one authority at a time.
OMNI_APP_URL=https://omniterminal.app
OMNI_MCP_URL=https://omniterminal.app/api/x402/mcp
X402_MAX_PAYMENT_USD=0.010
RUN_PAID_EXAMPLES=false
LIVE_TRADING=false
# Add only when deliberately testing paid research:
# EVM_PRIVATE_KEY=0x...
# Add broker credentials only for the matching broker example.- Use a dedicated low-balance EVM wallet for paid research, separate from broker and trading wallets.
- Set RUN_PAID_EXAMPLES=true only for the command you intend to fund, then unset it.
- The all-routes HTTP example buys ten JSON results; the five paid native MCP tools total 0.020 USDC when each is called once. The Ask Omni bundle calculator enforces its own 0.016/0.029/0.039 USDC tier ceilings.
- X402_MAX_PAYMENT_USD caps each call, not the total process budget.
Runnable example index
Each example is committed next to the package it imports.
npm run example:rest
npm run example:ws
npm run example:news-ws
npm run example:x402
npm run example:mcp
npm run example:coinbase
npm run example:robinhood- examples/x402-all-routes.ts and examples/mcp-all-tools.ts default to free/no-spend behavior.
- examples/agents/research.ts lets both broker examples select x402 REST or native MCP research.
- Coinbase performs authenticated preview before any live submission.
- Robinhood dry-run returns the exact signed order payload without transmitting it.
Guarded Hyperliquid testnet agents
A separate package pins every market-data, signing, order, and cancel request to testnet.
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- Momentum and mean-reversion use live testnet candles; Omni Risk uses bounded x402 REST or MCP research.
- The default result is HOLD or a capped ALO preview. Funded execution needs two exact testnet opt-ins.
- The lifecycle caps notional at $25, verifies the passive order, cancels it immediately, and verifies removal.
- Never reuse a mainnet key; x402 payer and Hyperliquid testnet keys remain separate.
References
Implementation references
SDK README
https://github.com/InTheta/omni-universe-sdks/blob/main/packages/typescript/README.mdCanonical release installation, source status, client map, examples, and verification commands.
SDK package manifest
https://github.com/InTheta/omni-universe-sdks/blob/main/packages/typescript/package.jsonDefines package version, scripts, engines, exports, and locked dependencies.
SDK tests
https://github.com/InTheta/omni-universe-sdks/tree/main/packages/typescript/testCovers inputs, response contracts, payment boundaries, MCP, WebSockets, and brokers.
Hyperliquid testnet agents
https://github.com/InTheta/omni-universe-sdks/tree/main/examples/testnet-agentsRunnable, testnet-pinned momentum, mean-reversion, and Omni-risk examples.