# Otto X — x402 DeFi API on X Layer

> Pay-per-call DeFi API. AI agents pay micro-fees via x402 protocol on X Layer (Chain 196).
> No API keys. No accounts. The on-chain payment IS the authentication.

## Paid Endpoints (x402 paywall)

All paid endpoints return HTTP 402 with payment instructions if no valid payment header is provided.
Payments settle on X Layer mainnet (EIP-155, Chain ID 196) via OKX Facilitator.

- POST /swap ($0.01): Get swap quote + calldata on X Layer via OKX DEX (V1: not broadcast).
- GET /market-alpha ($0.005): X Layer token market intelligence — live pricing for curated tokens.
- GET /price ($0.002): Single token USD price via OKX DEX quote.
- GET /all-tokens ($0.002): Full list of all tokens supported on X Layer DEX.
- GET /approve ($0.005): ERC-20 approval calldata for DEX router (needed before swap).
- GET /crypto-news ($0.001): Importance-ranked crypto headlines with per-article source links and publish times, plus a sentiment-scored market brief. Regenerated hourly; meta carries the snapshot's age and a fresh/stale verdict..
- GET /token-alpha ($0.001): Premium token intelligence — news, Twitter sentiment, futures data.
- GET /kol-sentiment ($0.003): Aggregated sentiment from top 50 crypto KOLs.
- GET /trending-altcoins ($0.001): Top 3 trending altcoins with analysis.
- GET /mega-report ($0.05): Alpha & Intel Report — comprehensive daily market briefing — headlines, sentiment, KOL alpha, trending, yield.
- GET /token-security ($0.001): Token contract security audit — honeypot detection, rug pull risk, tax analysis.
- GET /funding-rates ($0.001): Derivatives dashboard — funding rates, open interest, long/short ratios.
- GET /defi-analytics ($0.001): DeFi protocol analytics — TVL rankings, chain breakdown, gainers/losers.
- GET /filtered-news ($0.001): AI-filtered news by topic (DeFi, NFTs, Layer2, etc.).
- GET /twitter-summary ($0.001): Curated crypto Twitter/X digest from top KOLs.
- GET /token-details ($0.001): Token price, market cap, 24h change.
- GET /yield-alpha ($0.001): Top DeFi yield opportunities across chains.
- GET /tradfi-data ($0.001): TradFi macro intelligence — indices, VIX, DXY, yields, commodities.
- GET /vet-token ($0.01): Token Safety & Tradeability Vetting — one-call X Layer token check: GoPlus contract security (honeypot, tax, mint/ownership flags) + holder concentration + live OKX DEX tradeability & price. Refuses (unpaid) if the security scan is empty..
- GET /token-deep-dive ($0.05): Token Deep-Dive — full-picture briefing for a major token: price & market cap + contract security + derivatives funding/OI + market KOL context + OKX DEX price. Unresolved legs labelled unavailable, never faked. Refuses (unpaid) if core token details are missing..
- GET /rwa-pulse ($0.05): RWA Market Pulse — a pulse on the real-world-asset market: TradFi macro (indices, VIX, DXY, yields, commodities) + live tokenized-RWA perps (equities like AAPL/TSLA/NVDA, commodities, FX) from Hyperliquid + crypto market news. Live legs only; any reading that would fabricate is omitted and named. Refuses (unpaid) if the macro core is empty..
- GET /generate-meme ($0.15): AI image generation via fal.ai (gpt-image-2 default, nano-banana-pro alt).
- GET /llm-research ($0.10): AI research assistant with web search via Gemini 3.1 Flash-Lite.
- GET /tx-explainer ($0.01): Decode & explain EVM transactions across 11 chains.
- GET /portfolio ($0.001): Multi-chain token balances for your Otto X sub-wallet (or ?address=0x...).
- GET /supported-tokens ($0.001): Search tokens by symbol on chain.
- GET /hyperliquid-account ($0.001): Hyperliquid perpetual futures account info — defaults to your Otto X sub-wallet.
- GET /hyperliquid-market ($0.001): Perpetual market data & funding rates.
- GET /hl-transaction-history ($0.001): Hyperliquid trade history — defaults to your Otto X sub-wallet.
- GET /yield-markets ($0.001): Blue-chip supply APYs from each protocol's authoritative source — Aave V3 + Compound V3 (on-chain), Morpho (official GraphQL), Syrup (ERC-4626 trailing).
- GET /yield-farming-active ($0.001): Active yield positions for a wallet — Otto-allowlisted lending positions also get a rebalance recommendation (current APY vs. the highest-rated allowlisted protocol alternative + the action calls to switch) and a portfolio yield summary.
- GET /yield-farming-historical ($0.001): Yield op history for a wallet — deposit/redeem timeline with exact Otto fees and a totals summary.
- GET /idle-capital ($0.001): Detect undeployed tokens that could earn yield.
- GET /yield-recommendations ($0.001): Personalized yield vault recommendations.
- POST /auto-swap ($0.05): Execute an in-chain swap on your Otto X sub-wallet via OKX DEX aggregator.
- POST /auto-bridge ($0.05): Execute a cross-chain bridge from your Otto X sub-wallet (17 chains supported).
- POST /auto-defi-invest ($0.05): Deposit into a whitelisted DeFi protocol (Aave V3, Lido, Compound V3, Morpho) from your Otto X sub-wallet.
- POST /auto-defi-withdraw ($0.05): Redeem an active DeFi position from your Otto X sub-wallet.
- POST /yield-copilot ($0.05): One-call yield: deploy your idle stablecoins into the highest-APY Otto-allowlisted lending venue (Aave V3 / Compound V3 / Morpho) on Base, Arbitrum, Optimism, Ethereum, or X Layer — accepts principalAuth; returns a before/after APY + projected yield artifact.
- POST /auto-withdraw ($0.05): Escape hatch — sweep funds from your Otto X sub-wallet to any external address.
- GET /sub-wallet ($0.01): Resolve (or auto-provision) your Otto X sub-wallet — bound to the verified x402 payer.
- POST /yield-watch ($0.001): Register or update a yield-watch subscription. mode=auto: signed EIP-712 30-day delegation authorizing Otto to auto-rebalance between Aave V3 and Compound V3 (Morpho ships v1.1). mode=notify: free observation alerts only..
- DELETE /yield-watch ($0.001): Revoke an active yield-watch subscription — requires a signed YieldWatchRevocation typed-data note (different primaryType from the registration delegation).
- GET /yield-watch ($0.001): Read the caller's current yield-watch subscription state (mode, scope, policy knobs, move counter, next nonce).
- GET /yield-watch/audit ($0.001): Read the caller's yield-watch audit trail — registrations, revocations, observation starts/resets, auto-move attempts/results.
- GET /stablecoin-watch ($0.001): Is USDC/USDT/DAI holding its $1 peg, and is stablecoin supply growing or shrinking (risk-on vs risk-off)? Live peg deviation (bps), circulating supply + 1d/7d/30d flow, market dominance and chain spread for the top 30 USD stablecoins, plus downside depeg alerts for any coin trading >0.5% below peg. Sourced from DefiLlama (public). Served from a cached snapshot while fresh (≤1h) and regenerated on demand when a read finds it stale..
- GET /protocol-revenue-leaders ($0.001): Which protocols earn the most — and who is accelerating? Top 30 DeFi protocols by 24h fees, each with revenue, take-rate (the cut the protocol keeps vs fees users pay), 7d/30d trend and category, plus total DeFi fees & revenue. A fundamentals screen (fee/revenue economics), distinct from TVL. Sourced from DefiLlama (public). Served from a cached snapshot while fresh (DefiLlama fees are daily aggregates) and regenerated on demand when a read find….
- GET /market-risk ($0.002): Composite crypto market-stress digest: a 0-100 score (low/moderate/elevated/high) blended from global USD-stablecoin depeg health (DefiLlama) and Base on-chain DEX exit-liquidity, with a per-leg breakdown and an AI risk line. Both legs required for a score. Every read older than an hour regenerates the score inline. Fresh-or-refuse: if a current score can't be computed, the call refuses (uncharged) rather than return an older reading..
- GET /news-recaps ($0.003): A tight 4-6 sentence crypto market recap an agent can ingest whole: overall direction and why, the 2-3 developments that matter, and anything notable on the top-10 board — distilled hourly from the same live news engine behind Otto's top-ranked /crypto-news feed. The one-paragraph state-of-market; buy /crypto-news when you want the full report..
- GET /fx-rates ($0.001): Live + reference foreign-exchange (forex) rates, base USD. LIVE near-real-time mid quotes for the 12 most-traded currencies (EUR, GBP, JPY, CHF, CAD, AUD, NZD, CNY, HKD, SGD, SEK, KRW), refreshed every minute with an honest market-open/stale flag, PLUS the official ECB daily reference table for ~30 currencies. Derive any cross-rate or pair. Keyless, pay-per-call..
- GET /pm-markets ($0.001): Top Polymarket prediction markets right now: the 25 highest-volume open markets with live odds (outcome probabilities), best bid/ask, spread, last trade, 24h + total volume, liquidity, 1d/7d price change, end date and event link. Flat JSON, refreshed every 5 minutes..
- GET /pm-crypto ($0.001): Crypto prediction markets on Polymarket: the highest-volume open BTC, ETH and crypto markets with live odds (outcome probabilities), best bid/ask, spread, 24h + total volume, liquidity, price change and end date. 'Bitcoin above X', price targets, ETF and protocol events — what the market actually prices in, as flat JSON refreshed every 5 minutes..
- GET /rh-season ($0.001): Robinhood Chain memecoin intelligence: the rug-screened RH Chain (chainId 4663) movers. Hard liquidity + wash-volume gates filter $0-liquidity honeypots faking $1M volumes; every survivor carries rug-risk flags (thin liquidity, vol/liquidity anomaly, pool age, CoinGecko listing) plus trusted-KOL mentions with verbatim quotes and a synthesized RH sentiment read. What is pumping AND whether it is real. Served from a cached snapshot while fresh (≤1….
- GET /tokenized-equities ($0.001): The live registry of tokenized US equities & ETFs on Robinhood Chain (chainId 4663): symbol, canonical token address, decimals, listed-on-rail routability, and the EXECUTABLE buy price — what a $100 buy pays per token at the route's minimum output — published next to the catalog reference price and the deviation between them. Every served address is bound to a hand-verified identity pin. The on-chain settlement layer for tokenized-equity exposur….
- GET /earnings-calendar ($0.003): Earnings calendar + surprise history for a vendor-resolved equity or ETF: next report date and session (before-open / after-close) with EPS & revenue estimates, latest reported EPS versus estimate with surprise %, and a four-quarter history. Licensed Finnhub feed; monetary values keep vendor payload units. Event-window price drift is marked unavailable, never inferred. Pass ?ticker= (e.g. AAPL). Refreshed daily..
- GET /analyst-ratings ($0.003): Analyst consensus for a vendor-resolved equity: the latest buy/hold/sell distribution (strong buy · buy · hold · sell · strong sell counts, total, and a deterministic consensus label) plus up to six months of the same distribution so an agent can read the drift — is the street moving toward or away from the name. Vendor counts (Finnhub), label rule stated in the payload. No price targets and no per-analyst grade actions are served..
- GET /equity-news ($0.003): Company news for a vendor-resolved equity: licensed Finnhub headlines from the trailing 7 days with publish time, source and summary. Only articles that name the company are served — labelled primary (headline names it) or mentioned (only the summary does) — so a symbol-tagged story about another company never fills the list. No sentiment is fabricated. Pass ?ticker= (e.g. TSLA). Refreshed hourly..
- GET /dividend-intel ($0.003): Cash-dividend intelligence for a vendor-resolved equity from the licensed Tiingo end-of-day feed: TTM dividend/share and yield against the latest close, latest dividend, split-adjusted complete-year growth, the last eight payments, split events, and a cut-detection checklist with explicit coverage. Payout ratio, forward ex-dates and declaration/record/payment dates are not served (not in the Tiingo feed); non-payers return status no-cash-dividen….
- GET /macro-regime ($0.003): Daily US macro-regime snapshot from licensed Alpha Vantage series: 10-year Treasury yield, effective federal funds rate, 3-month rate changes, CPI index and YoY inflation, plus a mechanical rate-direction / inflation-direction label with disclosed thresholds. Scanner context, no query param. Refreshed daily..
- GET /technical-signals ($0.003): Daily technical snapshot for a vendor-resolved equity from licensed Tiingo adjusted closes: Wilder RSI-14 with state, 20-session momentum, SMA-20 / SMA-50, price distance from each average, above / below / mixed trend state, and the latest observed golden / death cross. Price and averages keep vendor payload units. Pass ?ticker= (e.g. MSFT). Refreshed daily..
- GET /insider-trades ($0.003): SEC Form 4 insider trades for any US-listed company: who bought and sold (officer / director / 10% owner), purchase vs sale counts and dollar values (SEC codes P/S), net purchase-sale balance, shares held after each transaction, and filing links. An hourly snapshot straight from the primary source — public-domain SEC EDGAR. Pass ?ticker= (e.g. AAPL). Refreshed hourly..
- GET /institutional-holdings ($0.003): Latest 13F-HR holdings for any SEC-filing manager (hedge funds, asset managers): top 20 positions by value with issuer, CUSIP, value in whole USD, share / principal amount (SH/PRN), put/call flag and position count, amendments applied. Whale-tracking straight from the primary source — public-domain SEC EDGAR. Pass ?manager= a CIK or manager ticker (e.g. 1067983 for Berkshire, or BLK). Refreshed hourly..
- GET /pm-search ($0.001): Search Polymarket prediction markets by free text — elections, Fed rates, crypto prices, sports, geopolitics, AI. Returns the top matching open markets with live odds (outcome probabilities), best bid/ask, spread, volume, liquidity, end date and event link as flat JSON. Pass ?query= (e.g. "fed rate cut"). Live odds on a ~10-minute cadence..
- GET /equity-smart-money ($0.006): Smart-money bundle for any US-listed company in ONE call: SEC Form 4 insider activity (purchases vs sales, SEC codes P/S, net purchase-sale balance, who filed and their roles) PLUS trailing-twelve-month fundamentals — revenue + YoY, net income + YoY, diluted EPS — from XBRL filings. Insider conviction and the financials behind it, together. Public-domain SEC EDGAR. Pass ?ticker= (e.g. NVDA). Refreshed hourly..
- GET /tweet-search ($0.005): Search X / Twitter for any query and get the actual matching tweets — keyword, $CASHTAG, from:handle, @handle mentions, or boolean OR. Each tweet returns author, full text (long-form notes included), timestamp, likes and retweets. Most-recent-first for real-time monitoring. Structured JSON, pay-per-call. Pass ?query= (e.g. $BTC). Live X search, ~5-minute recency..

## Free Endpoints

- GET / : Interactive landing page (HTML) or JSON service discovery (Accept: application/json).
- GET /health : Service health check.
- GET /tokens : Curated X Layer token registry (USDT, USDG, OKB, WETH).
- GET /sub-wallet/preview?address=0x... : Read-only existence check for an Otto X sub-wallet (never provisions).
- GET /defi-positions?address=0x... : Active DeFi positions for an Otto X sub-wallet.
- GET /supported-protocols : DeFi protocols on the Otto X allowlist (filtered to executable chains).
- GET /llm.txt : This file — AI-readable service catalog.
- GET /.well-known/x402 : x402 discovery document (JSON).
- GET /recipes : Recipes catalog — composed multi-endpoint workflows, one payment each (HTML).
- GET /api/recipes : Recipes index (JSON) — id, question, route, price, steps, params.

## Agentic Wallet notes

Authenticated by your x402 payment. Funds custodied in a TEE-backed sub-wallet auto-provisioned on first
paid call. POST /auto-* endpoints accept an optional EIP-3009 `principalAuth` that pulls your USDC into
the sub-wallet in the same call (no separate top-up). Without it, an insufficient-balance call returns
HTTP 409 with deposit instructions — your x402 fee is NOT charged on 409.

## Yield Copilot

POST /yield-copilot is one-call yield: pass {chain, token} (and optional amount + principalAuth) and Otto
deploys your idle stablecoin into the highest-APY Otto-allowlisted lending venue (Aave V3 / Compound V3 /
Morpho) on that chain — Base, Arbitrum, Optimism, Ethereum, or X Layer — and returns a before/after artifact
(idle 0% APY → venue APY, illustrative annualized yield, $0.05 fee, withdraw endpoints, provenance). Omit
`amount` to deploy the full idle balance of that token. On Ethereum, ops are declined during a base-fee
spike (>~25 gwei) rather than subsidizing it. Otto never pools user funds; withdraw the position anytime via
POST /auto-defi-withdraw, or sweep the sub-wallet via POST /auto-withdraw. Informational only — not
investment advice; APYs float and are not guaranteed.

GET /yield-farming-active enriches each Otto-allowlisted lending position with a rebalance recommendation:
current APY vs. the highest-rated allowlisted *protocol* alternative for that stable on that chain (the APY
is a protocol-level figure — OKX picks the deposit market — never "the best vault is X"), the projected $/yr
uplift, and — when you read your own sub-wallet — the 2-call switch (POST /auto-defi-withdraw then
POST /yield-copilot). It only suggests a switch when the gap clears a delta + $/yr bar and the position has
been held past a cooldown. GET /yield-farming-historical is the receipt: your deposit/redeem timeline with
exact $0.05-per-op Otto fees, plus an exact realized yield/APY per closed round-trip (the on-chain amount
that actually came back minus what you deposited, annualized over the hold) — or a reason when it can't be
attributed cleanly. The summary carries lifetime realized $ + total Otto fees.

## Quick Start (for agents)

1. GET any paid endpoint without payment → receive 402 + payment details.
2. Construct on-chain payment on X Layer for the specified amount.
3. Retry request with payment proof in header.
4. Receive DeFi data.

## Links

- GitHub: https://github.com/useOttoAI/otto-x
- Docs: https://docs.useotto.xyz
- OKX Onchain OS: https://web3.okx.com/onchainos