Agent guide

Buy one bounded Omni result over standard x402 HTTP.

The safest integration begins with an unpaid request. The returned challenge declares the exact resource and payment terms; the buyer then decides whether to sign and retry. Omni receives the payment proof, never the buyer private key.

At a glance

Discovery: HTTP 402 Inspect terms before signing or paying.
Products: 9 routes Use the smallest bounded result for the task.
Success: 200 + receipt Validate JSON, freshness, and settlement.

Why It Matters

What traders and researchers should take away

A first request reveals current terms without requiring an Omni account or API key.
A local price and asset policy can reject an unexpected challenge before signing.
Receipt and schema validation prevent a downstream agent from treating an ambiguous response as paid research.

How it works

What the product uses behind the scenes

The SDK uses @x402/core, @x402/evm, and @x402/fetch with an EVM signer and allowlist policy.
Base Sepolia and guarded Base mainnet use canonical USDC assets and exact x402 v2 settlement.
Input validation runs before the payment-aware fetch so invalid symbols, addresses, limits, or batches cannot create avoidable payment attempts.

Notes

Things to know

A funded EVM_PRIVATE_KEY can spend and must stay outside source, logs, browser bundles, and screenshots.
Do not retry an uncertain settlement automatically; reconcile the transaction or receipt first.
Do not treat a successful payment as trading authorization.

Guide

Steps

Inspect a challenge without paying
Run curl -i https://omniterminal.app/api/x402/v1/market-risk/BTC?scope=current&event_window_minutes=60&limit=5 and confirm HTTP 402 plus PAYMENT-REQUIRED.
Configure the buyer locally
Use a dedicated low-balance wallet, set X402_MAX_PAYMENT_USD=0.003, and keep RUN_PAID_EXAMPLES=false during discovery.
Call one typed method
Construct OmniX402Client with createEvmPaymentClient, then request the smallest product needed by the agent.
Validate before use
Require the expected service/schema, acceptable data_as_of and freshness, plus a successful PAYMENT-RESPONSE transaction and network.

Safety

Before using this workflow

Start on Base Sepolia when validating a new buyer integration.
Use a per-call cap and a separate aggregate budget or approval layer.
Stop on missing freshness, missing receipt, malformed JSON, unknown asset/network, or ambiguous settlement.

View all products Choose a route and schema.
Open the HTTP contract Inspect bounded inputs.

Minimal typed HTTP example

This code buys one Market Risk Snapshot only when the caller supplies a funded key.

javascript

import { createEvmPaymentClient, OmniX402Client } from "@omni-terminal/sdk";

const privateKey = process.env.EVM_PRIVATE_KEY;
if (!privateKey?.startsWith("0x")) throw new Error("EVM_PRIVATE_KEY is required");

const client = new OmniX402Client({
  paymentClient: createEvmPaymentClient(privateKey, {
    maxPaymentUsd: 0.003
  })
});

const { data, payment } = await client.marketRisk("BTC", {
  scope: "current",
  event_window_minutes: 60,
  limit: 5
});

if (data.schema !== "market_risk_snapshot.v1" || !payment?.success) {
  throw new Error("Paid result failed contract validation");
}
console.log({ dataAsOf: data.data_as_of, payment });

Run from omni-universe-sdks/packages/typescript until the npm package is published.
The SDK independently filters network, canonical USDC asset, and amount before it signs.
Use the response only after checking product-specific freshness and component status.

Failure and retry policy

Payments require stricter retry rules than ordinary idempotent reads.

400 means fix the bounded request before trying again.
402 means inspect and approve current terms; it is not an application error.
503 means the payment or bounded upstream is unavailable; do not infer a neutral market signal.
A network timeout after signing or submission is uncertain settlement state; reconcile before retrying.

Run the guarded all-routes example

The committed example is free by default and visibly armed for paid mode.

bash

npm run example:x402

# Paid mode: buys every route once. Current total list price: 0.016 USDC.
EVM_PRIVATE_KEY=0x... X402_MAX_PAYMENT_USD=0.003 RUN_PAID_EXAMPLES=true npm run example:x402

Do not paste a production or broker wallet key into this example.
Unset RUN_PAID_EXAMPLES immediately after the bounded test.
Review each returned payment receipt rather than treating process exit alone as proof.

References

Implementation references

HTTP example
https://github.com/InTheta/omni-universe-sdks/blob/main/packages/typescript/examples/x402-all-routes.ts
Guarded free and paid route matrix.
HTTP client
https://github.com/InTheta/omni-universe-sdks/blob/main/packages/typescript/src/x402.ts
Payment policies, inputs, response contracts, and receipts.
OpenAPI
omni-terminal/static/openapi-x402.yaml
Published bounded HTTP contract.

At a glance

What traders and researchers should take away

What the product uses behind the scenes

Things to know

Steps

Before using this workflow

Open the workflow

Minimal typed HTTP example

Failure and retry policy

Run the guarded all-routes example

Implementation references

HTTP example

HTTP client

OpenAPI

Next pages