Quickstart

Prerequisites

• Node 20+ (or Python 3.11+, Go 1.22+ — pick your SDK)
• A free OpenUSDC Cloud workspace (optional for the local sandbox)
• USDC on Base, Solana, Arbitrum, or Optimism — only required for step 4

1. Install the CLI

npm i -g @openusdc/cli
openusdc --version
# openusdc cli 0.6.2

2. Run the gateway in sandbox mode

The sandbox is a deterministic in-process chain simulator. No faucet, no network, no flakes — perfect for tests and the first five minutes of your life with OpenUSDC.

openusdc dev \
  --chain sandbox \
  --route POST:/echo \
  --price "0.0010 USDC" \
  --pay-to 0xDEADBEEFcafe

The gateway is now listening on http://localhost:7202 and will charge 0.001 USDC per call on the /echo route.

3. Make a payment

From the CLI:

openusdc fetch POST http://localhost:7202/echo \
  --max-spend "0.01 USDC" \
  --body '{"prompt":"hello"}'

# → 200 OK
# → x-openusdc-receipt: ousdc_3f9a... (verified)
# → cost: 0.0010 USDC · chain: sandbox

Or from Node:

import { openusdc } from "@openusdc/sdk";

const data = await openusdc.fetch(
  "http://localhost:7202/echo",
  { method: "POST", body: { prompt: "hello" }, maxSpend: "0.01 USDC" }
);

console.log(data);          // → { echoed: "hello" }
console.log(data.$receipt); // → signed payment receipt

4. Move to Base (or Solana, Arbitrum, Optimism)

Swap the --chain sandbox flag for --chain base and point the SDK at a wallet you control. The simplest path is to provision a Coinbase MPC wallet and reference it by ID:

openusdc dev \
  --chain base \
  --route POST:/echo \
  --price "0.0040 USDC" \
  --pay-to 0x9A3f...c821

# In the agent / client
const wallet = openusdc.wallet({
  chain: "base",
  signer: { kind: "coinbase-mpc", id: "wallet_42" },
});

await wallet.fetch("http://localhost:7202/echo", { ... });

The first time you settle on Base, the SDK prompts you to confirm spend caps and counterparty allow-lists. You can also bake these into a policy.json committed to your repo.

5. Connect to Cloud (optional)

openusdc login
openusdc workspace use acme-staging
openusdc gateway link --workspace acme-staging

From this point on, every settlement is mirrored into your Cloud workspace and shows up in the dashboard within ~200ms. You can stop and start the gateway freely — the ledger is consistent.

Architecture

OpenUSDC has three logical pieces. They are independently deployable, but they speak the same wire format.

1. SDK — runs in the agent process. Wraps a wallet, signs x402 payment headers, retries 402 responses, returns structured receipts.
2. Gateway — runs in front of the API server. Enforces pricing, validates payment headers, settles on-chain, forwards the request, and writes a ledger entry.
3. Cloud control plane — optional. Aggregates ledger entries, hosts the dashboard, fans out webhooks, drives alerts, and exports data warehouse-ready files.

All three components are open-source. Cloud is the only piece we also offer as a managed SaaS. tracing is enabled by default; traces propagate W3C TraceContext from the agent through the gateway and into your handler.