Skip to main content
Welcome to the technical documentation for the Otto AI Agent Swarm on x402. While our main Agent Swarm overview explains what our agents do, this page provides the specific endpoint details, request parameters, and examples needed for programmatic, machine-to-machine (M2M) integration. All endpoints are accessible via the x402 protocol, allowing any developer or AI agent to pay for and consume our services in real-time. Base URL: https://x402.ottoai.services Network: Base Mainnet Payment: USDC (via the x402 protocol)

​
How to Make a Request (x402 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 will reject this request with an HTTP 402 Payment Required status code. The response body contains the payment details. 
# Example: Requesting top 10 headlines
curl -i "https://x402.ottoai.services/top-ten"

# Server Responds:
HTTP/1.1 402 Payment Required
Content-Type: application/json
...

{
  "error": "Payment required",
  "accepts": [
    {
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
      "maxAmountRequired": "1000", // 0.001 USDC (6 decimals)
      "network": "base",
      "payTo": "0xYourPaymentAddress",
      "scheme": "exact"
    }
  ]
}

​
Step 2: Client Signs & Pays

The client must now use a wallet to:
  1. Read the payment requirements from the 402 response.
  2. Construct and sign a valid payment payload (like an EIP-3009 transferWithAuthorization).
This is typically handled by an x402-compatible client library.

​
Step 3: Retry Request with Payment Header

The client retries the exact same request, but this time includes an X-PAYMENT header containing the signed payment payload. 
# Example: Retrying the request with payment
curl "https://x402.ottoai.services/top-ten" \
     -H "X-PAYMENT: 0x..." # The signed payment payload

​
Step 4: Success (Receives Data)

The server receives the request, verifies the payment payload with a Facilitator (see Understanding the Facilitator), and, if valid, settles the transaction and returns the 200 OK response with the requested data. 
# Server Responds:
HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "headlines": [
    {
      "title": "Bitcoin & Ethereum Brace for Powell's Speech...",
      "source": "CryptoNews",
      "impact_score": 9.5
    },
    ...
  ]
}

​
Understanding the Facilitator

The Facilitator is a critical component of the x402 payment flow. It acts as a trusted intermediary that:
  1. Validates Payment Signatures: Verifies that the payment authorization in the X-PAYMENT header is cryptographically valid and signed by the account with sufficient balance.
  2. Prevents Replay Attacks: Ensures each payment signature can only be used once by tracking nonces and timestamps.
  3. Executes On-Chain Settlement: Submits the validated payment transaction to the blockchain (Base network) to transfer USDC from the buyer to the service provider.
  4. Provides Instant Confirmation: Returns confirmation to the API server within milliseconds, enabling real-time service delivery.
Key Points:
  • The Facilitator is a separate service operated by the x402 protocol infrastructure
  • All payment validations happen off-chain for speed, but settlements are on-chain for security
  • Payment signatures typically expire after a short window (e.g., 60 seconds) to prevent stale transactions
  • Each payment includes a unique nonce to prevent replay attacks

​
Client-Side Example (Node.js / Axios)

For programmatic access, we recommend using a client library like x402-axios to handle this flow automatically. 
import { withPaymentInterceptor } from 'x402-axios';
import axios from 'axios';
import { privateKeyToAccount } from 'viem/accounts';

// ⚠️ SECURITY WARNING: Never hardcode private keys in your source code!
// Always use environment variables or secure key management systems.
const account = privateKeyToAccount(process.env.PRIVATE_KEY);

// Create an axios client for the Otto API
const client = withPaymentInterceptor(
  axios.create({ baseURL: 'https://x402.ottoai.services' }),
  account
);

// Make the request with error handling
try {
  const response = await client.get('/top-ten');
  console.log('Response data:', response.data);
} catch (error) {
  if (error.response?.status === 402) {
    // Payment flow failed - check balance or payment authorization
    console.error('Payment failed:', error.response.data);
    console.error('Required amount:', error.response.data.accepts[0].maxAmountRequired);
  } else if (error.response?.status === 400) {
    // Invalid request parameters
    console.error('Invalid request:', error.response.data);
  } else if (error.response?.status === 500) {
    // Server error
    console.error('Server error. Please try again later.');
  } else if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
    // Network error
    console.error('Network error. Check your connection.');
  } else {
    // Unknown error
    console.error('Unexpected error:', error.message);
  }
}

​
API Endpoint Reference

​
News & Social

AI-curated crypto market news, headlines, and social sentiment.

​
GET /crypto-news

Fetches a comprehensive, AI-curated summary of the latest market news, including top stories, regulatory updates, and DeFi trends. Price: 0.001 USDC Parameters: None Example Request: 
curl "https://x402.ottoai.services/crypto-news" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "report": "Your Crypto News Brief\n\nOverview: Cryptocurrency markets experienced increased activity today, driven by easing macroeconomic conditions, regulatory developments, and notable shifts in market structure and technology.\n\nMarket Sentiment:\nOverall Bull/Bear Score: 78\n\nKey Developments:\n* Crypto M&A activity reached a record $10 billion in Q3 2025, fueled by easing macroeconomic conditions boosting demand for both Bitcoin and gold as alternative assets.\n* News regarding a potential end to the US-China trade war has influenced global market sentiment, contributing to a crypto market rally.\n* Speculation around a potential pardon by Trump has spurred plans for Binance to re-enter the U.S. market, potentially reshaping the competitive landscape.\n* Hong Kong approved Asia's first Solana ETF, signaling growing institutional acceptance, while Russia and Kyrgyzstan are integrating crypto into their national financial systems.\n\n[Powered by $OTTO AI | @OttoWallet]"
}

​
GET /filtered-news

Get news filtered for a specific crypto topic (e.g., “Airdrops”, “DeFi trends”, “Bitcoin ETF”). Price: 0.001 USDC Parameters:
  • topic (string, required): The topic to filter news for.
Example Request: 
curl "https://x402.ottoai.services/filtered-news?topic=AI%20Agents" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "report": "🎯 FILTERED CRYPTO NEWS: AI AGENTS\n📊 Confidence Score: High\n📈 Sources: Twitter (Yes), News (Yes), Historical (Yes)\n⏰ Generated: Oct 26, 06:14 PM\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nFellow traders and DeFi users, the 'AI Agents' narrative is undeniably heating up, and we're seeing tangible signs of capital flowing into this nascent but rapidly evolving sector. While comprehensive institutional reports on 'AI Agent token sector capital flows' are still developing, the on-chain activity and market buzz from today's data provide a clear signal.\n\nKey indicators point to AI Agents as a rapidly emerging \"hot narrative\" in crypto. We're observing specific tokens catching significant attention: for instance, some traders are noting that `#Ai agents are pumping hard`, with expectations that tokens like **$Ake** and **$Pippin** will follow this upward trend.\n\n**Coinbase x402 transactions are up a staggering 10,000% as AI agents go live.** This explosion in transaction volume for a micro-transaction layer token directly linked to AI agent operations indicates real-world utility and increasing adoption on the blockchain.\n\n[Powered by $OTTO AI | @OttoWallet]",
  "topic": "AI Agents"
}

​
GET /top-ten

Receive a quick digest of the 10 most important crypto news headlines, ranked by relevance and potential impact. Price: 0.001 USDC Parameters: None Example Request: 
curl "https://x402.ottoai.services/top-ten" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "headlines": "IMPORTANCE RANKING:\n\n1. **Crypto M&As Hit Record $10B in Q3 2025 as Easing Boosts Bitcoin and Gold Demand** - This article highlights significant institutional capital inflow and market maturation, with M&A volumes reaching record highs.\n\n2. **US-China Trade War To End – Will Crypto Market Rally?** - A potential end to the US-China trade war is a major geopolitical and macroeconomic development.\n\n3. **Crypto U.S News: Trump Pardon Fuels Binance Plans to Reenter U.S. Market** - Binance's potential re-entry into the U.S. market following a high-profile pardon would be a monumental event.\n\n4. **SOL ETF, Crypto PM, and Russian Reforms, Asia's Bold** - This article covers multiple crucial global developments: Hong Kong's approval of Asia's first Solana ETF.\n\n5. **Cardano Founder Hoskinson Backs Selig's CFTC Chair Pick Amid Crypto Regulation Shifts** - The appointment of Michael Selig signals a potentially pro-crypto shift in regulatory policy.\n\n[Powered by $OTTO AI | @OttoWallet]"
}

​
GET /twitter-summary

Get curated insights and sentiment analysis from the crypto community on X (Twitter), identifying trending topics and top tweets. Price: 0.001 USDC Parameters: None Example Request: 
curl "https://x402.ottoai.services/twitter-summary" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "digest": "📰 CRYPTO TWITTER DIGEST - Oct 26, 06:16 PM\n\n━━━ CRITICAL ALERTS ━━━\n🚨 Vitalik warns off-chain security not guaranteed even with blockchain's 51% attack protection.\n\n━━━ DEFI ECOSYSTEM ━━━\n🔄 Advisor adds $10K of $VALOR to Meteora liquidity pool.\n\n━━━ OTHER NEWS ━━━\n📌 Smart trader with 100% win rate increases $BTC and $ETH long positions.\n📌 Binance paid $450k for lobbying the White House in September.\n📌 Kraken's Q3 revenue hits all-time high, driven by 2025 acquisitions and IPO prep.\n📌 Whale accumulated 3,195 $BTC in 3 hours.\n📌 Whale opened 40x long on $BTC and 10x long on $HYPE.\n📌 Zelle to enable international crypto stablecoin transactions.\n📌 Richard Heart deposits $102M worth of $ETH.\n📌 Whale rotated from $SOL to $ETH, selling $18.5M $SOL for $ETH.\n\n[Powered by $OTTO AI | @OttoWallet]",
  "timestamp": "2025-10-26T18:16:19.356Z"
}

​
GET /historical-summaries

Access a 30-day historical news archive. This is a premium B2B service for research, backtesting, or populating a knowledge base. Price: 0.001 USDC Parameters: None Example Request: 
curl "https://x402.ottoai.services/historical-summaries" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "summaries": "[
    {
      \"end_time\": \"2025-10-26T00:00:00.000Z\",
      \"generated_at\": \"2025-10-26T00:00:29.584Z\",
      \"start_time\": \"2025-10-25T18:00:00.000Z\",
      \"top_ten\": \"IMPORTANCE RANKING:\\n\\n1. **Crypto News: Is This the Most Bullish Update for Bitcoin and Ethereum to Date?**\\n    * **Explanation:** JPMorgan Chase, a major U.S. bank, accepting Bitcoin and Ethereum as collateral for loans is a monumental step for institutional adoption and market legitimacy.\\n\\n2. **Trump Names SEC Crypto Task Force Head Selig as Next Nominee to Run U.S. CFTC**\\n    * **Explanation:** The potential appointment of a crypto-knowledgeable official to lead the CFTC could lead to clearer regulatory frameworks and increased market certainty.\\n\\n3. **Trump's Pardon of Binance Founder CZ May Signal Crypto's Expanding Washington Influence**\\n    * **Explanation:** A presidential pardon for CZ suggests a growing influence of the crypto industry in Washington and could signal a more lenient regulatory approach.\\n\\n[... 7 more ranked headlines]\"
    },
    {
      \"end_time\": \"2025-10-25T00:00:00.000Z\",
      \"generated_at\": \"2025-10-25T00:00:39.835Z\",
      \"start_time\": \"2025-10-24T18:00:00.000Z\",
      \"top_ten\": \"IMPORTANCE RANKING:\\n1. **Trump Picks SEC Crypto Counsel Michael Selig to Lead CFTC Amid Crypto Oversight Push** - Michael Selig's nomination signals a major push for unified and clearer crypto oversight in the U.S.\\n\\n2. **U.S. CPI Data Dips as Fed Rate Cut Odds Hit 97%: What's Next for Crypto?** - Lower-than-expected CPI data and high probability of Fed rate cuts are critical macroeconomic drivers for crypto markets.\\n\\n[... 8 more ranked headlines]\"
    }
  ]"
}
Note: The response contains 30 days of daily news summaries. Each summary includes:
  • start_time / end_time: The time window covered
  • generated_at: When the summary was created
  • top_ten: The 10 most important headlines for that day, ranked by impact

​
Market Intelligence

Access real-time token metrics, market analysis, and sentiment.

​
GET /token-details

Get a snapshot of a token’s core metrics, performance, and trading data. Price: 0.001 USDC Parameters:
  • token (string, required): The token symbol (e.g., “SOL”, “ETH”).
Example Request: 
curl "https://x402.ottoai.services/token-details?token=SOL" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "token": "SOL",
  "price": 145.20,
  "market_cap": 65000000000,
  "performance": {
    "1h": 0.5,
    "24h": 2.1,
    "7d": -3.4
  },
  "volume_24h": 1200000000,
  "supply": {
    "circulating": 448000000,
    "total": 570000000
  },
  "momentum_signal": "NEUTRAL"
}

​
GET /token-alpha

Receive a comprehensive, AI-enhanced report that combines all Token Details with filtered news, sentiment signals, and actionable insights. Price: 0.001 USDC Parameters:
  • token (string, required): The token symbol (e.g., “SOL”, “ETH”).
Example Request: 
curl "https://x402.ottoai.services/token-alpha?token=ETH" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "token": "ETH",
  "price": 2847.32,
  "market_cap": 342000000000,
  "performance": {
    "1h": 0.3,
    "24h": 1.8,
    "7d": 4.2
  },
  "alpha_signals": {
    "momentum": "BULLISH",
    "institutional_sentiment": "POSITIVE",
    "key_narratives": ["Ethereum Supercycle", "Institutional Tokenization", "L2 Scaling"]
  },
  "news_summary": "Ethereum's 'supercycle' thesis is gaining traction, with projections of ETH reaching $21,000 anchored in institutional RWA tokenization...",
  "recommendation": "ACCUMULATE"
}

​
GET /kol-sentiment

Analyzes tweets from the top 50 crypto Key Opinion Leaders (KOLs) to provide a market sentiment score, key narratives, and trending tokens. Price: 0.001 USDC Parameters: None Example Request: 
curl "https://x402.ottoai.services/kol-sentiment" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "report": "\n=== OTTO KOL SENTIMENT ALPHA ===\nGenerated: 2025-10-26T18:48:48.495Z\n\n📊 OVERALL SENTIMENT\nBULLISH\nScore: 78%\n\n🎯 KEY NARRATIVES\n1. The Resurgence of Privacy: Zcash Leads the Charge in a Post-Surveillance World\n2. Base Layering Up: x402 Protocol Catalyzing Mainstream Adoption\n3. Ethereum's Supercycle Thesis: Institutional Tokenization Fuels a $21K Vision\n\n🔥 TRENDING TOKENS\n• Hottest Major: BTC\n• Trending Altcoins: ZEC, SEDA, PAYAI, ARB, GRNY, BMNR, IWM\n\n💎 TOP KOL INSIGHTS\n• @fundstrat (1623 engagement)\n  \"Positive development USA 🇺🇸 - China 🇨🇳 trade relations\n  - ⬆️ for equities $SPY $QQQ $IWM\n  - ⬆️for supercycle Ethereum $ETH\n  - ⬆️ for Bitcoin $BTC\"\n\n📝 SUMMARY\nThe crypto market intelligence gathered from recent KOL activity points towards a distinctly bullish sentiment, underscored by a blend of macro catalysts, significant institutional interest, and emerging narratives driving specific altcoin rallies.\n\n[Powered by $OTTO AI | @OttoWallet]"
}

​
GET /yield-alpha

Discover the best DeFi yield opportunities across blue-chip protocols like AAVE, Morpho, and Pendle, with APY comparisons. Price: 0.001 USDC Parameters: None Example Request: 
curl "https://x402.ottoai.services/yield-alpha" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "opportunities": "=== OTTO YIELD ALPHA OPPORTUNITIES ===\nUpdated: October 26, 6:37 PM GMT\n\n=== BLUE-CHIP YIELDS (Low Risk, Best of the Best) ===\nFiltered for highest quality DeFi: High TVL, Pendle Prime, Blue Chip Protocols\n\nBest Stablecoin: Morpho - USDC (Arbitrum)\n   * APY: 10.40%\n   * TVL: $13,528,117\n   * Blue chip crypto + RWA collateral strategy\n   * Market: https://app.morpho.org/arbitrum/vault/0x5c0C306Aaa9F877de636f4d5822cA9F2E81563BA/steakhouse-high-yield-usdc\n\nBest ETH: Morpho - WETH (Ethereum)\n   * APY: 3.81%\n   * TVL: $17,480,478\n   * Morpho vault with $17M TVL\n\nBest BTC: Pendle Prime - eBTC (Ethereum)\n   * APY: 1.78%\n   * TVL: $1,731,713\n   * Pendle Prime PT market (expires Dec 18, 2025)\n\n[Powered by $OTTO AI | @OttoWallet]"
}

​
GET /trending-altcoins

Discover the top 3 trending altcoins (Rank 10-500) with a “Why it’s Trending” thesis and key metrics. Price: 0.001 USDC Parameters: None Example Request: 
curl "https://x402.ottoai.services/trending-altcoins" -H "X-PAYMENT: 0x..."
Sample Response: 
{
  "status": "success",
  "report": "=== OTTO TOP 3 TRENDING ALTCOINS ===\nGenerated: Sun, 26 Oct 2025 18:05:00 GMT\n\n**1. HYPE (Hyperliquid) - CMC Rank #11**\n🔥 WHY IT'S TRENDING:\n* A 'digital Nasdaq' disrupting derivatives by listing equity and commodity perps – a true game-changer!\n* A 'Giant Company' is pursuing a monumental $1 Billion acquisition, mirroring MicroStrategy's Bitcoin strategy for altcoins!\n* Explosive rally with a 143.79% surge in 24h volume and 'insane' monthly candles, signaling massive retail and institutional FOMO.\n📊 KEY METRICS: Price: $47.50 | Market Cap: $15.99B | 24h Volume: $635.52M | 24h Change: 📈 13.56%\n🎯 BULLISH THESIS: HYPE is a crypto powerhouse at the nexus of institutional validation and a rapidly expanding derivatives market.\n\n**2. ZEC (Zcash) - CMC Rank #24**\n🔥 WHY IT'S TRENDING:\n* Leading the charge in the \"Q4: ZEC szn\" narrative, as privacy coins make a dramatic resurgence!\n* Rapidly surging with a 531.85% gain in 30 days and a stunning 26.06% increase today, nearing an all-time high!\n📊 KEY METRICS: Price: $347.89 | Market Cap: $5.66B | 24h Volume: $1.08B | 24h Change: 📈 26.91%\n\n**3. AAVE (Aave) - CMC Rank #32**\n🔥 WHY IT'S TRENDING:\n* Aave V4 is set to unify liquidity, positioning the protocol to bring \"the next trillion dollars onchain\"!\n* Commanding leadership in Real-World Assets (RWAs) with over $350 million in net deposits.\n📊 KEY METRICS: Price: $236.60 | Market Cap: $3.61B | 24h Volume: $240.03M | 24h Change: 📈 4.90%\n\n[Powered by $OTTO AI | @OttoWallet]"
}

​
AI Tools Agent

Advanced AI for knowledge, research, and creativity.

​
POST /llm-research

Get instant, reliable answers to any question, or summarize a webpage/document from a URL. Powered by Google’s Gemini 2.5 Pro with live web search. Price: 0.001 USDC Request Body: (JSON)
  • prompt (string, optional): A question or prompt for the AI.
  • url (string, optional): A URL to summarize or analyze.
Note: You can provide prompt, url, or both parameters together. Example Request (Prompt): 
curl -X POST "https://x402.ottoai.services/llm-research" \
     -H "Content-Type: application/json" \
     -H "X-PAYMENT: 0x..." \
     -d '{"prompt": "Explain Base Chain in simple terms."}'
Example Request (URL): 
curl -X POST "https://x402.ottoai.services/llm-research" \
     -H "Content-Type: application/json" \
     -H "X-PAYMENT: 0x..." \
     -d '{"url": "https://some-crypto-news-site.com/article"}'
Sample Response: 
{
  "status": "success",
  "response_text": "Base Chain is a Layer 2 (L2) blockchain built on Ethereum, developed by Coinbase. It offers faster and cheaper transactions compared to Ethereum's main network while inheriting Ethereum's security. Base is designed to make decentralized applications more accessible and affordable for everyday users.",
  "sources": [
    "https://base.org",
    "https://docs.base.org/overview"
  ]
}

​
POST /generate-meme

Transforms a detailed text prompt into a high-quality PNG image, perfect for memes and branding, with high-fidelity text rendering. Price: 0.001 USDC Request Body: (JSON)
  • prompt (string, required): A detailed description of the image. Be specific and include text you want rendered.
Example Request: 
curl -X POST "https://x402.ottoai.services/generate-meme" \
     -H "Content-Type: application/json" \
     -H "X-PAYMENT: 0x..." \
     -d '{"prompt": "A photorealistic image of a golden Bitcoin rocket launching into space with the text TO THE MOON in bold letters at the top"}'
Sample Response: 
{
  "status": "success",
  "image_url": "https://images.ottowallet.xyz/api/images/1761442152697.png",
  "prompt_used": "A photorealistic image of a golden Bitcoin rocket launching into space with the text TO THE MOON in bold letters at the top"
}

​
POST /video-gen

Generates high-quality video from text or image using OpenAI’s Sora 2 models. Pricing is dynamic based on the selected model and duration. Price: Dynamic ( 1.00−1.00 - 7.50 USDC ) ricing Tiers:
Model4s Price8s Price12s Price
sora-2$1.00$2.00$3.00
sora-2-pro$2.50$5.00$7.50
Request Body: (JSON) prompt (string, required): A detailed description of the video. model (string, required): Model to use: sora-2 (Standard) or sora-2-pro (Pro). seconds (number, required): Duration of the video: 4, 8, or 12. orientation (string, optional): Video aspect ratio: portrait or landscape (default: ‘portrait’). image_url (string, optional): Source image URL for image-to-video generation.

​
Troubleshooting

​
Common Issues and Solutions

​
Issue: “Payment verification failed”

Possible Causes:
  • Insufficient USDC balance in your wallet
  • Payment signature has expired (signatures are valid for ~60 seconds)
  • Invalid or corrupted payment signature
  • Payment already used (replay attack prevention)
Solutions:
  • Verify your USDC balance on Base network
  • Ensure your system clock is synchronized (NTP)
  • Regenerate the payment signature and retry immediately
  • Check that you’re not reusing old payment signatures

​
Issue: “Invalid token parameter”

Possible Causes:
  • Token symbol doesn’t exist or is misspelled
  • Using full token name instead of symbol (e.g., “Bitcoin” instead of “BTC”)
Solutions:
  • Use standard token symbols: BTC, ETH, SOL, etc.
  • Ensure the token symbol is uppercase
  • Check CoinMarketCap for the correct symbol

​
Still Having Issues?

If you’re experiencing problems not covered here:
  1. Check our status page: status.ottoai.services (if available)
  2. Review the error message: Our error responses include detailed information
  3. Contact support: Reach out to our developer support team
  4. Join our TG: Connect with other developers in our community

​
Additional Resources

[Powered by $OTTO AI | @OttoWallet]