Developer documentation

Agent calls your URL
  → No payment header → your server returns 402 + payment details
  → Agent's SDK pays Circle Gateway (~200ms, off-chain)
  → Agent retries with payment proof
  → Your middleware verifies payment
  → Your handler runs, returns data
  → Earnings settle to your Arc address

# In your server project
npm install @circle-fin/x402-batching express

import express from "express";
import { createGatewayMiddleware } from "@circle-fin/x402-batching/server";

const app = express();

// Replace with your UCW wallet address from the Obol dashboard
const SELLER = process.env.SELLER_ADDRESS;

const gateway = createGatewayMiddleware({
  sellerAddress: SELLER,
  networks: "eip155:5042002",                          // Arc testnet
  facilitatorUrl: "https://gateway-api-testnet.circle.com",
});

// $0.002 USDC per call to this route
app.get("/enrich", gateway.require("$0.002"), (req, res) => {
  const domain = req.query.domain || "example.com";
  res.json({
    domain,
    company: "Acme Inc.",
    // req.payment is populated after a successful payment
    paidBy: req.payment?.payer,
    txHash: req.payment?.transaction,
  });
});

app.listen(4021);

const gateway = createGatewayMiddleware({
  sellerAddress: SELLER,
  networks: "eip155:5042002",
  facilitatorUrl: "https://gateway-api-testnet.circle.com",
});

// Cheap: basic lookup
app.get("/company/basic", gateway.require("$0.001"), (req, res) => {
  res.json({ name: "Acme Inc.", country: "US" });
});

// Medium: full profile
app.get("/company/full", gateway.require("$0.005"), (req, res) => {
  res.json({ name: "Acme Inc.", headcount: 420, revenue: "$12M", ... });
});

// Expensive: bulk batch (up to 50 domains per call)
app.post("/company/bulk", gateway.require("$0.050"), async (req, res) => {
  const { domains } = req.body;
  const results = await enrichAll(domains);   // your own logic
  res.json({ results, count: results.length });
});

// Free: health check (no middleware = no payment required)
app.get("/health", (_req, res) => res.json({ ok: true }));

# Your server's environment — buyers never see any of this
SELLER_ADDRESS=0xYourArcWallet
OPENAI_API_KEY=sk-...
SOME_DATA_API_KEY=abc123
SCRAPER_PROXY_PASSWORD=xyz789

import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// You pay OpenAI ~$0.002/call (GPT-4o-mini).
// You charge agents $0.004/call → $0.002 margin per call.
app.post("/complete", gateway.require("$0.004"), async (req, res) => {
  const { prompt } = req.body;
  const chat = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: prompt }],
  });
  res.json({
    result: chat.choices[0].message.content,
    paidBy: req.payment?.payer,
  });
});

import puppeteer from "puppeteer";

// Agents pay $0.01 per page scrape. You pay server costs (~$0.001).
app.get("/scrape", gateway.require("$0.010"), async (req, res) => {
  const { url } = req.query;
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: "networkidle2" });
  const text = await page.evaluate(() => document.body.innerText);
  await browser.close();
  res.json({ url, text, charCount: text.length, paidBy: req.payment?.payer });
});

// Agents call your endpoint and pay $0.001.
// Your server calls the premium API with your key.
// Agents never see your key.
app.get("/weather", gateway.require("$0.001"), async (req, res) => {
  const { city } = req.query;
  const r = await fetch(
    `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_KEY}&q=${city}`
  );
  const data = await r.json();
  res.json({
    city: data.location.name,
    temp_c: data.current.temp_c,
    condition: data.current.condition.text,
    paidBy: req.payment?.payer,
  });
});

# Terminal 1 — run your server
SELLER_ADDRESS=0xYourArcAddress node server.mjs

# Terminal 2 — expose it publicly (no install needed)
npx localtunnel --port 4021
# → your url is: https://happy-dogs-fly.loca.lt

# 1. Push your server code to a GitHub repo

# 2. Go to railway.app → New Project → Deploy from GitHub

# 3. Set environment variables in Railway dashboard:
#    SELLER_ADDRESS = 0xYourArcAddress
#    PORT           = 4021
#    (any API keys your server needs)

# 4. Railway gives you a URL like:
#    https://your-project.railway.app
# Use that URL when registering in the Obol dashboard.

1. Agent deposits USDC into Circle Gateway (one time, any amount)
2. Agent calls a paid API endpoint
3. Server returns 402 + payment details (seller address, amount, network)
4. Agent's SDK signs an EIP-3009 off-chain authorization (~200ms, no gas)
5. Circle Gateway verifies and records the payment
6. Agent retries the request with the payment header
7. Server verifies → processes → returns data
8. Gateway settles to seller on Arc (batched, gasless)

# 1. Generate a new EOA private key (keep this secret):
node -e "const {Wallet} = require('ethers'); const w = Wallet.createRandom(); console.log('address:', w.address, '\nkey:', w.privateKey)"

# 2. Fund it with testnet USDC:
#    Go to faucet.circle.com → select Arc testnet → paste the address

# 3. Set your agent key in your environment:
export OBOL_AGENT_KEY=0xYourPrivateKey

npm install @circle-fin/x402-batching

import { GatewayClient } from "@circle-fin/x402-batching/client";

const buyer = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.OBOL_AGENT_KEY,
});

// One-time: deposit USDC into Gateway (from your Arc wallet)
await buyer.deposit("10");   // deposit 10 USDC

// Check your Gateway balance
const balances = await buyer.getBalances();
console.log("Available:", balances.available, "USDC");

// Pay and call any Obol-powered endpoint
const { data, transaction } = await buyer.pay(
  "https://your-provider.railway.app/enrich?domain=acme.com"
);

console.log("Response:", data);
console.log("Paid in tx:", transaction);

// The buyer.pay() call handles the full 402 → pay → retry flow.
// No manual steps. If the server returns 402, the SDK pays and retries.

// List all services in the Obol marketplace
const res = await fetch("https://obol-arc.web.app/api/services");
const { services } = await res.json();

for (const svc of services) {
  console.log(svc.name, "→", svc.hostedUrl, "@ $" + svc.priceUsdc + "/call");
}

// Then pay and call the one you want
const { data } = await buyer.pay(`${svc.hostedUrl}/enrich?domain=stripe.com`);

// Add to your claude_desktop_config.json or mcp settings:
{
  "mcpServers": {
    "obol": {
      "command": "node",
      "args": ["packages/obol-mcp/dist/index.js"],
      "env": {
        "OBOL_AGENT_KEY": "0xYourAgentPrivateKey"
      }
    }
  }
}

Buyer dashboard — "Deposit to Gateway":
  Arc wallet → Circle Gateway unified balance
  Used to fund the agent's spending pool.
  Requires PIN confirmation (UCW).

Buyer dashboard — "Bridge →" on a chain card:
  Any chain → Any other chain
  Uses Circle CCTP behind the scenes.
  ~30 seconds to arrive.

Buyer dashboard — "Withdraw →" on Gateway balance card:
  Gateway balance → Any chain, any recipient address
  Pick destination network from dropdown (all 8 chains supported).

Seller dashboard — "Withdraw earnings":
  Your Arc wallet → Any address on any network
  Same cross-chain capability via CCTP.
  Enter recipient address manually.

# What an unpaid request looks like:
HTTP/1.1 402 Payment Required
X-Payment-Required: {
  "scheme": "circle-gateway",
  "network": "eip155:5042002",
  "maxAmountRequired": "2000",    // in USDC micro-units (6 decimals)
  "sellerAddress": "0xSeller...",
  "facilitatorUrl": "https://gateway-api-testnet.circle.com"
}

# The GatewayClient SDK reads this header, signs an off-chain EIP-3009
# authorization, submits to Circle Gateway, then retries the original
# request with a signed payment proof in the Authorization header.