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 X brings the Otto AI agent swarm to the X Layer ecosystem. Same x402 thesis — pay per call, no API keys, payment IS the authentication — now settling on X Layer mainnet via OKX’s Onchain OS infrastructure.
Base URL: https://xlayer.ottoai.services
Chain: X Layer Mainnet (Chain ID: 196)
Payment: On-chain micro-payments on X Layer via OKX Facilitator
Discovery:
Sister surfaces (overlapping agent catalog, different rails): x402 (USDC on Base/Polygon/Solana) · USDC / Circle Gateway (gasless batched USDC) · MPP (IETF M2M / Stripe). See Access Paths & Coverage for current counts and capability coverage.
How It Differs from x402.ottoai.services
| x402.ottoai.services | xlayer.ottoai.services |
|---|
| Chain | Base, Polygon, Solana | X Layer (196) |
| Facilitator | CDP (Coinbase) | OKX Facilitator |
| Payment Token | USDC | Native X Layer payments |
| SDK | @x402/express (Coinbase) | @okxweb3/x402-express (OKX) |
| Endpoints | 37 | 42 |
| Focus | Full agent swarm | DEX + market intel + AI tools + trading resources |
Both deployments serve the same underlying agent intelligence. Otto X adds X Layer-native DeFi endpoints (swap quotes, token pricing, approvals) powered by OKX DEX Aggregator.
OKX Onchain OS Usage
| Module | How It’s Used |
|---|
x402 SDK (@okxweb3/x402-express, @okxweb3/x402-evm, @okxweb3/x402-core) | Payment middleware gating all 42 paid endpoints via OKXFacilitatorClient on X Layer |
| DEX Aggregator API v6 | HMAC-authenticated calls for swap quotes, token pricing, registry, and ERC-20 approvals on chain 196 |
| Agentic Wallet | Project on-chain identity (0xa3db6825de8222e9f8bac136eeb2f65d49a88fcf) |
| OKX API Auth | HMAC-SHA256 request signing for all DEX interactions |
Pricing Overview
X Layer DEX Endpoints
| Endpoint | Price | Description |
|---|
POST /swap | $0.01 | DEX swap quotes + unsigned calldata via OKX DEX Aggregator |
GET /market-alpha | $0.005 | Live token pricing derived from on-chain DEX quotes |
GET /price?token=0x... | $0.002 | Single token USD price via DEX quote |
GET /all-tokens | $0.002 | All tokens supported on X Layer DEX |
GET /approve?token=0x...&amount=N | $0.005 | ERC-20 approval calldata for DEX router |
Market Intelligence
| Endpoint | Price | Description |
|---|
GET /crypto-news | $0.001 | Real-time crypto news with sentiment analysis |
GET /token-alpha?symbol=BTC | $0.01 | Premium token intelligence — news, sentiment, futures |
GET /kol-sentiment | $0.01 | 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 |
GET /token-security?address=0x... | $0.001 | Token contract security audit |
GET /funding-rates?symbol=BTC | $0.001 | Derivatives funding rates & open interest |
GET /defi-analytics?protocol=aave | $0.001 | DeFi protocol analytics |
GET /filtered-news?topic=DeFi | $0.01 | 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?symbol=BTC | $0.001 | Token price, market cap, 24h change |
GET /yield-alpha | $0.01 | Top DeFi yield opportunities across chains |
GET /tradfi-data?symbol=SPY | $0.001 | TradFi macro intelligence — indices, VIX, DXY, yields (omit symbol for macro dashboard) |
| Endpoint | Price | Description |
|---|
GET /generate-meme?prompt=... | $0.50 | Multi-model image gen via fal.ai (GPT Image 2, Nano Banana Pro) |
GET /llm-research?prompt=... | $0.50 | AI research assistant with web search |
GET /tx-explainer?txHash=0x...&chain=base | $0.01 | Decode & explain EVM transactions across 11 chains |
Trading Resources
Read-only data sourced directly from Otto X’s own libs — Zerion for portfolios, vaults.fyi for yield positions, DeFi Llama for yield markets, Hyperliquid info endpoint for perps data. Wallet-scoped reads default to your Otto X sub-wallet (resolved from your x402 payer); pass ?address=0x... to query any other EVM address.
| Endpoint | Price | Description |
|---|
GET /portfolio | $0.001 | Multi-chain token balances for your Otto X sub-wallet (or ?address=) |
GET /supported-tokens?chainId=8453&search=USDC | $0.001 | Search tokens by symbol on a given chain (CoinGecko registry) |
GET /hyperliquid-account | $0.001 | Hyperliquid perpetual futures account + open positions |
GET /hyperliquid-market?asset=BTC | $0.001 | Perpetual market data + mark prices (omit asset for top-20 by leverage) |
GET /hl-transaction-history | $0.001 | Recent Hyperliquid fills. Optional ?limit= (default 50, max 200) |
GET /yield-markets | $0.001 | Available yield markets via DeFi Llama (filterable by protocol, chainId, tokenSymbol) |
GET /yield-farming-active | $0.001 | Active yield positions via vaults.fyi — 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 — deposit/redeem timeline with exact $0.05-per-op Otto fees, exact realized yield/APY per closed round-trip, and a totals summary |
GET /idle-capital | $0.001 | Detect undeployed tokens that could earn yield |
GET /yield-recommendations | $0.001 | Personalized vault recs based on your idle balances |
Agentic Wallet V2 — Autonomous DeFi Execution
Otto X provisions a TEE-custodied sub-wallet for each x402 payer and executes swaps, bridges, and DeFi deposits on their behalf — all signed inside OKX’s TEE, no user-side key management.
| Endpoint | Price | Description |
|---|
GET /sub-wallet?address=0x... | $0.01 | Resolve or provision your payer-bound Otto X sub-wallet. Use preview routes where available for free lookups. |
POST /auto-swap | $0.05 | In-chain swap via OKX DEX aggregator (500+ sources, 20 chains). Accepts principalAuth for one-call UX. |
POST /auto-bridge | $0.05 | Cross-chain bridge via OKX (Stargate / Across / Relay / Gas.zip, 17 chains). Accepts principalAuth. |
POST /auto-defi-invest | $0.05 | Deposit into allowlisted DeFi protocol (Aave V3, Lido, Compound V3, Morpho). Accepts principalAuth. |
POST /auto-defi-withdraw | $0.05 | Redeem an active DeFi position |
POST /yield-copilot | $0.05 | One-call yield — deploy 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 artifact. |
POST /yield-watch | $0.001 | Yield Watch — register for notify-only alerts OR a 30-day signed delegation for autonomous Aave↔Compound rebalances. See Yield Watch below. |
DELETE /yield-watch | $0.001 | Revoke the auto delegation (or pause notify mode). Signed-revoke (EIP-712) for auto; chat-id auth for notify. |
GET /yield-watch | $0.001 | Inspect your current subscription (mode, scope, signed caps, next nonce, move count, paused state). |
GET /yield-watch/audit | $0.001 | Read your audit trail — register/revoke/observation/alert/auto-move-started/-succeeded/-failed events with tx hashes. |
POST /auto-withdraw | $0.05 | Escape hatch — sweep funds from your sub-wallet to any external address |
GET /supported-protocols | free | Catalog of allowlisted protocol × chain × token combinations |
GET /defi-positions?address=0x... | free | Active DeFi positions for a sub-wallet |
Yield Watch
| Endpoint | Price | Description |
|---|
POST /yield-watch | $0.001 | Register or update notify/auto yield monitoring policy |
DELETE /yield-watch | $0.001 | Revoke an active yield-watch subscription |
GET /yield-watch | $0.001 | Read the caller’s current yield-watch subscription state |
GET /yield-watch/audit | $0.001 | Read the caller’s yield-watch audit trail |
Allowlisted protocols:
| Protocol | Chains |
|---|
| Aave V3 | Base, Arbitrum, Optimism, Polygon, Ethereum, X Layer |
| Lido | Ethereum |
| Compound V3 | Base, Arbitrum, Ethereum |
| Morpho | Base, Ethereum |
All four protocols × every chain in the table are reachable: each of those chains is in the gas-top-up + execution registry. (Lido is ETH staking on Ethereum, not a stablecoin venue.)
principalAuth launch chains (USDC EIP-3009): Base, Arbitrum, Optimism, Ethereum, Polygon. Plus X Layer (USDT0). Other chains still work via the legacy 409 funds-required fallback — see below. On Ethereum, ops are declined during a base-fee spike (above ~25 gwei) rather than subsidizing it.
Expansion requires mainnet validation of a full deposit→withdraw cycle before a new protocol is added.
Yield Copilot — POST /yield-copilot
One call deploys your idle stablecoin capital into yield:
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
Tier 3 of the yield ladder: instead of polling /yield-farming-active yourself, register once and let Otto watch your positions and either notify you via Telegram when there’s a better venue, or auto-rebalance under a 30-day signed delegation.
Two modes — the same endpoint, the body distinguishes:
Notify mode (no on-chain delegation, no spending limits — Otto just sends a Telegram receipt when a sustained APY gap opens, including the copy-pasteable two-call switch):
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
}
Auto mode (signed EIP-712 delegation — Otto will rebalance Aave↔Compound on your behalf, capped by maxMoves over 30 days and maxPrincipalRaw per move, every move audited + receipted to Telegram):
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
}
}
EIP-712 typed-data signing recipe (the client signs delegationMsg against this domain + types):
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,
});
Server verifies the signature using viem’s recoverTypedDataAddress and binds the result to the registered wallet. The delegation is atomically claimed via a single-statement CAS on next_nonce — concurrent registrations from the same wallet can’t replay each other, and a revocation always bumps the nonce so a stale signed message can’t replay after revoke.
Revoke (auto mode signs RevokeYieldDelegation with the current nonce; notify mode just sends a DELETE — chat-id ownership is the auth):
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> }
Guardrails (auto mode):
- 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.
Status reads:
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
The audit trail is the source of truth for “what did Otto do for me?” — every entry carries tx hashes (where applicable) and the resolved investment IDs, so a user can reproduce any move on-chain.
Pricing: all four endpoints are paywalled at $0.001 (registration / revocation / status / audit are bookkeeping; the value is the moves themselves which carry the standard $0.05 fee per leg via the underlying /auto-defi-withdraw + /yield-copilot calls Otto runs internally — same as a user-initiated rebalance).
Launch posture: Tier 3 launches Base USDC Aave ↔ Compound V3 first, with Morpho-on-Base and multi-chain (Arbitrum / Optimism / Ethereum / X Layer) auto support landing in v1.1 once each chain has soaked a manual deposit + withdraw cycle on mainnet.
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.05Ottofeeperopandtxhashes.Eachfullredemptioncarriesa‘realized‘block—‘realizedyieldusd‘and‘realizedapypct‘computed∗∗exactly∗∗(theon−chainamountthatactuallycamebacktoyoursub−wallet,minuswhatyoudeposited;APYannualizedovertheholdingperiod)forpositionswhosedeposit(s)Ottorecorded;a‘null‘‘realized‘witha‘reason‘meansitcouldn′tbeattributedcleanly(e.g.partialwithdrawal,positionfundedexternally,oritpre−datestheredeemed−amountinstrumentation).The‘summary‘adds‘realizedyield‘(lifetimerealized, # closed round-trips with a realized figure) alongside the exact total Otto fees. For current rates use GET /yield-farming-active.
Custody Model (Important)
Otto X’s Agentic Wallet is TEE-custodial, not self-custodial:
- 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.
This posture is specific to Otto X on X Layer. Otto AI’s other agents (Market Alpha, Trade Execution, Tools, Prediction Markets) remain non-custodial via Safe + Dynamic MPC.
Aligned with Agent Payments Protocol §8.4
This split — funded wallet off the per-action signing path, hot key in the TEE for autonomous execution — is exactly the architecture OKX’s Agent Payments Protocol whitepaper (§8.4 Separating signing from custody) describes for production agent commerce. Otto X has been running this design on mainnet since March 2026, ahead of the protocol’s public release. Once the APP wire-format spec is published, Otto X sub-wallets are a drop-in Buyer-Agent runtime for charge, session, and upto intents.
One-Call Flow via EIP-3009 principalAuth (recommended)
Recent clients collapse the old two-step funds-required dance into a single HTTP call by including a signed EIP-3009 TransferWithAuthorization note in the request body. The server verifies it, pulls your USDC (or USDT0 on X Layer) directly into your sub-wallet on-chain, then executes the op — all in one response.
Client-side recipe:
-
One-time preview —
GET /sub-wallet?address=0xYOUR_WALLET (free). Cache sub_wallet.evm_address indefinitely; it’s deterministic per payer.
-
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.
-
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..."
}
}
Sent with the x402 fee in PAYMENT-SIGNATURE.
Server guarantees, verified before touching the chain:
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).
The server then broadcasts token.transferWithAuthorization(...) (operator pays gas, user funds move straight from their wallet to their sub-wallet — no intermediate custody), tops up the sub-wallet with dust native gas if needed, executes the op, and returns 200 with all tx hashes.
Legacy Flow — HTTP 409 funds_required (fallback)
Clients that can’t sign EIP-3009 notes, or that target chains we haven’t enabled yet, fall back to the two-step flow. POST /auto-* without a principalAuth and with an insufficient sub-wallet balance returns:
{
"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."
}
Because the status is ≥ 400, x402 skips settlement — you’re NOT charged for the funds-required response. Only successful execution settles the service fee.
The same idempotency key can be reused for up to 7 days to re-submit the original intent once funds arrive. Re-submitting the same body with a fresh key returns the same op (dedup on payer + op type + body hash).
Free Endpoints
| Endpoint | Description |
|---|
GET / | Landing page + JSON service discovery |
GET /health | Service health check |
GET /tokens | Curated token registry (16 tokens) |
GET /llm.txt | AI-readable service catalog |
GET /.well-known/x402 | x402 discovery document |
GET /sub-wallet?address=0x... | Auto-provisioned sub-wallet EVM address + supported chains/assets |
GET /supported-protocols | DeFi allowlist catalog |
GET /defi-positions?address=0x... | Active DeFi positions (public on-chain read) |
x402 Payment Flow (OKX)
The flow is the same as our Base/Polygon deployment, but settlement happens on X Layer via OKX Facilitator instead of CDP Facilitator.
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
Otto X maintains a curated registry of 16 X Layer tokens, available for free at GET /tokens.
| Category | Tokens |
|---|
| Native | OKB |
| Stablecoins | USDT, USDG, USDC, USDe, frxUSD |
| Wrapped | WETH, WOKB, XBTC, XETH, XSOL, XOKSOL |
| DeFi | sUSDe, rsETH, LINK |
| Meme | XDOG |
The paid GET /all-tokens endpoint returns the full list from OKX DEX Aggregator (100+ tokens).
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
For a full client example showing discovery and the 402 payment flow, see examples/client.ts in the GitHub repo.
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