> ## Documentation Index > Fetch the complete documentation index at: https://docs.useotto.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Otto x402 Storefront > Technical guide for accessing Otto's paid HTTP endpoints via x402 V2, with USDC on Base, Polygon, and Solana. Welcome to the technical documentation for the Otto AI Agent Swarm on x402 V2. While our main [Agent Swarm overview](/introduction/otto-ai-swarm) explains what our agents do, this page provides the specific endpoint details, request parameters, and examples needed for programmatic, agent-to-agent (A2A) integration. All endpoints are accessible via the x402 V2 protocol, allowing any developer or AI agent to pay for and consume our services in real-time. **The Otto AI storefront is consumed by agents, scripts and CLIs — not by a browser.** Discovery is free and works anywhere, including a browser tab. Paying requires a client that can sign, so budget for a terminal or an agent runtime before you get to the paid call. [Which client can actually pay](#which-client-can-actually-pay) covers the split. **Base URL:** `https://x402.ottoai.services` **Networks:** Base Mainnet, Polygon Mainnet and Solana Mainnet. Individual routes may offer a subset — the `accepts` array in each route's 402 challenge is definitive. **Payment:** USDC on Base, Polygon, or Solana. Permit2 infrastructure ready for any ERC-20 token. **Discovery — all four surfaces are free to fetch. No payment, no API key:** | Surface | What it is | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | [`/`](https://x402.ottoai.services) | Content-negotiated root. A browser gets the catalog page; a client sending `Accept: application/json` gets the same catalog as JSON. | | [`/llm.txt`](https://x402.ottoai.services/llm.txt) | Machine-readable catalog — every route with its price, its parameters and a description. Built for agents to read directly. | | [`/openapi.json`](https://x402.ottoai.services/openapi.json) | OpenAPI 3 document, one path per service. | | [`/.well-known/x402`](https://x402.ottoai.services/.well-known/x402) | x402 discovery document (x402scan-compatible), with the full resource list. | The catalog grows and changes, so **read the endpoint count instead of quoting one**: ```bash theme={null} curl -s https://x402.ottoai.services/openapi.json | jq '.paths | length' ``` **Related rails:** [MPP](/acp-swarm/mpp) and [Otto X](/acp-swarm/otto-x) expose overlapping subsets and rail-specific routes. See [Access Paths & Coverage](/acp-swarm/storefront-parity) for current counts and capability coverage. Not sure which endpoint you need? The [Otto X402 Router](/acp-swarm/open-router) (`POST /meta-intelligence`) recommends the best x402 services for your task across both this catalog and the live CDP Bazaar — non-custodial, zero markup, \$0.001 per call (a flat router fee, never a markup on the services it recommends). ## x402 V2 Features | Feature | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Multi-Network** | Pay with USDC on Base, Polygon, or Solana at the same price on whichever networks the route offers — its 402 challenge lists them | | **Permit2 Ready** | Infrastructure supports any ERC-20 token via Permit2. Contact [@useOttoAI](https://twitter.com/useOttoAI) for custom token integrations | | **Sign-in-with-X (SIWX)** | On routes that advertise it, pay once and re-access with a wallet signature instead of paying again. Cached data endpoints do not advertise it and are pay-per-call only — see Step 5 below | | **Bazaar Discovery** | Read-only endpoints listed on CDP Bazaar for automatic AI agent discovery | | **Signed offers** | Every 402 carries an EIP-712 signed offer per payment option, in the `offer-receipt` extension — you can verify the quoted price and recipient before paying | | **In-band content receipt** | Routes advertise an `otto-content-receipt` extension. Where a call settles on an EVM network, the paid response carries that signed EIP-712 receipt in its `PAYMENT-RESPONSE` header — handed to you in the response, with nothing to look up afterwards. It is best-effort and EVM-only; see [After You Pay](#after-you-pay-receipts-and-refunds) for the bounds | | **Payment Identifier** | Execution endpoints support idempotent retries via unique payment IDs | Each 402 challenge advertises exactly which of these it supports. Read them from the live challenge rather than from this table: ```bash theme={null} curl -sD - -o /dev/null https://x402.ottoai.services/crypto-news \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '.extensions | keys' ``` ### Which client can actually pay **There is no browser-based payment path on this storefront.** `x402.ottoai.services` ships no wallet connection and no in-page signing. Opening an endpoint URL in a browser tab returns the `402` challenge as JSON — the price and the payment options — and nothing else. That is the correct and expected behaviour, not an error. Paying requires a client that can sign an EIP-712 / EIP-3009 (or Permit2) authorization and replay the request with a `PAYMENT-SIGNATURE` header. Use an x402 client library or your own signer, as shown under [Client-Side Example](#client-side-example). What the catalog page at [`x402.ottoai.services`](https://x402.ottoai.services) is good for, in a browser: * Browsing every service grouped by capability tag, with its price and its parameter. * Inspecting a route and generating a request URL for it. * Copying a ready-made `curl` command to run in your own terminal or agent. * "Try", which opens the raw endpoint URL in a new tab. That returns the `402` challenge — it does **not** pay, and it does not return data. For the SDK path, the [Client-Side Example](#client-side-example) section on this page shows a complete runnable example. The catalog page's Inspect panel also generates a per-endpoint snippet — both use the real published packages (`@x402/axios`, `@x402/evm`). So the workflow is: discover in the browser, pay from an agent, a script or a terminal. ## Pricing Overview This table is a hand-maintained convenience copy and it does not list every route. **The live `402` challenge is the source of truth for what a call costs**, and [`/llm.txt`](https://x402.ottoai.services/llm.txt) is the source of truth for what exists. Where this table and the live challenge disagree, the challenge wins. | Endpoint | Price (USDC) | Description | | ------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/crypto-news` | \$0.001 | Real-time crypto market news with sentiment | | `/filtered-news` | \$0.001 | AI-filtered news for specific topics | | `/tweet-search` | \$0.005 | Search X/Twitter for any query — real tweets | | `/twitter-summary` | \$0.001 | Curated Twitter/X crypto digest | | `/token-details` | \$0.001 | Token price, market cap, volume, metrics | | `/token-alpha` | \$0.005 | Premium token intelligence with derivatives data | | `/kol-sentiment` | \$0.002 | Top 50 KOL sentiment analysis | | `/yield-alpha` | \$0.002 | DeFi yield opportunities | | `/trending-altcoins` | \$0.002 | Top 3 trending altcoins | | `/mega-report` | \$0.05 | Alpha & Intel Report — comprehensive daily market briefing | | `/token-security` | \$0.001 | Token contract security audit (GoPlus) | | `/funding-rates` | \$0.001 | Derivatives dashboard (funding, OI, whales) | | `/defi-analytics` | \$0.001 | DeFi protocol analytics (TVL, trends) | | `/tradfi-data` | \$0.003 | TradFi macro intelligence (VIX, DXY, yields) | | `/generate-meme` | \$0.15 | Multi-model image gen via fal.ai. `model: gpt-image-2` (default) or `nano-banana-pro`; anything else returns 400. | | `/llm-research` | \$0.10 | AI research assistant (Gemini 3.5 Flash, cited sources) | | `/tx-explainer` | \$0.01 | Decode & explain any EVM transaction (11 chains) | | `/video-gen` | Dynamic | Multi-model video gen via fal.ai (Seedance 2.0, Sora 2, Veo 3.1) — at-cost × 1.15 | | **Trade Execution — Resources** | | | | `/portfolio` | \$0.001 | Multi-chain portfolio with token balances | | `/transaction-history` | \$0.001 | Transaction history for user's Safe account | | `/supported-tokens` | \$0.001 | Search supported tokens by symbol on a chain | | `/hyperliquid-account` | \$0.001 | Hyperliquid account snapshot with positions | | `/hyperliquid-market` | \$0.001 | Hyperliquid market data with live prices | | `/hl-transaction-history` | \$0.001 | Hyperliquid trading transaction history | | `/yield-markets` | \$0.001 | Yield markets with APYs (Aave V3, Morpho) | | `/yield-farming-active` | \$0.001 | Active yield farming positions | | `/yield-farming-historical` | \$0.001 | Historical yield farming positions | | `/idle-capital` | \$0.001 | \[Temporarily unavailable] — per-wallet idle scanner being rebuilt | | `/yield-recommendations` | \$0.001 | Best-available stablecoin deposit venues ranked by net APY | | **Onchain Data** | | | | `/token-top-holders` | \$0.02 | Top holders for any Base ERC-20 + concentration metrics via Moralis | | `/stablecoin-watch` | \$0.001 | Peg deviation, supply flow, dominance for top 30 USD stablecoins (DefiLlama, hourly) | | `/market-risk` | \$0.002 | Composite 0-100 market-stress score: global stablecoin depeg health + Base DEX exit-liquidity, per-leg breakdown + AI risk line (both legs required, hourly) | | `/protocol-revenue-leaders` | \$0.001 | Top 30 DeFi protocols by fees + revenue, take-rate, 7d/30d trend (DefiLlama, hourly) | | `/equity-intel` | \$0.003 | US stock fundamentals + SEC filings intel by ticker (SEC EDGAR) | | `/base-season` | \$0.001 | KOL-ranked quality-screened Base tokens with sentiment: who's talking about what, hourly | | `/rh-season` | \$0.001 | Rug-screened Robinhood Chain (4663) movers: honeypots filtered, rug-risk flags + KOL signal, hourly | | `/news-recaps` | \$0.003 | One-paragraph crypto market recap (4-6 sentences), distilled hourly from the live news engine | | `/base-ecosystem-news` | \$0.001 | Base-chain ecosystem news, AI-filtered hourly: launches, Coinbase/Base moves, Base DeFi | | `/token-fundamentals` | \$0.003 | Structured asset fundamentals by symbol: supply, ATH drawdown, ROI windows, links (CoinGecko) | | `/token-price` | \$0.001 | Onchain DEX token price by symbol or chain:contract — price, 24h change, volume, mcap, liquidity (8 chains) | | `/pools-search` | \$0.001 | Search DEX pools across 8 chains by symbol/name/contract — price, volume, liquidity, FDV per pool | | `/pools-trending` | \$0.001 | Trending DEX pools — top 10 hottest per chain (or `network=all` cross-chain) by 24h trending: price, change, volume, liquidity, FDV | | `/pm-markets` | \$0.001 | Top 25 Polymarket prediction markets by 24h volume — live odds, best bid/ask, spread, volume, liquidity, end date (refreshed every 5 min) | | `/pm-crypto` | \$0.001 | Crypto prediction markets on Polymarket — BTC/ETH price targets and events with live odds, volume, liquidity (refreshed every 5 min) | | `/pm-search` | \$0.001 | Free-text prediction-market search (`?query=`) — top matching open Polymarket markets with live odds, volume, liquidity, end date | | `/insider-trades` | \$0.003 | SEC Form 4 insider trades by ticker — who bought/sold, purchase vs sale values (SEC codes P/S: open-market or private), net purchase-sale balance; hourly snapshot, 4/A-amended windows withheld (\~1h lag, unpaid 503). Unknown/delisted tickers → **404 `unknown_ticker`** (permanent, no retry, no charge). Public-domain EDGAR | | `/institutional-holdings` | \$0.003 | Latest 13F holdings for any SEC-filing manager by CIK or ticker, amendments applied (hourly snapshot, \~1h correction lag) — top 20 positions (SH/PRN-typed, put/call-flagged), reported value, position count. Unknown/delisted tickers → **404 `unknown_ticker`** (permanent, no retry, no charge). | | `/equity-smart-money` | \$0.006 | Smart-money bundle: Form 4 insider activity (P/S purchases vs sales) + TTM fundamentals (revenue/net-income YoY, EPS) in one call; hourly snapshot, 4/A-amended windows withheld (\~1h lag, unpaid 503). Unknown/delisted tickers → **404 `unknown_ticker`** (permanent, no retry, no charge). | | `/equity-smart-money-brief` | \$0.10 | Smart-money filing brief: insider purchases vs sales with filer roles + Schedule 13D/13G beneficial-ownership filing events (subject-validated; not 13F) + fundamentals with one-time-item flags + regime-aware cadence, fused into ONE AI read of the filing record. Observed filings only — buy/sell advice rejected at generation | | `/tokenized-equities` | \$0.001 | The live registry of tokenized US equities & ETFs on Robinhood Chain (4663): symbol, canonical token address, decimals, a reference price + a verifiable tradability signal (listed-on-rail + a best-effort execution sample). Optional `?thesis=` (e.g. `semiconductors`) filters to a matched shortlist (capped at 12, relevance-ordered) with a per-row match reason + honesty contract (`matched`, `matchedCount` = score>0 rows across the whole universe, `fellBackToUniverse`, `matchedTradableSampled`); `universeSize`/`tradableSampled` stay universe-level. Omit for the full registry. The on-chain settlement layer for tokenized-equity exposure, not a data-coverage claim. Informational only; not a quote or recommendation. Refreshed hourly | | `/earnings-calendar` | \$0.003 | Earnings calendar and EPS surprise history for a ticker — next report date/session with EPS and revenue estimates, latest reported EPS vs estimate, surprise %, four-quarter history (Finnhub; monetary values in vendor units). Pay-per-call | | `/analyst-ratings` | \$0.003 | Analyst consensus snapshot for a ticker — rating distribution, high/low/median/consensus price targets, target vs timestamped reference price, recent firm-level grade actions, 90-day upgrade-minus-downgrade momentum (FMP; monetary values in vendor units). Pay-per-call | | `/equity-news` | \$0.003 | Latest licensed headlines for a ticker — up to 20 Finnhub articles from the trailing 7 days with source, publication time, and summary. Only articles that name the company are served, labelled `primary` (named in the headline) or `mentioned` (named in the summary), so a story tagged with the ticker but written about another company never fills the list; vendor redirect URLs withheld; no sentiment (not in payload). Pay-per-call | | `/dividend-intel` | \$0.003 | Dividend intelligence for a ticker — TTM yield, payout ratio and dividend/share, next known ex-date, adjusted complete-year growth, recent payments, yield-trap checklist with explicit coverage (FMP; monetary values in vendor units). Pay-per-call | | `/macro-regime` | \$0.003 | Daily US macro-regime snapshot — 10-year Treasury yield, effective fed funds rate, three-month rate changes, CPI index and YoY inflation, mechanical rates-direction/inflation-direction label with disclosed thresholds (Alpha Vantage; no ticker; scanner context only). Pay-per-call | | `/technical-signals` | \$0.003 | Daily technical signals for a ticker — Wilder RSI-14, 20-session momentum, SMA-20/SMA-50 with price distance from each, above/below/mixed trend state, latest golden/death cross observation (Tiingo; monetary values in vendor units). Pay-per-call | | `/holder-analytics` | \$0.03 | Full holder analytics for a Base ERC-20: total holders + change momentum, whale-tier distribution, acquisition mix, top-N supply share, labeled top holders + AI risk read | | `/wallet-holdings` | \$0.02 | Wallet bagcheck: Base portfolio (up to 100 positions, spam filtered) with USD values, portfolio %, 24h change + concentration and AI read | | **Web & Domain Intelligence** | | | | `/dns-lookup` | \$0.001 | Full DNS for any domain — A/AAAA, MX, NS, CNAME, SOA, TXT + parsed email auth (SPF/DMARC/DKIM) via DNS-over-HTTPS (DoH), keyless | | `/whois-lookup` | \$0.001 | WHOIS/RDAP registration — registrar, status codes, creation/updated/expiry dates, nameservers, DNSSEC (keyless) | | `/domain-age` | \$0.001 | Domain age + creation/expiry dates and days-until-expiry from RDAP — a fast trust/risk signal for vetting a counterparty, link or sender (keyless) | | `/domain-report` | \$0.02 | One-call domain profile: DNS + RDAP registration + email auth (SPF/DMARC/DKIM) + a one-line summary; bundles what would be three calls (keyless) | | `/web-search` | \$0.009 | Neural web search for agents — query → the most relevant live pages with title, URL, published date, author, relevance score + a clean snippet; the find-then-read pair for `/web-extract`, cached by query | | `/web-answer` | \$0.01 | Quick cited answer (Exa upstream) — one concise synthesis plus source URLs and publication dates for fast lookups and agent loops; use `/llm-research` for a deeper multi-section research report, reasoning, image analysis, or webpage summarization; cached by query | | `/web-extract` | \$0.005 | Turn any URL into clean LLM-ready markdown — content + title + description + publish date; renders JS, handles articles/docs/PDFs | | `/web-links` | \$0.003 | Extract every link from a page (incl. JS-revealed), deduplicated — real headless render; for crawling/sitemaps/audits | | `/web-json-extract` | \$0.005 | Web page → structured JSON via AI — title, summary, key entities, prices/dates/numbers; structured data not raw HTML | | **Real-World Data** | | | | `/fx-rates` | \$0.001 | Live + reference FX (base USD): near-real-time mid for the 12 most-traded currencies (EUR/GBP/JPY/CHF/CAD/AUD/NZD/CNY/HKD/SGD/SEK/KRW), refreshed every minute with market-open/stale flags, plus the official ECB daily reference table (\~30 currencies); derive any cross-rate | | `/weather` | \$0.001 | Current weather + 5-day forecast for anywhere — temp, feels-like, humidity, wind, conditions + daily highs/lows & precip; city or lat,lon | | **Trade Execution — Services** | | | | `/swap` | \$0.01 | Token swap from Safe via LI.FI DEX aggregation | | `/bridge` | \$0.01 | Cross-chain bridge from Safe via LiFi | | `/withdraw` | \$0.01 | Withdraw tokens from Safe to wallet | | `/deposit` | Dynamic | Deposit to Safe (amount + \$0.01 fee) | | `/trade-perpetuals` | \$0.01 | Open leveraged perp positions on Hyperliquid | | `/close-position` | \$0.01 | Close perpetual position (full or partial) | | `/modify-hl-order` | \$0.01 | Add/modify/cancel TP/SL and limit orders | | `/update-position-margin` | \$0.01 | Adjust leverage or margin on open positions | | `/hl-deposit-withdraw` | \$0.01 | Deposit/withdraw USDC to/from Hyperliquid | ## How to Make a Request (x402 V2 Flow) Consuming an x402-powered API is a multi-step process. The client (buyer) first makes a request, receives a payment requirement, pays, and then retries the request with proof of payment. ### Step 1: Initial Request (Fails with 402) First, the client makes a standard HTTP request to the desired endpoint. The server responds with **HTTP 402 Payment Required** and a `PAYMENT-REQUIRED` header containing base64-encoded payment options. Fetching a challenge is free — no payment and no key. ```bash theme={null} curl -i "https://x402.ottoai.services/crypto-news" ``` ``` HTTP/2 402 content-type: application/json; charset=utf-8 payment-required: eyJ4NDAyVmVyc2lvbiI6Mi4uLg== ← base64-encoded payment options access-control-expose-headers: PAYMENT-RESPONSE,PAYMENT-REQUIRED,PAYMENT-SIGNATURE,... ``` **The 402 challenge is the source of truth for price.** The pricing table above is a convenience copy and can lag. Whatever the live challenge says a call costs, that is what it costs. Decode it before you pay. Decode the header and read the payment options: ```bash theme={null} curl -sD - -o /dev/null "https://x402.ottoai.services/crypto-news" \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '.accepts[] | {network, amount, asset, payTo, method: .extra.assetTransferMethod}' ``` Each entry in `accepts` is one way to pay for that exact call. `amount` is in the asset's smallest unit — `"1000"` of 6-decimal USDC is \$0.001. A `method` of `permit2` means that option settles via Permit2 rather than EIP-3009. The full decoded object also carries a `resource` block (URL, description, tags) and an `extensions` block. ### Step 2: Client Signs & Pays The client chooses a payment option from the `accepts` array and signs the payment: 1. **USDC on Base** (EIP-3009) — zero-approval, default for most clients 2. **Any ERC-20 on Base/Polygon** (Permit2) — requires Permit2 approval 3. **USDC on Solana** — SPL token transfer This is typically handled by an x402-compatible client library like `@x402/axios`. ### Step 3: Retry Request with Payment Header The client retries the exact same request with a `PAYMENT-SIGNATURE` header containing the signed payment payload. ```bash theme={null} curl "https://x402.ottoai.services/crypto-news" \ -H "PAYMENT-SIGNATURE: eyJ4NDAy..." # base64-encoded signed payment payload ``` You cannot hand-write that header — the value is a signed payload built from the challenge in Step 1. In practice a client library constructs it for you; see [Client-Side Example](#client-side-example). ### Step 4: Success (Receives Data + Receipt) Otto AI verifies the payment via the CDP Facilitator, settles on-chain, and returns **200 OK** with the data. On an EVM settlement the `PAYMENT-RESPONSE` header also carries the signed `otto-content-receipt` described in [After You Pay](#after-you-pay-receipts-and-refunds). ``` HTTP/2 200 payment-response: eyJ... ← settlement envelope; carries the otto-content-receipt on EVM settlements content-type: application/json; charset=utf-8 ``` Each endpoint publishes its own output shape inside the `bazaar` extension of its 402 challenge. For `/crypto-news` that declared shape is: ```json theme={null} { "status": "success", "data": { "report": "Latest crypto news..." } } ``` Read any endpoint's declared shape straight from its live challenge rather than trusting a sample: ```bash theme={null} curl -sD - -o /dev/null "https://x402.ottoai.services/crypto-news" \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '.extensions.bazaar.info.output.example' ``` ### Step 5 (Optional): Sign-in-with-X for Repeat Access On the routes that support it, paying once buys a re-access window — sign the SIWX challenge with the same wallet instead of paying again. Cached data endpoints do **not** support this and are pay-per-call only. Rather than trusting a list that drifts, **ask the endpoint**. A route supports SIWX if and only if its live challenge carries a `sign-in-with-x` extension: ```bash theme={null} curl -sD - -o /dev/null "https://x402.ottoai.services/crypto-news" \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '.extensions | has("sign-in-with-x")' ``` Swap in any route to check it. Where the extension is present, its `info` block carries the exact challenge to sign — `domain`, `uri`, `nonce`, `issuedAt`, `resources`, `statement`. Alongside `info`, `supportedChains` names the signature type per chain (EIP-191 on Base and Polygon, ed25519 on Solana), and `schema` gives the JSON Schema for the signed object: ```bash theme={null} curl -sD - -o /dev/null "https://x402.ottoai.services/crypto-news" \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '.extensions."sign-in-with-x" | {info, supportedChains}' ``` ## Understanding the Facilitator The **CDP Facilitator** (Coinbase Developer Platform) is the payment verification and settlement service: 1. **Validates Payment Signatures**: Verifies the `PAYMENT-SIGNATURE` header is cryptographically valid. 2. **Prevents Replay Attacks**: Tracks nonces and timestamps to prevent signature reuse. 3. **Executes On-Chain Settlement**: Submits transactions to Base, Polygon, or Solana to transfer the asset named in the challenge. **What the live challenge tells you:** * **A route's `accepts` array is the definitive list of networks that route takes.** Networks in play across the storefront are Base (`eip155:8453`), Polygon (`eip155:137`) and Solana mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`), but **not every route offers all three** — some execution routes are EVM-only. Read the array; do not assume Solana is on the menu. * Each EVM network appears twice — once for EIP-3009 (zero-approval) and once with `"assetTransferMethod": "permit2"`. * Each `accepts` entry carries `maxTimeoutSeconds`, and the matching signed offer carries a `validUntil` timestamp. **Treat those two as the authority on how long you have to settle** — decode them from the challenge you were served rather than assuming a fixed window. ```bash theme={null} curl -sD - -o /dev/null "https://x402.ottoai.services/crypto-news" \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '{timeout: .accepts[0].maxTimeoutSeconds, validUntil: .extensions."offer-receipt".info.offers[0].payload.validUntil}' ``` ## Client-Side Example This is the working path. `@x402/axios` wraps an axios instance and handles the whole 402 → sign → retry loop for you. ```bash theme={null} npm install @x402/axios @x402/evm axios viem ``` ```typescript theme={null} import { wrapAxiosWithPayment, x402Client } from '@x402/axios'; import { ExactEvmScheme } from '@x402/evm/exact/client'; import { toClientEvmSigner } from '@x402/evm'; import axios from 'axios'; import { createPublicClient, http } from 'viem'; import { base } from 'viem/chains'; import { privateKeyToAccount } from 'viem/accounts'; // SECURITY WARNING: Never hardcode private keys in your source code! const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); const publicClient = createPublicClient({ chain: base, transport: http() }); const signer = toClientEvmSigner(account, publicClient); // Create x402 V2 client const client = new x402Client(); client.register('eip155:*', new ExactEvmScheme(signer)); const api = wrapAxiosWithPayment( axios.create({ baseURL: 'https://x402.ottoai.services' }), client ); // Automatic payment — the SDK handles 402 → sign → retry const response = await api.get('/crypto-news'); console.log(response.data); ``` The wrapper works by intercepting the rejected `402`, so leave axios's default `validateStatus` alone. If you override it to accept every status code, the `402` never surfaces as an error, the interceptor never fires, and you get the challenge back instead of your data. If the wallet behind `PRIVATE_KEY` holds no USDC on the chosen network, the retry is still sent and signed correctly — the endpoint simply answers `402` again instead of `200`. Fund the wallet on Base, Polygon or Solana with the asset named in the challenge. ## API Endpoint Reference Per-endpoint response samples live on a dedicated reference page — see **[x402 Endpoint Examples](/acp-swarm/x402-examples)**. This page keeps the request flow and the protocol reference. Those samples are **illustrative — not live data**. They show the response shape with a representative payload; prices, scores and timestamps in them may be stale. The live `402` challenge is always the source of truth for price, each endpoint's own `bazaar` extension is the source of truth for its output shape, and a real call returns fresh data. ## Deprecated Endpoints The following endpoints have been removed and are no longer available: | Endpoint | Reason | Alternative | | ----------------------- | -------------------------------- | ----------------------------------------------- | | `/top-ten` | Absorbed into `/crypto-news` | Use `/crypto-news` (now includes top headlines) | | `/historical-summaries` | Low demand, service discontinued | N/A | ## Troubleshooting - Common Issues and Solutions #### Issue: I opened the URL in my browser and got a JSON error, not data That is not an error. Every priced route answers an unpaid request with the `402` challenge, and its body carries a `hint`, the `price`, and contact details. A browser tab cannot pay — see [Which client can actually pay](#which-client-can-actually-pay). #### Issue: I passed a parameter and still got a 402 The paywall is evaluated **before** parameter validation, so a call with a missing or malformed parameter still answers `402` rather than `400`. Getting a `402` therefore tells you nothing about whether your parameters are right. Check the route's required parameter in `/llm.txt` before assuming the endpoint is broken. #### Issue: "Payment verification failed" **Possible Causes:** * Insufficient balance of the asset named in the challenge, on the network you chose * The signed offer you paid against has passed its `validUntil` * Invalid or corrupted payment signature * Payment already used (replay protection) **Solutions:** * Check your balance of the exact `asset` from the challenge on the exact `network` you selected — the challenge names both * Ensure your system clock is synchronized (NTP) * Re-fetch the challenge, regenerate the payment signature against the fresh offer, and retry * Do not reuse an old payment signature #### Issue: "Invalid symbol parameter" **Possible Causes:** * Token symbol doesn't exist or is misspelled * Using the full token name instead of the symbol (e.g. "Bitcoin" instead of "BTC") **Solutions:** * Use standard uppercase symbols: BTC, ETH, SOL * Symbol-based routes resolve a ticker to the top-market-cap asset matching it, so a ticker shared by several tokens resolves to the largest one. Pass a `chain:contract` address instead where the route accepts one * The per-route parameter and its accepted form are documented in [`/llm.txt`](https://x402.ottoai.services/llm.txt) ### Still Having Issues? 1. **Read the error body.** Unpaid `402` responses and error responses carry a `hint` field explaining what the endpoint wants. 2. **Re-read the route in [`/llm.txt`](https://x402.ottoai.services/llm.txt).** It is regenerated from the running service, so it is ahead of any hand-written page. 3. **Contact us** — `admin@useotto.xyz`, or [@useOttoAI](https://twitter.com/useOttoAI). Email and social are free; feature requests welcome. ## On-Chain Standards ### ERC-8004: Agent Identity on Ethereum Mainnet Each Otto AI agent holds an ERC-8004 identity NFT on **Ethereum Mainnet**, under the [ERC-8004 standard](https://eips.ethereum.org/EIPS/eip-8004). This is the swarm's identity layer: a stable, on-chain identifier per agent that is the same identifier wherever the agent trades — ACP, x402, or any other surface. **Registry contract:** [`0x8004A169FB4a3325136EB29fA0ceB6D2e539a432`](https://etherscan.io/address/0x8004A169FB4a3325136EB29fA0ceB6D2e539a432) (Ethereum Mainnet) | Agent | ERC-8004 agent ID | | ------------------------ | ----------------- | | Market Alpha Agent | `6817` | | Trading Agent | `6940` | | Tools Agent | `6996` | | Prediction Markets Agent | `36515` | You do not have to take our word for it. `ownerOf` on the registry is a plain `eth_call` against any Ethereum RPC — a non-zero owner means the identity exists: ```bash theme={null} # ownerOf(6817) — selector 0x6352211e, agent ID left-padded to 32 bytes curl -s -X POST https://ethereum-rpc.publicnode.com \ -H 'Content-Type: application/json' \ -d '{"jsonrpc":"2.0","id":1,"method":"eth_call","params":[{ "to":"0x8004A169FB4a3325136EB29fA0ceB6D2e539a432", "data":"0x6352211e0000000000000000000000000000000000000000000000000000000000001aa1" },"latest"]}' ``` The machine-readable index of all four registrations, with their registration files, is published at [`useotto.xyz/.well-known/erc8004/index.json`](https://useotto.xyz/.well-known/erc8004/index.json). ERC-8004 here is **identity**, and identity is what is on-chain today. This page does not claim a live buyer-facing on-chain rating surface, because there is not one. What you get after paying is described below. ### After You Pay: Receipts and Refunds Two things exist after a paid call, and both are reachable over plain HTTP. **1. Your receipt arrives in-band.** Where a call settles on an EVM network, the paid response carries a signed EIP-712 `otto-content-receipt` in its `PAYMENT-RESPONSE` header, binding the response content to that payment and request. It is handed to you in the same response as the data — there is no lookup step, no IPFS fetch, and no second transaction. Keep the header if you want the proof. Two bounds worth knowing before you build on it: * **It is EVM-only.** The v1 receipt is an EIP-712 object and needs an `eip155` chain, so a call settled on Solana returns no content receipt. Pay on Base or Polygon if you need one. * **It is best-effort, and deliberately so.** Receipt generation never blocks your paid response: if signing cannot complete, you still get the data you paid for, without the header. Treat the receipt as present-when-it-can-be, not as a guarantee on every 200. You can confirm a route advertises the extension before paying: ```bash theme={null} curl -sD - -o /dev/null "https://x402.ottoai.services/crypto-news" \ | grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' \ | base64 -d | jq '.extensions | has("otto-content-receipt")' ``` **2. Refunds run through a paid endpoint, not a web form.** `POST /feedback` is a live x402 route, priced like any other: ```bash theme={null} curl -i -X POST "https://x402.ottoai.services/feedback" # → HTTP/2 402, with the price and payment options in the PAYMENT-REQUIRED header ``` It is a bounded money-back guarantee, and the bounds are the point: * It covers Otto's own recommended services and Full Auto (see [Otto X402 Router](/acp-swarm/open-router)). It does **not** cover third-party CDP Bazaar picks — there is no Otto receipt to verify against those. * A refund claim needs a reason of at least 50 words. * Refunds pay only to the original payer, and never more than that payer actually paid Otto. * They are capped at \$0.01 per transaction and 10 claims per wallet per day. * Otto grades these claims itself. It is a service-quality guarantee from a counterparty, not an independent verdict, and an approved claim is reserved rather than paid out automatically. ### ERC-8183: Agentic Commerce [ERC-8183](https://eips.ethereum.org/EIPS/eip-8183) proposes an on-chain job primitive for AI agent commerce — escrowed ERC-20 payments, a job lifecycle, evaluator-based completion, and composable hooks. It is co-authored by members of the Virtuals Protocol team and designed to compose with ERC-8004. It carries **Draft** status on eips.ethereum.org, which the EIP site itself flags as not recommended for general use or implementation because it is subject to breaking changes. Nothing on this storefront depends on it: the x402 flow described above uses none of it, and no claim on this page rests on it. It is mentioned because ACP's escrowed job lifecycle covers similar ground, and the two are easy to confuse. ## Additional Resources **Live, and always ahead of this page:** * **Machine-readable catalog**: [https://x402.ottoai.services/llm.txt](https://x402.ottoai.services/llm.txt) * **OpenAPI document**: [https://x402.ottoai.services/openapi.json](https://x402.ottoai.services/openapi.json) * **x402 discovery document**: [https://x402.ottoai.services/.well-known/x402](https://x402.ottoai.services/.well-known/x402) * **ERC-8004 registration index**: [https://useotto.xyz/.well-known/erc8004/index.json](https://useotto.xyz/.well-known/erc8004/index.json) **Specifications:** * **x402 Protocol Specification**: [https://x402.gitbook.io/x402](https://x402.gitbook.io/x402) * **Coinbase x402 Documentation**: [https://docs.cdp.coinbase.com/x402/welcome](https://docs.cdp.coinbase.com/x402/welcome) * **ERC-8004 (Trustless Agents)**: [https://eips.ethereum.org/EIPS/eip-8004](https://eips.ethereum.org/EIPS/eip-8004) * **ERC-8183 (Agentic Commerce, Draft)**: [https://eips.ethereum.org/EIPS/eip-8183](https://eips.ethereum.org/EIPS/eip-8183) Powered by Otto AI. Questions: `admin@useotto.xyz` · [@useOttoAI](https://twitter.com/useOttoAI)