Agent guide
Discover Omni for free, then approve each paid MCP tool call.
Omni exposes a stateless Streamable HTTP MCP endpoint. The catalog tool is free; four research tools use x402 MCP payment requirements and a paid retry. A compatible client must understand that lifecycle rather than treating the endpoint as a conventional free MCP server.
At a glance
- Transport
- Streamable HTTP Canonical endpoint under /api/x402/mcp.
- Free tool
- get_market_catalog Discover prices, networks, symbols, and schemas.
- Paid tools
- 4 News, Market Risk, Entity Resolution, and Market Carry.
Why It Matters
What traders and researchers should take away
- Tool-using models can discover exact argument shapes and prices before requesting a paid result.
- An application-owned approval callback keeps the model from becoming the final spending authority.
- The same structured result can be used by a general assistant or a broker-connected research workflow.
How it works
What the product uses behind the scenes
- The native endpoint is https://omniterminal.app/api/x402/mcp using MCP protocol 2025-06-18 and the official @x402/mcp wrapper.
- Coinbase Bazaar offers a separate buyer-facing MCP server that discovers and proxies the nine HTTP products; it is not a duplicate native Omni tool inventory.
- OmniMcpClient validates arguments before the tool call and validates the paid JSON product plus settlement receipt after the retry.
Notes
Things to know
- A generic MCP host that does not support x402 payment metadata can list tools but cannot complete paid calls automatically.
- The SDK denies paid calls when approvePayment is absent or returns false.
- Do not put a funded private key in a desktop client configuration file that is synced, shared, or committed.
Guide
Steps
- Connect the endpoint
Use
https://omniterminal.app/api/x402/mcpas a Streamable HTTP MCP server. - Call the free catalog
Call
get_market_catalogwithout a wallet and inspect tool names, schemas, prices, networks, and supported symbols. - Add a payment policy
Provide a dedicated buyer key only to an x402-aware client, enforce
maxPaymentUsd, and require an application-owned approval callback. - Call one paid tool
Choose
get_market_moving_events,get_market_risk_context,resolve_market_entities, orget_market_carryand validate its receipt and schema.
Safety
Before using this workflow
- Treat tool selection by the model as a request, not final payment approval.
- Reject arguments outside the published allowlists and bounded ranges before payment.
- Use ACM or another buyer policy layer when you need daily budgets, human approval, reconciliation, and revocation.
Next
Open the workflow
- Open Agent Quickstart Compare HTTP, MCP, and SDK paths.
- View MCP source example Run the committed client.
Minimal x402-aware MCP example
The application approves payment; the model does not receive the buyer key.
import { OmniMcpClient } 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 = await new OmniMcpClient({
privateKey,
maxPaymentUsd: 0.003,
approvePayment: ({ toolName, paymentRequired }) => {
console.log({ toolName, accepts: paymentRequired.accepts });
return toolName === "get_market_risk_context";
}
}).connect();
try {
console.log((await client.catalogData()).data); // free
const result = await client.marketRiskData({
symbol: "BTC",
scope: "current",
limit: 5
});
console.log({ schema: result.data.schema, payment: result.payment });
} finally {
await client.close();
}- The free catalog must never trigger payment; the SDK treats that as a contract error.
- The approvePayment callback can inspect the selected tool and current requirements.
- The independent payment-client cap still applies when the callback returns true.
Native tool map
Choose the smallest tool that completes the task.
- get_market_catalog: free discovery.
- get_market_moving_events: 0.001 USDC for bounded equities, crypto, macro, or forex catalysts.
- get_market_risk_context: 0.003 USDC for joined liquidation levels, stress, funding, and news.
- resolve_market_entities: 0.001 USDC for 1–20 current aliases.
- get_market_carry: 0.001 USDC for current 1h funding with mechanical 8h, 1d, and APR context.
Coinbase Bazaar MCP alternative
Use Bazaar when the agent already discovers x402 HTTP resources through Coinbase CDP.
- Connect https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp.
- Call search_resources for Omni and inspect the returned HTTP resource descriptors.
- Pass the selected generated tool name and arguments to proxy_tool_call.
- The proxy returns the same bounded x402 payment requirement and product; the nine Bazaar resources remain HTTP resources.
Native Omni MCP has five tools. Coinbase Bazaar MCP exposes the nine HTTP products through its own search/proxy interface.
References
Implementation references
MCP example
https://github.com/InTheta/omni-universe-sdks/blob/main/packages/typescript/examples/mcp-all-tools.tsGuarded free and paid native tool lifecycle.
MCP client
https://github.com/InTheta/omni-universe-sdks/blob/main/packages/typescript/src/mcp.tsTransport, approvals, validation, and payment result handling.
x402 API reference
omni-terminal/docs/X402_API_REFERENCE.mdNative MCP and Bazaar MCP contracts.