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

> Technical guide for accessing Otto's 6 read-only/query endpoints via Circle Gateway, with gas-free buyer payments from Gateway USDC.

Welcome to the technical documentation for the Otto AI Agent Swarm on the **USDC / Circle Gateway** surface. While our main [Agent Swarm overview](/introduction/otto-ai-swarm) 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](https://x402.org) with [Circle Gateway](https://www.circle.com/agents) 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](https://developers.circle.com/stablecoins/gateway-supported-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`](https://www.npmjs.com/package/@circle-fin/x402-batching) — Circle's official buyer client.

**Discovery:**

* [Landing Page](https://usdc.ottoai.services) — interactive endpoint explorer
* [LLM Docs](https://usdc.ottoai.services/llm.txt) — machine-readable for AI agents
* [Health](https://usdc.ottoai.services/health) — service status
* [Circle Agent Marketplace](https://agents.circle.com/services) — Otto's listing (in review)

## What is Circle Gateway?

[Circle Gateway](https://www.circle.com/agents) 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.001 request actually costs $0.001, not "$0.001 plus $0.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 multiple pay-per-request storefronts on top of the same underlying agents. The rails overlap, but they are intentionally scoped for different jobs.

| 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)** | 50                                       | 40 GET/read-only                                       | 6 GET/read-only                                                              |

<Tip>
  **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 broadest standard x402 flow, use [x402](/acp-swarm/x402). If you want Stripe cards or Tempo stablecoin payments for read-only/query access, use [MPP](/acp-swarm/mpp).
  For exact current counts and capability coverage, see [Access Paths & Coverage](/acp-swarm/storefront-parity).
</Tip>

## 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.001 | 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.001 | Deeper token intelligence — narrative + on-chain & social signals  |
| `/yield-data`      | \$0.001 | Live lending-yield (APY) data across Aave, Morpho, Compound, Maple |

All routes are GET requests. Pricing is informational; data is not financial advice.

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

```typescript theme={null}
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)

```bash theme={null}
curl -v https://usdc.ottoai.services/crypto-news
```

The server responds with **HTTP 402 Payment Required** and a `PAYMENT-REQUIRED` header. The decoded `accepts[]` includes a `scheme="exact"` option for each Gateway-supported chain, each with a `GatewayWalletBatched` extra:

```json theme={null}
{
  "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:

```typescript theme={null}
const response = await client.pay('https://usdc.ottoai.services/crypto-news')
const body = await response.json()
console.log(body) // { status: "success", data: { report: "..." } }
```

Circle's facilitator verifies the signature, debits your Gateway balance virtually, and Otto returns the response. The net position is later settled onchain in a batch with other Gateway activity.

### Step 4: Inspect Balance

```typescript theme={null}
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.

```bash theme={null}
curl https://usdc.ottoai.services/crypto-news
# (use @circle-fin/x402-batching to handle the 402)
```

Response:

```json theme={null}
{
  "status": "success",
  "data": { "report": "Top headlines: ..." }
}
```

### `/twitter-summary`

Quick pulse from crypto Twitter — breaking news, trending narratives, sentiment shifts. No parameters.

### `/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) |

```bash theme={null}
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)                                              |

```bash theme={null}
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.

```bash theme={null}
curl https://usdc.ottoai.services/yield-data
```

## Response Format

All endpoints return JSON with a consistent envelope:

```json theme={null}
{
  "status": "success",
  "data": {
    // service-specific payload
  }
}
```

On error:

```json theme={null}
{
  "status": "failed",
  "data": "Description of what went wrong"
}
```

When Otto returns any HTTP status ≥ 400, the x402 settlement step is **skipped** — you will not be charged for a failed request.

## Circle Agent Marketplace

Otto AI is applying to Circle's [Agent Service Registry](https://agents.circle.com/services) — 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

* **Twitter:** [@useOttoAI](https://twitter.com/useOttoAI)
* **Docs:** [docs.useotto.xyz](https://docs.useotto.xyz)
* **x402 API:** [x402.ottoai.services](https://x402.ottoai.services) (standard onchain payments)
* **MPP API:** [mpp.ottoai.services](https://mpp.ottoai.services) (IETF MPP / Stripe cards / Tempo)
* **Circle Gateway:** [circle.com/agents](https://www.circle.com/agents)
* **Circle Agent Marketplace:** [agents.circle.com/services](https://agents.circle.com/services)