# 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): Real-time crypto news with sentiment analysis.
- GET /token-alpha ($0.001): Premium token intelligence — news, Twitter sentiment, futures data.
- GET /kol-sentiment ($0.001): Aggregated sentiment from top 50 crypto KOLs.
- GET /trending-altcoins ($0.001): Top 3 trending altcoins with analysis.
- GET /mega-report ($0.25): 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 /generate-meme ($0.50): AI image generation via fal.ai (gpt-image-2 default, nano-banana-pro alt).
- GET /llm-research ($0.50): 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.

## 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).

## 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