Skip to main content

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 by signing per-request payments in USDC. That suits low-volume and experimental traffic.

For production-scale workloads a direct Bearer API key is usually cheaper and simpler: predictable monthly billing through Stripe, a bundled request allowance, 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 → retryAuthorization: Bearer sk_… once, every call
Wallet private key in your agent's envAPI key from the OneSource dashboard
Per-call USDC settlement on Base or TempoMonthly billing through Stripe

Pricing model​

Per-call charges range $0.001 to $0.010 USDC depending on endpoint. The Bearer-key subscription bundles that into a single per-month fee covering a request allowance. There is one plan, so there's nothing to size or choose at signup. For sustained traffic it is usually materially cheaper than per-call. For low volume, x402 or MPP may still be more economical; see the cost comparison below.

Limits​

x402 / MPPBearer API key
ConcurrencyUnlimited; your wallet balance is the only boundUnlimited
Request volumeUnmetered, you pay per callFixed daily and monthly quota, account-wide (shared across all your keys)

What a key changes is how volume is paid for: a fixed monthly bill in place of per-call settlement, against a daily and monthly quota reported on every response via X-Quota-* headers. See Usage quotas.

If that volume isn't enough, contact support (daily and monthly caps can be raised on an individual account) or route the overflow to x402 / MPP, which has no quota.

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. 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 { x402Client, wrapFetchWithPayment } from '@x402/fetch';
- import { registerExactEvmScheme } from '@x402/evm/exact/client';
- import { privateKeyToAccount } from 'viem/accounts';
-
- const account = privateKeyToAccount(process.env.X402_PRIVATE_KEY);
- const client = new x402Client();
- registerExactEvmScheme(client, { signer: account });
- const apiFetch = wrapFetchWithPayment(fetch, client);
+ const apiFetch = (url: string, init: RequestInit = {}) =>
+   fetch(url, {
+     ...init,
+     headers: { ...init.headers, Authorization: `Bearer ${process.env.ONESOURCE_API_KEY}` },
+   });

  const res = await apiFetch('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 plus a 429 branch. Read the X-Quota-Day-Used / X-Quota-Day-Limit headers on the success path and slow down before you hit the wall, rather than discovering it as a rejection.

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.

Cost comparison​

The choice comes down to cost per call.

Wallet-paid calls cost $0.001 to $0.010 each depending on the endpoint. Across the 25 paid endpoints the mean is about $0.0043, though your figure depends entirely on your mix: the three cheapest endpoints (block-number, chain-id, network-info) are $0.001, while erc721-tokens, nft-metadata, and tx/ are $0.008 and pending is $0.010. Live per-endpoint prices are at /api/pricing and on each operation's API Reference page.

Monthly x402 / MPP spend at a few volumes, before settlement gas:

Calls / monthAll cheapest ($0.001)Mean mix ($0.0043)All dearest ($0.010)
5,000$5$22$50
25,000$25$108$250
250,000$250$1,080$2,500
2,000,000$2,000$8,640$20,000

The plan wins as soon as your wallet-paid spend would exceed the plan's monthly price. Compare the relevant row above against the price shown at app.onesource.io. Settlement gas pushes the crossover a little further in the plan's favor (Base for x402, materially less on Tempo for MPP, less again if you use batch settlement), but it is a small correction next to the per-call charge.

For most endpoint mixes that crossover lands in the low thousands of calls per month. Past it the plan's advantage compounds quickly: a workload doing 250,000 calls a month of mixed endpoints is comparing roughly a thousand dollars of wallet spend against one flat monthly fee.

Two things that arithmetic doesn't capture:

  • The plan is bounded and the wallet is not. The plan stops at its monthly and daily quota (see Usage quotas). Above the cap you are contacting support or sending overflow to x402 anyway, so at very high volume the honest answer is "both", not "the plan".
  • Some reasons to migrate aren't about price at all. A key means no wallet or private key in your runtime, an invoiced monthly charge your finance team can process, and a procurement path. Those hold whatever the arithmetic says, and they are the things per-call rails structurally cannot offer.

Below the crossover, wallet-paid is the better choice: cheaper, no volume ceiling, and no signup at all.

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-Quota-Day-Used approaches X-Quota-Day-Limit (or you get a 429 carrying daily_limit_exceeded / monthly_limit_exceeded), fall back to an x402- or MPP-signed call for that request. You buy the steady-state volume and pay per call only for the tail above it.
  • 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.

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.