Migrate from Coinbase x402

Drop-in middleware change. ~30 min of dev work. Production-safe rollback path included.

Honest take: should you actually migrate?

Coinbase's x402 facilitator is cheap and reliable. We're not telling you to rip it out. Here's the truth table:

Most teams end up running both: Coinbase for high-volume US tx, LemonCake for JP buyers + MPP-signed agents. That's fine — facilitators are commodity at the spec level.

The actual code change

x402 is one spec; only the facilitator URL and (optionally) the API key differ. Here's the typical diff in a Node/Express handler:

import { paymentMiddleware } from "@coinbase/x402";
+ import { paymentMiddleware } from "@lemon-cake/x402-server";

  app.use(paymentMiddleware({
-   facilitator: "https://api.cdp.coinbase.com/v2/x402",
+   facilitator: "https://lemoncake.xyz/api/x402",
    network:     "base",
    receiver:    process.env.RECEIVER_WALLET,
-   apiKey:      process.env.CDP_API_KEY,
+   apiKey:      process.env.LEMON_CAKE_API_KEY,    // free tier: no key required
+   mpp:         true,                              // accept Stripe MPP-signed payments
  }));

That's it. The receiver wallet is unchanged, the network is unchanged, the per-call price you set is unchanged. Buyers' permits don't need to be re-signed — the spender address on existing Coinbase permits already targets the buyer's wallet, not Coinbase's facilitator.

Production cutover (gradual)

1. Day 0: drop a feature flag into your handler that routes 1% of traffic to LemonCake facilitator. Compare settle latency + error rate side-by-side in your logs.
2. Day 1-3: bump to 10%, monitor edge cases (refunds, replay attempts). Most surprises show up at this ratio.
3. Day 4-7: bump to 50%. Validate the free-tier counter on your dashboard is tracking the right number of settled tx.
4. Day 8: flip to 100%. Leave the Coinbase code path in the feature flag for one more week as the rollback escape hatch.
5. Day 15:delete the Coinbase code path. You're done.

Rollback script

If anything goes sideways, flip one env var. The facilitator URL is the only routing point.

# rollback to Coinbase in < 1 minute
$ heroku config:set X402_FACILITATOR=https://api.cdp.coinbase.com/v2/x402
$ heroku restart

Why the free tier is real (not bait)

We sponsor gas on Base for the first 1,000 settled tx / month per project. Above that, $0.005/tx pay-as-you-go. We can afford this because (a) we batch settle on Base where gas is <$0.0001/tx, and (b) the conversion rate from free → Pro for projects that genuinely use 1k tx is high enough to subsidize the burn.

If your project hits the 1k cap, we email you at 80% and 100%. No surprise rate limiting, no service interruption — overage routes to the $0.005/tx bucket automatically.

What "MPP-compatible" actually means

After Stripe Sessions 2026, the Machine Payments Protocol (MPP) became the de-facto agent-payment signing spec for the Stripe / Tempo / Privy stack. Coinbase's facilitator does not accept MPP-signed payments today — it's x402-spec-only.

LemonCake's facilitator accepts both:

• x402 HTTP 402 + ERC-2612 permit (Coinbase-style)
• Stripe MPP-signed payment intents settling on Base/USDC

For you: one facilitator URL handles both flavors. For buyers: their existing Privy / Stripe MPP signature continues to work, no re-sign needed.

If you want us to do this for you

The migration sprint is $5,000 flat, 2 weeks — includes the PR into your repo, the cutover plan, the rollback script, and 30 days of post-launch fixes. Email contact@aievid.com and we'll send a written scope inside 24h.

Updated 2026-05-26. Pricing on Coinbase x402 facilitator pulled from docs.cdp.coinbase.com/x402. We update this monthly.