Otto X Storefront

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.

• Landing Page — interactive endpoint explorer
• LLM Docs — machine-readable for AI agents
• Discovery Doc — x402 discovery document
• GitHub — open source

​

How It Differs from x402.ottoai.services

​

OKX Onchain OS Usage

​

Pricing Overview

​

X Layer DEX Endpoints

​

Market Intelligence

​

AI Tools

​

Trading Resources

​

Agentic Wallet V2 — Autonomous DeFi Execution

​

Yield Watch

​

Yield Copilot — POST /yield-copilot

POST /yield-copilot
{ "chain": "base", "token": "USDC" }          # deploys your full idle USDC balance
# or
{ "chain": "optimism", "token": "USDC", "amount": "500", "principalAuth": { ... } }

• What it does: reads your Otto X sub-wallet’s idle balance of the requested stablecoin, picks the lending venue — the highest current APY among the Otto-allowlisted lending protocols (Aave V3, Compound V3, Morpho) for that stablecoin on that chain, sourced from vaults.fyi (Base / Arbitrum / Optimism / Ethereum) with the DeFi Llama yields API as fallback (the apy_source field in the response says which was used) — and supplies it via the same path /auto-defi-invest uses. Accepted stablecoins are those in the allowlist for that chain (USDC, USDT, USDT0, USDG, USDC.e, DAI as applicable). Omit amount to deploy the entire idle balance; supply principalAuth to fund the sub-wallet in the same call — principalAuth funding currently supports USDC on Base/Arbitrum/Optimism/Ethereum/Polygon and USDT0 on X Layer, and its value must equal the deposit amount exactly.
• Scope: Base, Arbitrum, Optimism, Ethereum, X Layer. (X Layer has no public APY feed yet, so on X Layer the response reports the venue with apy: null and points you to GET /yield-farming-active for the live rate. On Ethereum, the call is declined during a base-fee spike — above ~25 gwei — rather than subsidizing it.) If a stablecoin has several allowlisted venues on a chain and the APY feed is unavailable, Otto returns 503 APY_DATA_UNAVAILABLE rather than guessing — pick the venue yourself via /auto-defi-invest.
• The response is the artifact: before (idle amount, 0% APY) → after (venue, APY, illustrative annualized + monthly yield at the current rate) → economics ($0.05 Otto fee, APY delta) → custody (your payer-bound sub-wallet, withdraw endpoints) → selection (why this venue, APY source, TVL, pool id) → tx_hashes → a not_investment_advice disclaimer.
• What Otto provides: automation + transparency + non-custody + a $0.05 fee — not “earning power” or guaranteed returns. APYs float; deployed capital carries smart-contract, liquidity, and market risk. Otto never pools or rehypothecates user funds; withdraw the position anytime via POST /auto-defi-withdraw, or sweep the whole sub-wallet via POST /auto-withdraw.

​

Yield Watch — POST /yield-watch (notify) / POST /yield-watch (auto) / DELETE /yield-watch / GET /yield-watch / GET /yield-watch/audit

POST /yield-watch
{
  "mode": "notify",
  "telegramChatId": "1234567890",
  "chainIds": [8453, 42161],
  "tokens": ["USDC"],
  "protocols": ["aave_v3", "compound_v3", "morpho"],
  "hysteresisPctBps": 50,    # require ≥0.50pp APY gap before alerting
  "hysteresisHours": 6,       # for ≥6 sustained hours
  "throttleHours": 72,        # at most one alert per position per 72h
  "minHoldDays": 7            # don't alert on positions <7 days old
}

POST /yield-watch
{
  "mode": "auto",
  "telegramChatId": "1234567890",
  "delegationSig": "0x...",
  "delegationMsg": {
    "wallet":            "0xYOUR_WALLET",
    "subWallet":         "0xYOUR_SUB_WALLET",
    "mode":              "auto",
    "chainIds":          [8453],
    "tokens":            ["USDC"],
    "protocols":         ["aave_v3", "compound_v3"],
    "hysteresisPctBps":  50,
    "hysteresisHours":   6,
    "throttleHours":     72,
    "minHoldDays":       7,
    "maxMoves":          10,
    "maxPrincipalRaw":   "0",          # 0 = no per-move cap; positive = raw token units
    "nonce":             0,
    "issuedAt":          1716158400,
    "expiry":            1716763200
  }
}

import { signTypedData } from 'viem/actions';

const domain = {
  name: 'OttoXYieldWatch',
  version: '1',
  // No chainId / verifyingContract — this is a pure off-chain authority
  // bound to the wallet, sub-wallet, and nonce.
};

const types = {
  YieldDelegation: [
    { name: 'wallet',           type: 'address' },
    { name: 'subWallet',        type: 'address' },
    { name: 'mode',             type: 'string'  },
    { name: 'chainIds',         type: 'uint256[]' },
    { name: 'tokens',           type: 'string[]'  },
    { name: 'protocols',        type: 'string[]'  },
    { name: 'hysteresisPctBps', type: 'uint256' },
    { name: 'hysteresisHours',  type: 'uint256' },
    { name: 'throttleHours',    type: 'uint256' },
    { name: 'minHoldDays',      type: 'uint256' },
    { name: 'maxMoves',         type: 'uint256' },
    { name: 'maxPrincipalRaw',  type: 'uint256' },
    { name: 'nonce',            type: 'uint256' },
    { name: 'issuedAt',         type: 'uint256' },
    { name: 'expiry',           type: 'uint256' },
  ],
};

const signature = await walletClient.signTypedData({
  account,
  domain,
  types,
  primaryType: 'YieldDelegation',
  message: delegationMsg,
});

const REVOKE_TYPES = {
  RevokeYieldDelegation: [
    { name: 'wallet', type: 'address' },
    { name: 'nonce',  type: 'uint256' },
  ],
};
const revokeSignature = await walletClient.signTypedData({
  account, domain, types: REVOKE_TYPES, primaryType: 'RevokeYieldDelegation',
  message: { wallet, nonce: subscription.nextNonce },
});

DELETE /yield-watch
{ "wallet": "0xYOUR_WALLET", "signature": "0x...", "nonce": <current_next_nonce> }

• Allowlist: Aave V3 and Compound V3 only for v1. Morpho is rejected at registration (vault-address coupling lands in v1.1).
• TVL floor + APY staleness: an alt protocol must have ≥ $10M TVL and an APY data point ≤ 2h old before it can win a move.
• Hysteresis state machine: the alt must beat the current venue by hysteresisPctBps sustained for hysteresisHours straight (the worker tracks per-position observations; a regression resets the window).
• Throttle: at most one move per position per throttleHours window (default 72h) — bounds gas + Otto-fee spend.
• maxMoves: a hard cap over the 30-day delegation window. After the cap, the worker refuses further moves on that wallet.
• maxPrincipalRaw: a per-move notional cap in raw token units (e.g. "5000000" = $5 USDC at 6 decimals). "0" = no cap. Cap is bound to the LIVE position size at lock time, so a mid-window top-up over the cap is refused.
• Pre-broadcast resolver guards: both the current and the best-alt market must resolve cleanly via OKX, and must point at the SAME canonical token address (no USDC → USDC.e routing, no surprise asset substitution). Refusals at this stage never pay the audit cost.
• Post-broadcast verification: every leg (withdraw + invest) is followed by assertReceiptsConfirmed — a hard check that the broadcast tx hash actually landed on-chain. Defends against the OKX silent-drop bug pattern ({ok:true, txHash} returned but the relayer’s simulate reverted and dropped the broadcast).
• Per-phase failure receipts: if any leg fails, the Telegram receipt names the specific phase (withdraw / verification_withdraw / invest / verification_invest) and a recovery CLI tailored to where the funds are (still in the old protocol vs idle in your sub-wallet).
• Synthetic ledger close-out: a successful auto-move writes (auto_defi_withdraw, yield_copilot) rows to your otto_x_ops ledger so the next tick sees the OLD protocol closed + NEW open, and /yield-farming-historical treats the move as a realized round-trip for the closed deposit.

GET  /yield-watch                 # current subscription, paused flag, nextNonce, moveCount, signed scope
GET  /yield-watch/audit?limit=50  # full event trail: registered/revoked/observation_started/notify_alert/auto_move_started/auto_move_succeeded/auto_move_failed

​

Yield status & receipts — GET /yield-farming-active, GET /yield-farming-historical

• GET /yield-farming-active lists your active yield positions and, for each Otto-allowlisted lending position (Aave V3 / Compound V3 / Morpho stablecoin lending on Base / Arbitrum / Optimism / Ethereum / X Layer), adds a rebalance picture: current_apy_pct vs. best_alternative (the highest-rated allowlisted protocol for that stable on that chain — the APY is a protocol-level figure, since OKX picks the actual deposit market; it is never “the best vault is X”), apy_delta_pts, projected_annual_uplift_usd, and a recommendation of rebalance or hold with a plain-English why. A rebalance is suggested only when the gap clears both a minimum APY-delta and a minimum projected $/yr bar and you’ve held the position past a cooldown — it won’t nag you to chase rate noise. When you read your own sub-wallet, a rebalance recommendation includes the two-call switch: POST /auto-defi-withdraw {protocol, chain, token, ratio:"1"} then POST /yield-copilot {chain, token} (Otto re-picks the best venue at execution time, and the redeemed funds redeploy in full). The response also carries a yield_summary (total deployed, weighted-avg APY, projected annual yield, rebalances recommended).
• A rebalance is informational — the new rate is not locked, switching protocols carries smart-contract/migration risk, you pay 2 × $0.05 in Otto fees (Otto absorbs the on-chain gas), and if the redeploy leg fails your funds simply sit idle in your own sub-wallet (re-call POST /yield-copilot). Not investment advice.
• GET /yield-farming-historical is the receipt: your full yield-op timeline (deposits via /auto-defi-invest & /yield-copilot + redemptions via /auto-defi-withdraw) with the exact $0.05 Otto fee per op and tx hashes. Each full redemption carries a `realized` block — `realized_yield_usd` and `realized_apy_pct` computed **exactly** (the on-chain amount that actually came back to your sub-wallet, minus what you deposited; APY annualized over the holding period) for positions whose deposit(s) Otto recorded; a `null` `realized` with a `reason` means it couldn't be attributed cleanly (e.g. partial withdrawal, position funded externally, or it pre-dates the redeemed-amount instrumentation). The `summary` adds `realized_yield` (lifetime realized$, # closed round-trips with a realized figure) alongside the exact total Otto fees. For current rates use GET /yield-farming-active.

​

Custody Model (Important)

• Keys are generated and held inside OKX’s Trusted Execution Environment (TEE). Otto AI holds an API credential that authorizes signing; neither Otto nor OKX staff can export the underlying key.
• Users do not control their sub-wallet directly. There is no seed phrase to back up, no MetaMask connection, no co-signer role.
• This trades away the self-custodial property of Otto AI’s Safe-based Trade Execution Agent in exchange for fully autonomous execution (no user signing, no gas management, atomic operations).
• POST /auto-withdraw is the escape hatch: users can sweep any token balance to any external address at any time. No approvals, no holds.
• Otto runs an hourly GC that flags inactive empty sub-wallets to prevent capacity squat.

​

Aligned with Agent Payments Protocol §8.4

​

One-Call Flow via EIP-3009 principalAuth (recommended)

1. One-time preview — GET /sub-wallet?address=0xYOUR_WALLET (free). Cache sub_wallet.evm_address indefinitely; it’s deterministic per payer.
2. Sign two things — your wallet signs:
   • The x402 service fee (standard paywall, $0.25 USDT0 on X Layer → Otto treasury).
   • An EIP-3009 TransferWithAuthorization note authorizing your USDC on the target chain to flow into your sub-wallet. Modern wallets (MetaMask, Coinbase Wallet, Rabby, Phantom) can batch both into one confirmation screen.
3. POST the op — include principalAuth in the body:

{
  "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "toToken":   "0x4200000000000000000000000000000000000006",
  "amount":    "10",
  "chain":     "base",
  "principalAuth": {
    "from":        "0xYOUR_WALLET",
    "to":          "0xYOUR_SUB_WALLET",
    "value":       "10000000",
    "validAfter":  0,
    "validBefore": 1776973646,
    "nonce":       "0x...",
    "signature":   "0x..."
  }
}

• principalAuth.from MUST equal your x402 payer (no impersonation).
• principalAuth.to MUST equal your provisioned sub-wallet (no draining to attacker addresses).
• principalAuth.value MUST be ≥ the op’s required amount.
• validBefore MUST be in the future; nonce MUST be unseen (replay-safe via a per-signer-per-token-per-nonce DB claim + on-chain authorizationState check).

​

Legacy Flow — HTTP 409 funds_required (fallback)

{
  "status": "funds_required",
  "code": "FUNDS_REQUIRED",
  "idempotency_key": "a1b2c3...",
  "retry_after_deposit": true,
  "deposit": {
    "deposit_address": "0xYourSubWallet...",
    "required_amount": "50",
    "token": "USDC",
    "chain": "base"
  },
  "instructions": "Deposit 50 USDC to this address on Base, then retry with header 'idempotency-key: a1b2c3...'. Your x402 payment for this attempt was NOT charged."
}

​

Free Endpoints

​

x402 Payment Flow (OKX)

1. Send request  →  GET /crypto-news
2. Get 402       ←  Payment Required ($0.001, X Layer)
3. Pay on-chain  →  Transfer on X Layer mainnet (chain 196)
4. Retry + proof →  GET /crypto-news + payment header
5. Verified      →  OKX Facilitator confirms payment
6. Get data      ←  News report with sentiment

​

Token Registry

​

Quick Start

# Health check (free)
curl https://xlayer.ottoai.services/health

# Token registry (free)
curl https://xlayer.ottoai.services/tokens

# AI-readable catalog (free)
curl https://xlayer.ottoai.services/llm.txt

# Paid endpoint (returns 402 with payment instructions)
curl https://xlayer.ottoai.services/crypto-news

​

Roadmap

• principalAuth chain expansion: add Ethereum, Optimism, Avalanche, BSC for EIP-3009 one-call flows once on-chain gas economics justify it
• Onchain OS One-Time / Batch Payment for principal on X Layer: reroute the principal leg through the OKX Payment protocol so the user’s principal transfer itself is zero-gas (today only the service fee is); offer aggr_deferred scheme on high-frequency reads so AI-agent hot loops can batch-settle signatures via TEE
• Agentic Wallet allowlist expansion: broaden beyond Aave / Lido / Compound / Morpho once each new protocol clears mainnet validation; add BSC, Avalanche, and Solana DeFi integrations
• Yield ladder: POST /yield-copilot (Tier 1, live) deploys idle stablecoins into the highest-APY allowlisted lending venue in one call. Tier 2 (live, read-side): GET /yield-farming-active rebalance recommendations + the GET /yield-farming-historical op receipt — including exact realized yield/APY per closed round-trip. Tier 3 (live): POST /yield-watch — opt-in notify-only alerts OR a 30-day signed EIP-712 delegation for autonomous Aave↔Compound rebalances, with hard guardrails (TVL floor + APY staleness + hysteresis + minimum-hold + per-position throttle + signed maxMoves/maxPrincipalRaw caps + post-broadcast verification + per-phase failure receipts).
• Earn-pay-earn loops: Agents earn via x402, pay for intelligence via x402, compound returns through Otto X — all on X Layer
• OKX Onchain OS Skills integration: Publishing Otto services as first-class skills so Claude Code / Cursor / Codex CLI users can discover and pay for Otto intelligence natively
• Hyperliquid perps via Agentic Wallet: extend beyond OKX’s DeFi catalog by wiring wallet contract-call against Hyperliquid’s contracts for TP/SL-capable perp execution from the same sub-wallet
• Multi-master sharding: scale beyond 50 sub-wallets per OKX master by sharding across multiple execution masters with deterministic routing