Coinbase Onramp

Three integration depths (URL vs components vs API)

Coinbase Onramp is the same product exposed at three levels of control, all sharing the session-token init. You trade UI control for integration effort.

• Hosted Onramp URL — generateOnrampURL / getOnrampBuyUrl returns a Coinbase-hosted buy/sell page; least code, least UI control. Good for a 'Buy crypto' button.
• OnchainKit Fund components — <FundButton /> and <FundCard /> from @coinbase/onchainkit/fund embed the flow inside a React app; FundButton auto-routes EOA → Onramp vs Coinbase Smart Wallet → fund flow (Magic Spend).
• Headless REST API — buy/options → buy/quote → orders → transaction-status lets you build a fully custom UI (e.g. native mobile) while Coinbase still owns KYC, payments, and settlement.

Session-token auth (mandatory since Jul 31, 2025)

Coinbase moved from passing wallet addresses/appId as raw query params to a secure-init model. Every Onramp/Offramp URL must now be initialized with a single-use session token minted server-side.

• Your backend signs a JWT with the CDP API key and POSTs to the Session Token API (api.developer.coinbase.com/onramp/v1/token).
• The returned token is single-use and short-lived (~5 min [verify]); call it once per new user session.
• With a token set, you omit appId/addresses/assets from the URL — they're bound into the token, reducing tampering and leaking of wallet data.
• Consequence: no purely client-side integration is possible; a server route is part of the minimum architecture.

USDC / Base economics & the zero-fee play

The strategic hook is a zero-fee on/off-ramp for USDC (especially on Base). Coinbase subsidizes the conversion to grow USDC float, custody, and Base activity.

• USDC ramp can be fee-free (approval-gated) vs. ~1–4.5% card fees at consumer ramps — a direct shot at MoonPay/Transak pricing.
• Base (Coinbase's own L2) is the cheapest settlement target, so the zero-fee path doubles as Base distribution.
• Guest checkout (debit card / Apple Pay, no Coinbase account) lowers the funnel further, within per-region weekly caps (~$500/wk, $5 min in the US [verify]).
• Revenue is the spread/fee on non-USDC and card-funded purchases; USDC is the loss-leader.

Risk & strategic steering

• Ecosystem lock-in: the cheapest, smoothest path funnels users into USDC + Coinbase custody + Base rather than arbitrary chains/assets.
• Subsidy dependence: the headline zero-fee economics rely on Coinbase continuing to absorb the cost.
• Regulatory upside/constraint: a public, US-regulated issuer brings trust but also region-by-region limits and KYC gating that pure-crypto rivals can sidestep.
• Operational: treat the Transaction Status API (not the client redirect) as the source of truth for order completion.

Architecture

Coinbase Onramp sits between Coinbase's regulated exchange/custody and the destination chain. Unlike a publishable-key widget, it requires a server: your backend signs a JWT with your CDP API key, calls the Session Token API to mint a single-use token, then hands that token to the client. The client either redirects to a hosted Coinbase buy/sell URL, renders an OnchainKit Fund component, or — in the headless model — your own UI calls the REST quote/order endpoints. Coinbase owns KYC, payment acceptance, fraud, liquidity, and the on-chain payout; you own the wallet address and order correlation. USDC settled on Base is the zero-fee path.

Integration shape

Three tiers: (1) Hosted — generateOnrampURL / getOnrampBuyUrl builds a Coinbase-hosted URL initialized with the session token. (2) Components — @coinbase/onchainkit/fund exports <FundButton /> (opens the right flow for EOA vs Coinbase Smart Wallet) and <FundCard /> (an embedded fiat→crypto card). (3) Headless — the Onramp REST API (buy options, buy quote, order/session, transaction status) for a fully custom UI. All three require the server-minted session token.

API surface

POST /onramp/v1/token

Session Token API — mint a single-use token (server-side, JWT-authed with your CDP key). Required to init every Onramp/Offramp URL since Jul 31, 2025; token expires ~5 min. [verify expiry]

getOnrampBuyUrl(...) / generateOnrampURL(...)

Build the hosted one-click-buy URL. Key params: sessionToken, defaultNetwork, defaultAsset, presetFiatAmount, fiatCurrency, redirectUrl, partnerUserRef.

GET /onramp/v1/buy/options

Discover supported fiat currencies, payment methods, and crypto assets/networks available to a given country before quoting.

POST /onramp/v1/buy/quote

Get a binding buy quote (amount in, fees, amount out) for a fiat→crypto purchase; feeds the headless flow.

POST /platform/v2/onramp/orders

Create an onramp order/session; supports payment methods incl. GUEST_CHECKOUT_APPLE_PAY (renders the Apple Pay button on an allow-listed domain). [verify path]

<FundButton /> · @coinbase/onchainkit/fund

Drop-in React button; auto-detects EOA vs Coinbase Smart Wallet and routes to Onramp or the Smart Wallet fund flow (Magic Spend). Accepts a custom Onramp URL.

<FundCard /> · @coinbase/onchainkit/fund

Embedded fiat→crypto card for self-custody apps — amount input, payment-method select, and quotes inline, in a few lines.

Transaction Status API

Poll real-time + historical order status (treat this, not the client, as source of truth).

Minimal integration

Mint a session token on the server, then render an OnchainKit FundButton on the client.

// --- server: mint a single-use session token (required since Jul 31, 2025) ---
// JWT is signed with your CDP API key (see @coinbase/cdp-sdk / generateJwt).
const res = await fetch('https://api.developer.coinbase.com/onramp/v1/token', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${cdpJwt}`,            // JWT from your CDP API key
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    addresses: [{ address: userWallet, blockchains: ['base'] }],
    assets: ['USDC'],                                // USDC on Base = zero-fee path
  }),
});
const { token: sessionToken } = await res.json();    // single-use, ~5-min TTL

// --- client (React): build the URL + drop in the component ---
import { FundButton, getOnrampBuyUrl } from '@coinbase/onchainkit/fund';

const onrampUrl = getOnrampBuyUrl({
  sessionToken,                  // no raw addresses/appId needed once token is set
  presetFiatAmount: 50,
  fiatCurrency: 'USD',
  redirectUrl: 'https://rails.app/done',
});

export function BuyUsdc() {
  return <FundButton fundingUrl={onrampUrl} />;
}

Build notes

• Session token is server-only: signing the JWT needs your CDP API secret, so a backend route is mandatory — there is no pure client-side embed.
• When a session token is supplied you no longer pass appId, addresses, or assets in the URL — they're bound into the token.
• For Apple Pay guest checkout (GUEST_CHECKOUT_APPLE_PAY) the Apple Pay button must render on a domain you've allow-listed with Coinbase.
• Zero-fee USDC is approval-gated — apply for access; default/non-USDC methods still carry a spread/fee.
• [verify against current docs — endpoint paths (v1 vs platform/v2), token TTL, and guest-checkout caps evolve]