Skip to main content
POST
/
v2
/
onramp
/
sessions
Create an onramp session
curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/onramp/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "purchaseCurrency": "USDC",
  "destinationNetwork": "base",
  "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "paymentAmount": "100.00",
  "purchaseAmount": "10.000000",
  "paymentCurrency": "USD",
  "paymentMethod": "CARD",
  "country": "US",
  "subdivision": "NY",
  "redirectUrl": "https://example.com/success",
  "clientIp": "127.0.0.1",
  "partnerUserRef": "user-1234"
}
'
{
  "session": {
    "onrampUrl": "https://pay.coinbase.com/buy?sessionToken=abc123F"
  },
  "quote": {
    "paymentTotal": "100.75",
    "paymentSubtotal": "100.00",
    "paymentCurrency": "USD",
    "purchaseAmount": "100.000000",
    "purchaseCurrency": "USDC",
    "destinationNetwork": "base",
    "fees": [
      {
        "type": "FEE_TYPE_EXCHANGE",
        "amount": "0.5",
        "currency": "USD"
      },
      {
        "type": "FEE_TYPE_NETWORK",
        "amount": "0.25",
        "currency": "USD"
      }
    ],
    "exchangeRate": "1"
  }
}

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
​
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:

"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

​
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"

​
redirectUrl
string<uri>

URI to redirect the user to when they successfully complete a transaction. This URI will be embedded in the returned onramp URI as a query parameter.

Required string length: 5 - 2048
Example:

"https://example.com/success"

​
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 with Onramp User Transactions API to retrieve all transactions created by the user.

Example:

"user-1234"

Response

Onramp session created successfully.

​
session
object
required

An onramp session containing a ready-to-use onramp URL.

Example:
{
  "onrampUrl": "https://pay.coinbase.com/buy?sessionToken=abc123F"
}
​
quote
object

Quote information with pricing details for the crypto purchase.

Example:
{
  "paymentTotal": "100.75",
  "paymentSubtotal": "100.00",
  "paymentCurrency": "USD",
  "purchaseAmount": "100.000000",
  "purchaseCurrency": "USDC",
  "destinationNetwork": "base",
  "fees": [
    {
      "type": "FEE_TYPE_EXCHANGE",
      "amount": "0.5",
      "currency": "USD"
    },
    {
      "type": "FEE_TYPE_NETWORK",
      "amount": "0.25",
      "currency": "USD"
    }
  ],
  "exchangeRate": "1"
}