Setup

​

Prerequisites

• Get allowlisted. Contact the Coinbase team to enable your CDP project for App2App. Then register your iOS App Attest identifier (teamID.bundleID) yourself in CDP Portal, under Payments → Onramp & Offramp → App2App iOS.
• Add your redirect host to the domain allowlist. In CDP Portal, under Payments → Onramp & Offramp, add the host of the redirectUrl you’ll use. See Security Requirements for supported formats. Requests with a redirectUrl host that isn’t allowlisted are rejected.
• Stand up a backend that holds a CDP API key. Minting the attestation challenge and the purchase challenge both require a CDP API-key JWT; the device only ever sees the challenge that comes back, never the key. See Build your backend.
• Use a physical iOS device. App Attest requires the Secure Enclave, which the iOS Simulator doesn’t have. This applies to sandbox testing too, not just production.
• Use a custom development build, not Expo Go. @coinbase/cdp-app-attest is a native module; Expo Go can’t load it. Build with expo run:ios, a custom dev client, or EAS Build.
• Enable the App Attest capability in Xcode (requires an Apple Developer Program account) with a deployment target of iOS 14+. See Apple’s DeviceCheck documentation and the App Attest setup guide for background on what this capability does.

​

The four API routes

POST /v2/onramp/mobile/attestation/challenges

{
  "challenge": "<base64url, unpadded>",
  "expiresAt": "<ISO-8601 timestamp>"
}

POST /v2/onramp/mobile/attestation/registrations

{
  "challenge": "<from the attestation challenge>",
  "ios": {
    "keyId": "<Apple keyId, standard base64>",
    "attestation": "<CBOR attestation object, base64>",
    "bundleId": "<e.g. com.your.app>"
  }
}

{
  "appId": "<teamID.bundleID — not a CDP project ID>",
  "keyId": "<same keyId>",
  "platform": "ios",
  "attestedAt": "<ISO-8601 timestamp>"
}

POST /v2/onramp/mobile/sessions/challenges

{
  "destinationAddress": "<wallet address>",
  "destinationNetwork": "base",
  "purchaseCurrency": "USDC",
  "paymentCurrency": "USD",
  "redirectUrl": "https://your-allowlisted-host/onramp-return",
  "paymentAmount": "25.00",
  "partnerUserRef": "<your user ID>"
}

{
  "challenge": "<base64url, unpadded>",
  "expiresAt": "<ISO-8601 timestamp>"
}

POST /v2/onramp/mobile/sessions

{
  "challenge": "<from the purchase challenge>",
  "ios": {
    "keyId": "<registered keyId, standard base64>",
    "assertion": "<assertion, base64>"
  }
}

{
  "session": {
    "onrampUrl": "https://coinbase.com/onramp?sessionToken=..."
  }
}

​

One-time setup

​

1. Install dependencies

npm install @coinbase/cdp-app-attest@latest @coinbase/cdp-react-native@latest

pnpm add @coinbase/cdp-app-attest@latest @coinbase/cdp-react-native@latest

yarn add @coinbase/cdp-app-attest@latest @coinbase/cdp-react-native@latest

• @coinbase/cdp-app-attest is required. It’s the native module that drives DCAppAttestService directly and is what this guide uses for the App Attest ceremony in Register each device and Start the purchase.
• @coinbase/cdp-react-native is optional, used only for its canOpenCoinbaseOnramp() and handleOnrampReturn() helpers (Detect the Coinbase app and Handle the return). This guide does not use its openCoinbaseOnramp() function.
• If you’re building a native iOS app without React Native, call DCAppAttestService directly wherever this guide shows a @coinbase/cdp-app-attest call, and canOpenURL directly for detection — the request/response shapes are identical.

​

2. Configure your iOS project

<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>production</string>

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>com.coinbase.cdp.onramp.v2</string>
  <string>com.coinbase.cdp.onramp</string>
</array>

​

3. Build your backend

import { generateJwt } from "@coinbase/cdp-sdk/auth";

async function mintChallenge(path: string, body?: unknown) {
  const token = await generateJwt({
    apiKeyId: process.env.CDP_API_KEY_ID!,
    apiKeySecret: process.env.CDP_API_KEY_SECRET!,
    requestMethod: "POST",
    requestHost: "api.cdp.coinbase.com",
    requestPath: `/platform${path}`,
    expiresIn: 120,
  });

  const res = await fetch(`https://api.cdp.coinbase.com/platform${path}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
  });
  return res.json();
}

// Used once per install, by "Register each device" below
app.post("/app2app/attestation-challenge", async (req, res) => {
  res.json(await mintChallenge("/v2/onramp/mobile/attestation/challenges"));
});

// Used on every purchase, by "Start the purchase" below
app.post("/app2app/purchase-challenge", async (req, res) => {
  res.json(await mintChallenge("/v2/onramp/mobile/sessions/challenges", req.body));
});

​

4. Register each device

function base64urlToBase64(value: string): string {
  let out = value.replace(/-/g, '+').replace(/_/g, '/');
  while (out.length % 4 !== 0) out += '=';
  return out;
}

import { attest, getOnrampRegisteredKeyId, confirmOnrampRegistration, clearOnrampAttestation } from '@coinbase/cdp-app-attest';

async function registerDevice(projectId: string) {
  if (await getOnrampRegisteredKeyId(projectId)) return; // already registered

  const { challenge } = await fetch('/app2app/attestation-challenge', { method: 'POST' }).then(r => r.json());

  const attestation = await attest(base64urlToBase64(challenge)); // -> { ios: { keyId, attestation, bundleId } }

  try {
    const registration = await fetch('/v2/onramp/mobile/attestation/registrations', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ challenge, ios: attestation.ios }),
    }).then(r => r.json());

    await confirmOnrampRegistration(projectId, registration.keyId);
  } catch (err) {
    await clearOnrampAttestation(projectId); // the key is already consumed; force a fresh one next time
    throw err;
  }
}

​

Every purchase

​

1. Detect the Coinbase app

import { canOpenCoinbaseOnramp } from '@coinbase/cdp-react-native';

const supported = await canOpenCoinbaseOnramp();
if (supported) {
  // show "Pay with Coinbase" button
} else {
  // fall back to Coinbase-hosted Onramp
}

canOpenURL("com.coinbase.cdp.onramp.v2://")
canOpenURL("com.coinbase.cdp.onramp://")

​

2. Start the purchase

import { createAssertion } from '@coinbase/cdp-app-attest';
import { Linking } from 'react-native';

async function startPurchase(order: PurchaseOrder) {
  const { challenge } = await fetch('/app2app/purchase-challenge', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(order), // no projectId — the backend's JWT carries it
  }).then(r => r.json());

  const assertion = await createAssertion(base64urlToBase64(challenge)); // -> { ios: { keyId, assertion } }

  const { session } = await fetch('/v2/onramp/mobile/sessions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ challenge, ios: assertion.ios }),
  }).then(r => r.json());

  await Linking.openURL(session.onrampUrl);
}

• challenge expires 5 minutes after it’s minted. If the session call returns stale_attestation, mint a fresh purchase challenge and retry with a new assertion; keep the same registered device key.
• The session call is idempotent on the challenge: if you don’t receive a response (for example, due to a dropped connection), retry it. Retrying an already-attested challenge returns the same URL rather than an error.
• The returned onrampUrl’s session token expires 15 minutes after it’s issued.

import { clearOnrampAttestation } from '@coinbase/cdp-app-attest';

try {
  await startPurchase(order);
} catch (err) {
  if (!isAttestationKeyError(err)) throw err;
  await clearOnrampAttestation(projectId);
  await registerDevice(projectId);
  await startPurchase(order); // retry once
}

​

3. Handle the return

import { handleOnrampReturn } from '@coinbase/cdp-react-native';
import * as Linking from 'expo-linking';

Linking.addEventListener('url', ({ url }) => {
  if (url.includes('onramp-return')) {
    handleOnrampReturn({ returnUrl: url }).catch(console.error);
  }
});

• handshakeNonce is only included on success.
• error and cancelled carry no detail about what went wrong or how far the user got. If you need to distinguish “not eligible” from “transaction failed,” you can’t do it from the redirect alone.
• If the user isn’t already signed in to Coinbase, they’ll sign in or create an account (and complete KYC if they’re new) before the purchase continues, all inside the Coinbase app, with no separate step needed from you.

​

4. Confirm the transaction

1. Follow the Onramp & Offramp Webhooks guide to create a webhook subscription for onramp.transaction.success (and .created / .updated / .failed if you want the intermediate states).
2. Match incoming events to your user with partnerUserRef; it’s included in every payload.
3. Treat a transaction as settled only when the event is onramp.transaction.success (or, if you’re inspecting the payload directly, status is ONRAMP_TRANSACTION_STATUS_SUCCESS).
4. App2App transactions include isAppToApp: true, so you can distinguish them from other purchase flows if needed.

GET https://api.developer.coinbase.com/onramp/v1/buy/user/{partnerUserRef}/transactions

• Match transactions using partnerUserRef plus txHash, purchase currency, and amount. The redirect’s transactionId doesn’t match the transactionId returned by this endpoint: they’re generated by different systems for the same purchase, so don’t use them to join records, even though the redirect’s value now looks like a real ID on a live purchase rather than a placeholder.
• Sandbox (dry-run) sessions are the exception to both of the above; see Sandbox testing.

​

Sandbox testing

• Keep the sandbox- prefix until you’re ready to move real funds; it’s independent of which App Attest environment you’re using.

​

Errors

​

What to read next

• FAQ: Common questions from partners integrating App2App
• Onramp & Offramp Webhooks: Full webhook setup and payload reference
• Security Requirements: Domain allowlist requirements for your redirect URL
• onramp-v2-mobile-demo: Full reference implementation of the client and backend pieces in this guide