# DeFi Intel Agent Gateway — agent onboarding (30 seconds)

Paid DeFi data microservices via x402 (USDC). 40 products, 8 payment networks
(Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche, HPP, Stellar). No
accounts, no API keys required for per-call payment.

## 1. Discover
- HTTP catalog: GET https://defi-intel-agent-gateway.gg-neo15.workers.dev/v1/discovery  (40 products, methods, prices)
- MCP: connect to https://defi-intel-agent-gateway.gg-neo15.workers.dev/.mcp (streamable-http, initialize + tools/list)
- Plain text: GET https://defi-intel-agent-gateway.gg-neo15.workers.dev/llms.txt
- Pay doc: GET https://defi-intel-agent-gateway.gg-neo15.workers.dev/x402-pay.md

## 2. Call a product
Pick any `/v1/...` path from discovery. Without payment you get HTTP 402 +
`PAYMENT-REQUIRED` header (base64 x402 v2 manifest: price, network, payTo,
EIP-712 domain via `eip712ByChain`).

## 3. Pay (pick ONE)
- EIP-3009: sign TransferWithAuthorization from the manifest, resend with
  `PAYMENT-SIGNATURE` header (direct, any USDC wallet on any of the 8 networks).
- Prepaid (no wallet): POST /v1/keys/starter — pay $0.01 once, get a key with
  $0.05 credit; then call any product with `x-api-key: <key>` forever until
  credit runs out. Best for recurring use (e.g. polling base-gas-oracle).
- Facilitator: payAI / Dexter / HPP / Stellar handle verify+settle for you.
- MPP client (mppx / Cloudflare Agents withX402Client): point your MPP/x402
  client at the 402 — the `WWW-Authenticate: Payment` header carries the full
  evm.charge challenge; it pays directly (Credential in `Authorization: Payment`),
  zero custom code. Paid responses include a `Payment-Receipt` header.
- Session (recurring/polling): POST /v1/session to fund a prepaid balance once,
  then call any product with `x-session: <token>` — debits per call, no per-call
  signing. Best for a poller (e.g. base-gas-oracle).

## 4. Free samples first
Send `X-Trial: 1` to get up to 5 free calls/day/IP per product before paying.

## 5. Poller recipe — base-gas-oracle on a schedule (6 lines)
For an agent that polls a feed (e.g. gas prices every N minutes), open a SESSION
once and then poll — no per-call signing/settlement:

```bash
# 1) Fund a session once ($0.05 -> session token). Follow the 402 to pay:
curl -s -X POST https://defi-intel-agent-gateway.gg-neo15.workers.dev/v1/session -H 'content-type: application/json' -d '{}'
#   -> 402 + PAYMENT-REQUIRED; sign EIP-3009, resend -> 201 { session_token: "sess_..." }
TOKEN="sess_..."   # keep it; each call debits $0.001

# 2) Poll forever — no signature needed:
while true; do
  curl -s "https://defi-intel-agent-gateway.gg-neo15.workers.dev/v1/chain/base-gas-oracle" -H "x-session: $TOKEN"
  sleep 900   # every 15 min
done
```

A $0.05 session funds ~50 calls (base-gas-oracle). Refill with another
`POST /v1/session` when the balance runs out.

## 6. Pay from a Cloudflare Agent / any MPP client (mppx)
Install `mppx` + `viem` in your agent and it auto-pays every 402 — no custom
payment code:

```bash
npm i mppx viem
```

**HTTP (fetch auto-pays):**
```ts
import { Fetch, evm } from "mppx/client";
import { privateKeyToAccount } from "viem/accounts";

const fetch = Fetch.from({
  methods: [
    evm.charge({
      account: privateKeyToAccount(process.env.PRIVATE_KEY),
      currencies: [evm.assets.base.USDC], // Base mainnet USDC
      maxAmount: "1.00",
    }),
  ],
});

const r = await fetch("https://defi-intel-agent-gateway.gg-neo15.workers.dev/v1/chain/base-gas-oracle");
// -> HTTP 402 -> signs EIP-3009 -> retries -> 200 with data
```

**Cloudflare Agent + MCP tools:**
```ts
import { Agent } from "agents";
import { McpClient, evm } from "mppx/mcp/client";
import { privateKeyToAccount } from "viem/accounts";

export class MyAgent extends Agent {
  async onStart() {
    const { id } = await this.addMcpServer("defi-intel", "https://defi-intel-agent-gateway.gg-neo15.workers.dev/.mcp");
    const client = McpClient.wrap(this.mcp.mcpConnections[id].client, {
      methods: [
        evm.charge({
          account: privateKeyToAccount(this.env.PRIVATE_KEY),
          currencies: [evm.assets.base.USDC],
        }),
      ],
    });
    const r = await client.callTool({ name: "base_gas_oracle", arguments: {} });
    // Free tools pass through; paid tools auto-pay via the challenge in _meta
  }
}
```

The wallet must hold a little USDC on Base mainnet. Entry ticket: $0.001 per call
(base-gas-oracle). The 402 body + `WWW-Authenticate: Payment` carry the full
charge details (amount, USDC, recipient, chainId).

## Entry ticket
`GET /v1/chain/base-gas-oracle` = $0.001 — cheapest call, proves the rail.
See GET https://defi-intel-agent-gateway.gg-neo15.workers.dev/x402-pay.md for full detail.