Migrating from x402 / MPP to an API key

The OneSource REST API is discoverable through a number of channels (AgenticMarket / CDP Bazaar, AgentCash, x402scan, mppScan, the MCP Registry, Glama, npm) and any agent that found you there can call the API today by signing per-request payments in USDC. That's a great fit for low-volume or experimental traffic.

For production-scale workloads a direct Bearer API key is usually cheaper and simpler: predictable monthly billing through Stripe, configurable rate limits, no per-call wallet settlement. This guide covers what changes (and what doesn't) when you migrate.

What stays the same

• Base URL. Still https://api.onesource.io. No DNS change.
• Endpoints. Identical paths, parameters, response shapes. All endpoints in the API Reference work as before.
• Response envelope. Same { data, error, meta } shape on success and failure.

The wire format is exactly the same. Only the auth header changes.

What changes

Auth

Before (x402 or MPP)	After (Bearer API key)
Sign each call (USDC on Base for x402, or USDC.e / pathUSD on Tempo for MPP); client handles 402 → sign → retry	Authorization: Bearer sk_… once, every call
Wallet private key in your agent's env	API key from the OneSource dashboard
Per-call USDC settlement on Base or Tempo	Monthly billing through Stripe

Pricing model

Per-call charges range $0.001 – $0.010 USDC depending on endpoint. The Bearer-key subscription bundles that into a per-month fee with a request quota and rate cap; exact numbers depend on the plan you pick at signup. For sustained traffic the monthly plan is usually materially cheaper than per-call. For low or bursty volume, x402 or MPP may still be more economical; see the pricing comparison below.

Rate limits

	x402 / MPP	Bearer API key
Rate cap	None, only your wallet balance limits you	Set by your plan, account-wide (shared across all your keys)
Monthly quota	None	Set by your plan, account-wide

If your traffic has sustained spikes above your plan's rate cap, plan for backoff. The Developer plan is currently the only subscription tier, so for more capacity, route the overflow to x402 / MPP (which has no quota) or run a second subscription under a different email.

Discovery

The OneSource REST API stays listed on its existing discovery channels (AgenticMarket / CDP Bazaar, AgentCash, x402scan, mppScan, the MCP Registry, Glama, npm) regardless of which auth path your own traffic uses. The service still emits x402 challenges in parallel with MPP and accepts Bearer keys, so third-party agents that find OneSource through any of those channels keep working without code changes.

Migration path

1. Sign up for an API key

Follow Sign up for an API key at app.onesource.io/signup: create your account, confirm your email, and subscribe to the Developer plan. Then create a key under API Keys and copy its sk_… value from the creation dialog right away, it's shown only once.

2. Read the key into your app

Retrieve your API key covers dashboard, env-var, and .env patterns. Standard practice: store as ONESOURCE_API_KEY in your hosting platform's secret store; read once at startup; cache in memory.

3. Swap auth in your client

If you were using @x402/fetch:

- import { wrapFetchWithPayment } from '@x402/fetch';
- import { privateKeyToAccount } from 'viem/accounts';
-
- const account = privateKeyToAccount(process.env.X402_PRIVATE_KEY);
- const skillsFetch = wrapFetchWithPayment(fetch, { account, chain: 'base' });
+ const skillsFetch = (url: string, init: RequestInit = {}) =>
+   fetch(url, {
+     ...init,
+     headers: { ...init.headers, Authorization: `Bearer ${process.env.ONESOURCE_API_KEY}` },
+   });

  const res = await skillsFetch('https://api.onesource.io/api/chain/network-info');

If you were using AgentCash MCP or an MPP-aware fetcher:

  {
    "mcpServers": {
      "agentcash": { "command": "npx", "args": ["-y", "agentcash-mcp"] }
+     ,
+     "onesource": {
+       "command": "npx",
+       "args": ["-y", "@one-source/mcp@latest"],
+       "env": { "ONESOURCE_API_KEY": "sk_…" }
+     }
    }
  }

The OneSource MCP Server gives the agent direct, key-authenticated access; AgentCash and other wallet-paid clients can stay for non-OneSource x402 endpoints.

4. Update error handling

With Bearer-key auth the failure surface shifts from x402 / MPP payment errors to gateway auth errors plus envelope errors from the service. The gateway returns a flat {error, message} shape for auth/routing problems (invalid_token, api_key_required, plan_required) while the OneSource service still returns the canonical {data, error, meta} envelope for parameter validation and on-chain failures. See Error codes for the full catalog and a normalizer that handles both shapes.

If your retry logic only handles the 402 → sign → retry loop, replace it with a 5xx backoff path. Rate-limit headers (X-RateLimit-*) are advisory today, so back off proactively when Remaining trends low rather than waiting for a 429.

5. Smoke test

Run the unified verify call from First request once with the new key. Compare to your existing x402 / MPP logs: data should be byte-equal for the same input.

Pricing comparison

A worked example for a workload making 30 calls/minute (~43,200 calls/day, ~1.3M calls/month), assuming an even mix of paid endpoints:

Path	Cost basis	Approximate monthly cost
x402 (avg $0.004/call)	1.3M × $0.004 + Base settlement gas	~$5,200 + gas
MPP (avg $0.004/call, lower gas)	1.3M × $0.004 + Tempo settlement	~$5,200 + minimal gas
Bearer API key	Fixed monthly plan covering the request volume	plan price

For sustained > ~$1K/month equivalents, the monthly plan typically wins. Below that, x402 or MPP can be cheaper and gives you no rate cap.

Running both in parallel

Nothing forces you to pick one. The OneSource service accepts Bearer keys, x402 signatures, and MPP credentials in parallel; they coexist on the same endpoints. Common dual-mode patterns:

• API key as primary, wallet-paid as overflow. Your default client uses the Bearer key; when X-RateLimit-Remaining drops near zero (or, once enforcement lands, when you see a 429), fall back to an x402- or MPP-signed call for that request. Plan for two-or-three orders-of-magnitude burst capacity without paying for the headroom every month.
• API key for production paths, wallet-paid for experiments. Your prod service uses the Bearer key; ad-hoc scripts or one-off agents pay per call.

Both paths are first-class and tested.

Keeping your discovery footprint visible

If you actively rely on discovery (agents finding OneSource through AgenticMarket / CDP Bazaar, AgentCash, x402scan, mppScan, the MCP Registry, Glama, or npm) those listings remain live and unaffected by which auth path your own traffic uses. Even if you switch your own calls to Bearer-key auth, third-party agents discovering you through any wallet-paid channel will continue to pay-per-call via x402 or MPP without disruption.