Create an onramp mobile challenge

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "purchaseCurrency": "USDC",
  "destinationNetwork": "base",
  "destinationAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "redirectUrl": "https://example.com/success",
  "paymentAmount": "100.00",
  "purchaseAmount": "10.000000",
  "paymentCurrency": "USD",
  "paymentMethod": "CARD",
  "country": "US",
  "subdivision": "NY",
  "clientIp": "127.0.0.1",
  "partnerUserRef": "user-1234"
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges"

payload = {
    "purchaseCurrency": "USDC",
    "destinationNetwork": "base",
    "destinationAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "redirectUrl": "https://example.com/success",
    "paymentAmount": "100.00",
    "purchaseAmount": "10.000000",
    "paymentCurrency": "USD",
    "paymentMethod": "CARD",
    "country": "US",
    "subdivision": "NY",
    "clientIp": "127.0.0.1",
    "partnerUserRef": "user-1234"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    purchaseCurrency: 'USDC',
    destinationNetwork: 'base',
    destinationAddress: '0x1234567890abcdef1234567890abcdef12345678',
    redirectUrl: 'https://example.com/success',
    paymentAmount: '100.00',
    purchaseAmount: '10.000000',
    paymentCurrency: 'USD',
    paymentMethod: 'CARD',
    country: 'US',
    subdivision: 'NY',
    clientIp: '127.0.0.1',
    partnerUserRef: 'user-1234'
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'purchaseCurrency' => 'USDC',
    'destinationNetwork' => 'base',
    'destinationAddress' => '0x1234567890abcdef1234567890abcdef12345678',
    'redirectUrl' => 'https://example.com/success',
    'paymentAmount' => '100.00',
    'purchaseAmount' => '10.000000',
    'paymentCurrency' => 'USD',
    'paymentMethod' => 'CARD',
    'country' => 'US',
    'subdivision' => 'NY',
    'clientIp' => '127.0.0.1',
    'partnerUserRef' => 'user-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges"

	payload := strings.NewReader("{\n  \"purchaseCurrency\": \"USDC\",\n  \"destinationNetwork\": \"base\",\n  \"destinationAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"redirectUrl\": \"https://example.com/success\",\n  \"paymentAmount\": \"100.00\",\n  \"purchaseAmount\": \"10.000000\",\n  \"paymentCurrency\": \"USD\",\n  \"paymentMethod\": \"CARD\",\n  \"country\": \"US\",\n  \"subdivision\": \"NY\",\n  \"clientIp\": \"127.0.0.1\",\n  \"partnerUserRef\": \"user-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"purchaseCurrency\": \"USDC\",\n  \"destinationNetwork\": \"base\",\n  \"destinationAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"redirectUrl\": \"https://example.com/success\",\n  \"paymentAmount\": \"100.00\",\n  \"purchaseAmount\": \"10.000000\",\n  \"paymentCurrency\": \"USD\",\n  \"paymentMethod\": \"CARD\",\n  \"country\": \"US\",\n  \"subdivision\": \"NY\",\n  \"clientIp\": \"127.0.0.1\",\n  \"partnerUserRef\": \"user-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"purchaseCurrency\": \"USDC\",\n  \"destinationNetwork\": \"base\",\n  \"destinationAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"redirectUrl\": \"https://example.com/success\",\n  \"paymentAmount\": \"100.00\",\n  \"purchaseAmount\": \"10.000000\",\n  \"paymentCurrency\": \"USD\",\n  \"paymentMethod\": \"CARD\",\n  \"country\": \"US\",\n  \"subdivision\": \"NY\",\n  \"clientIp\": \"127.0.0.1\",\n  \"partnerUserRef\": \"user-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "challenge": "MWYwNWQwODktZTZlYy02OTdlLTgzZTYtMTI3NzcyOWJhNjM3",
  "expiresAt": "2025-04-24T00:05:00Z"
}

Onramp (App2App)

Create an onramp mobile challenge

Issues a challenge for initiating an onramp flow from a partner mobile app. Authenticate this request from the partner backend with a CDP API key; do not embed the API key in the mobile client. The project is identified by the API key JWT.

Pass the challenge to the mobile app. The app signs it using platform attestation (iOS App Attest or Android Play Integrity) and submits it to the Create Onramp Mobile Session endpoint without CDP API key authentication to obtain a ready-to-use onramp URL. The redirectUrl is required so the Coinbase app knows where to return the user after completing or dismissing the transaction.

POST

onramp

mobile

sessions

challenges

Create an onramp mobile challenge

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "purchaseCurrency": "USDC",
  "destinationNetwork": "base",
  "destinationAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "redirectUrl": "https://example.com/success",
  "paymentAmount": "100.00",
  "purchaseAmount": "10.000000",
  "paymentCurrency": "USD",
  "paymentMethod": "CARD",
  "country": "US",
  "subdivision": "NY",
  "clientIp": "127.0.0.1",
  "partnerUserRef": "user-1234"
}
'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges"

payload = {
    "purchaseCurrency": "USDC",
    "destinationNetwork": "base",
    "destinationAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "redirectUrl": "https://example.com/success",
    "paymentAmount": "100.00",
    "purchaseAmount": "10.000000",
    "paymentCurrency": "USD",
    "paymentMethod": "CARD",
    "country": "US",
    "subdivision": "NY",
    "clientIp": "127.0.0.1",
    "partnerUserRef": "user-1234"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    purchaseCurrency: 'USDC',
    destinationNetwork: 'base',
    destinationAddress: '0x1234567890abcdef1234567890abcdef12345678',
    redirectUrl: 'https://example.com/success',
    paymentAmount: '100.00',
    purchaseAmount: '10.000000',
    paymentCurrency: 'USD',
    paymentMethod: 'CARD',
    country: 'US',
    subdivision: 'NY',
    clientIp: '127.0.0.1',
    partnerUserRef: 'user-1234'
  })
};

fetch('https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'purchaseCurrency' => 'USDC',
    'destinationNetwork' => 'base',
    'destinationAddress' => '0x1234567890abcdef1234567890abcdef12345678',
    'redirectUrl' => 'https://example.com/success',
    'paymentAmount' => '100.00',
    'purchaseAmount' => '10.000000',
    'paymentCurrency' => 'USD',
    'paymentMethod' => 'CARD',
    'country' => 'US',
    'subdivision' => 'NY',
    'clientIp' => '127.0.0.1',
    'partnerUserRef' => 'user-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges"

	payload := strings.NewReader("{\n  \"purchaseCurrency\": \"USDC\",\n  \"destinationNetwork\": \"base\",\n  \"destinationAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"redirectUrl\": \"https://example.com/success\",\n  \"paymentAmount\": \"100.00\",\n  \"purchaseAmount\": \"10.000000\",\n  \"paymentCurrency\": \"USD\",\n  \"paymentMethod\": \"CARD\",\n  \"country\": \"US\",\n  \"subdivision\": \"NY\",\n  \"clientIp\": \"127.0.0.1\",\n  \"partnerUserRef\": \"user-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"purchaseCurrency\": \"USDC\",\n  \"destinationNetwork\": \"base\",\n  \"destinationAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"redirectUrl\": \"https://example.com/success\",\n  \"paymentAmount\": \"100.00\",\n  \"purchaseAmount\": \"10.000000\",\n  \"paymentCurrency\": \"USD\",\n  \"paymentMethod\": \"CARD\",\n  \"country\": \"US\",\n  \"subdivision\": \"NY\",\n  \"clientIp\": \"127.0.0.1\",\n  \"partnerUserRef\": \"user-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/onramp/mobile/sessions/challenges")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"purchaseCurrency\": \"USDC\",\n  \"destinationNetwork\": \"base\",\n  \"destinationAddress\": \"0x1234567890abcdef1234567890abcdef12345678\",\n  \"redirectUrl\": \"https://example.com/success\",\n  \"paymentAmount\": \"100.00\",\n  \"purchaseAmount\": \"10.000000\",\n  \"paymentCurrency\": \"USD\",\n  \"paymentMethod\": \"CARD\",\n  \"country\": \"US\",\n  \"subdivision\": \"NY\",\n  \"clientIp\": \"127.0.0.1\",\n  \"partnerUserRef\": \"user-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "challenge": "MWYwNWQwODktZTZlYy02OTdlLTgzZTYtMTI3NzcyOWJhNjM3",
  "expiresAt": "2025-04-24T00:05:00Z"
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Body

application/json

Common request parameters shared by Create Onramp Session and Create Onramp Mobile Challenge.

purchaseCurrency

string

required

The ticker (e.g. BTC, USDC, SOL) or the Coinbase UUID (e.g. d85dce9b-5b73-5c3c-8978-522ce1d1c1b4) of the crypto asset to be purchased.

Use the Onramp Buy Options API to discover the supported purchase currencies for your user's location.

Example:

"USDC"

destinationNetwork

string

required

The name of the crypto network the purchased currency will be sent on.

Use the Onramp Buy Options API to discover the supported networks for your user's location.

Example:

"base"

destinationAddress

string

required

The address the purchased crypto will be sent to.

Required string length: 1 - 128

Example:

"0x1234567890abcdef1234567890abcdef12345678"

redirectUrl

string<uri>

required

URI to redirect the user to after they complete or dismiss the transaction. Embedded in the returned onramp URL as a query parameter.

Required string length: 5 - 2048

Pattern: ^.*://.*$

Example:

"https://example.com/success"

paymentAmount

string

A string representing the amount of fiat the user wishes to pay in exchange for crypto. When using this parameter, the returned quote will be inclusive of fees i.e. the user will pay this exact amount of the payment currency.

Example:

"100.00"

purchaseAmount

string

A string representing the amount of crypto the user wishes to purchase. When using this parameter, the returned quote will be exclusive of fees i.e. the user will receive this exact amount of the purchase currency.

Example:

"10.000000"

paymentCurrency

string

The fiat currency to be converted to crypto.

Example:

"USD"

paymentMethod

enum<string>

The type of payment method used to generate the onramp quote.

Available options:

CARD,

ACH,

APPLE_PAY,

PAYPAL,

FIAT_WALLET,

CRYPTO_WALLET

Example:

"CARD"

country

string

The ISO 3166-1 two letter country code (e.g. US).

Example:

"US"

subdivision

string

The ISO 3166-2 two letter state code (e.g. NY). Only required for US.

Example:

"NY"

clientIp

string

The IP address of the end user requesting the onramp transaction.

Example:

"127.0.0.1"

partnerUserRef

string

A unique string that represents the user in your app. This can be used to link individual transactions together so you can retrieve the transaction history for your users. Prefix this string with "sandbox-" (e.g. "sandbox-user-1234") to perform a sandbox transaction which will allow you to test your integration without any real transfer of funds.

This value can be used with the Onramp User Transactions API to retrieve all transactions created by the user.

Example:

"user-1234"

Response

Onramp mobile challenge created successfully.

A server-issued challenge for platform attestation in an App2App onramp handoff.

challenge

string

required

An opaque server-issued token to be used with platform attestation (iOS App Attest or Android Play Integrity Standard). Treat it as an opaque string — do not attempt to parse its contents. Pass this value along with the attestation payload to the Create Onramp Mobile Session endpoint to complete the App2App handoff.

iOS: pass this value directly to DCAppAttestService.generateAssertion(keyId, clientDataHash: SHA256(challenge)).

Android: compute requestHash = base64url(SHA256(challenge)) and pass it to StandardIntegrityManager.requestToken(requestHash).

Required string length: 16 - 2048

Example:

"MWYwNWQwODktZTZlYy02OTdlLTgzZTYtMTI3NzcyOWJhNjM3"

expiresAt

string<date-time>

required

The time at which the challenge expires. Challenges are short-lived; submit the attestation to Create Onramp Mobile Session before this time or request a new challenge.

Example:

"2025-04-24T00:05:00Z"