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.
Welcome to the technical documentation for the Otto AI Agent Swarm on the USDC / Circle Gateway surface. 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 integration via Circle’s gasless nanopayments rail.
All endpoints are accessible via x402 + Circle Gateway, allowing any developer or AI agent to pay per request in USDC with zero buyer gas by pre-funding a Circle Gateway balance once.
Base URL: https://usdc.ottoai.services
Protocol: x402 with Circle Gateway batched-settlement scheme — every 402 advertises scheme="exact" with a GatewayWalletBatched extra and is verified + settled by Circle’s facilitator.
Payment: USDC across Circle Gateway’s supported EVM chains — Base, Arbitrum, Optimism, Polygon, and additional Gateway-supported networks. Pre-fund the GatewayWallet contract once; every request is then a signed EIP-3009 authorization (offchain, sub-second). Circle batches net positions and settles them onchain in aggregate.
SDK: @circle-fin/x402-batching — Circle’s official buyer client.
Discovery:
What is Circle Gateway?
Circle Gateway is Circle’s batched-settlement rail for USDC. Instead of every request paying gas onchain, buyers pre-fund a GatewayWallet contract once, then sign EIP-3009 authorizations offchain per request. Circle’s facilitator verifies signatures, aggregates net positions across many calls, and settles them in batches.
Key properties:
- Gas-free for buyers — pre-fund once, then every call is an offchain signature
- Sub-cent pricing — a 0.001requestactuallycosts0.001, not “0.001plus0.30 in gas”
- Multi-chain — one Gateway balance is reachable across every supported EVM chain
- Agent-native — designed for high-frequency machine-to-machine payments
USDC vs x402 vs MPP
Otto AI runs three pay-per-request storefronts on top of the same underlying agent catalog. Same data, same agents, different payment rails.
| Feature | x402 | MPP | USDC (Circle Gateway) |
|---|
| Protocol | Coinbase x402 V2 | IETF Standard | x402 + Circle Gateway batched scheme |
| Payment | USDC on Base, Polygon, Solana | Tempo USDC.e + Stripe cards | USDC on Gateway-supported EVM chains |
| Buyer gas | Per-request onchain | Per-request onchain | None — pre-funded + batched |
| Headers | PAYMENT-REQUIRED / PAYMENT-SIGNATURE | WWW-Authenticate: Payment / Authorization: Payment | PAYMENT-REQUIRED / PAYMENT-SIGNATURE (with GatewayWalletBatched extra) |
| SDK | @x402/axios | mppx | @circle-fin/x402-batching |
| Base URL | https://x402.ottoai.services | https://mpp.ottoai.services | https://usdc.ottoai.services |
| Endpoints (v1) | 30+ | 25 | 6 (market intel, expanding) |
Which should I use? If you need gas-free sub-cent calls or high-frequency reads from an agent, use USDC (Circle Gateway). If you’re already on Base/Polygon/Solana with USDC and prefer the standard x402 flow, use x402. If you want Stripe cards or Tempo stablecoin payments, use MPP. Pricing (v1 catalog — 6 endpoints)
The USDC surface launches with a curated subset of Otto’s catalog. More routes are added as additional passthroughs land.
| Endpoint | Price | Description |
|---|
/crypto-news | $0.001 | Real-time crypto news with sentiment, ranked by importance |
/twitter-summary | $0.001 | Quick crypto-Twitter pulse — breaking news, trending narratives |
/token-details | $0.01 | Core market metrics (price, mcap, volume, supply, links) |
/tx-explainer | $0.01 | Plain-English explanation of any EVM transaction across 11 chains |
/token-intel | $0.05 | Deeper token intelligence — narrative + on-chain & social signals |
/yield-data | $0.05 | Live lending-yield (APY) data across Aave, Morpho, Compound, Maple |
How to Make a Request (Gateway Flow)
Step 1: Pre-fund the Gateway
Deposit USDC into Circle’s GatewayWallet contract once. Every supported chain reuses the same balance.
import { GatewayClient } from '@circle-fin/x402-batching'
import { privateKeyToAccount } from 'viem/accounts'
const account = privateKeyToAccount('0x...')
const client = new GatewayClient({ account, chain: 'base' })
// One-time deposit into the Gateway
await client.deposit({ amount: 5_000_000n }) // 5 USDC (6 decimals)
Step 2: Initial Request (Returns 402)
curl -v https://usdc.ottoai.services/crypto-news
PAYMENT-REQUIRED header. The decoded accepts[] includes a scheme="exact" option for each Gateway-supported chain, each with a GatewayWalletBatched extra:
{
"x402Version": 2,
"accepts": [
{
"scheme": "exact",
"network": "eip155:8453",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"payTo": "0x...",
"maxAmountRequired": "1000",
"maxTimeoutSeconds": 604900,
"extra": {
"name": "GatewayWalletBatched",
"verifyingContract": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE"
}
}
]
}
Step 3: Pay (Offchain EIP-3009 Signature) and Retry
The GatewayClient handles signing + retry automatically — no onchain transaction, no gas:
const response = await client.pay('https://usdc.ottoai.services/crypto-news')
const body = await response.json()
console.log(body) // { status: "success", data: { report: "..." } }
Step 4: Inspect Balance
const balances = await client.getBalances()
console.log(balances) // [{ chain: 'base', balance: '4998000' }, ...]
Endpoint Details
/crypto-news
Real-time crypto market news with sentiment analysis and top headlines ranked by importance.
curl https://usdc.ottoai.services/crypto-news
# (use @circle-fin/x402-batching to handle the 402)
{
"status": "success",
"data": { "report": "Top headlines: ..." }
}
/token-details
Core market metrics for a token: price, market cap, 24h volume, supply, official links.
| Parameter | Required | Description |
|---|
symbol | Yes | Token symbol (e.g., BTC, ETH, SOL) |
curl "https://usdc.ottoai.services/token-details?symbol=ETH"
/tx-explainer
Plain-English explanation of any EVM transaction across 11 supported chains.
| Parameter | Required | Description |
|---|
chain | Yes | EVM chain slug (base, arbitrum, optimism, polygon, ethereum, …) |
hash | Yes | Transaction hash (0x-prefixed) |
curl "https://usdc.ottoai.services/tx-explainer?chain=base&hash=0x..."
/token-intel
Deeper token intelligence: narrative, context, on-chain and social signals. Routes to the same upstream as /token-alpha on the x402 surface.
| Parameter | Required | Description |
|---|
symbol | Yes | Token symbol (e.g., BTC, ETH) |
/yield-data
Live lending-yield (APY) data across whitelisted lending protocols: Aave, Morpho, Compound, Maple (Syrup). No parameters.
curl https://usdc.ottoai.services/yield-data
{
"status": "success",
"data": {
// service-specific payload
}
}
{
"status": "failed",
"data": "Description of what went wrong"
}
Circle Agent Marketplace
Otto AI is applying to Circle’s Agent Service Registry — Circle’s curated marketplace where AI agents discover and pay for USDC-priced services without subscriptions or API keys. The USDC storefront at usdc.ottoai.services is the listing under review.
Support
