Initializing Onramp

Getting an Onramp Session Token

Create a CDP API Key and follow these instructions on CDP API key authentication to make signed requests.

First call the Onramp Session Token API to obtain a token, then pass that token as the sessionToken query string parameter when generating the Onramp URL.

caution

The token expires after a short period of time and can only be used once. A new token must be obtained for every new session.

Method

POST

URL

https://api.developer.coinbase.com/onramp/v1/onramp/token

Request Parameters

The Onramp Session Token API is an RPC endpoint that accepts parameters as JSON in the request body.

Name	Type	Req	Description
destination_wallets	DestinationWallet[]	Y	Array of destination wallet addresses that the purchased crypto should be sent to. Each entry in this array is an object containing an address and an optional list of blockchains or asset IDs that the address supports.

Response Fields

The Onramp Session Token API returns a JSON response including the following fields.

Name	Description
token	A unique string that can be passed into the Pay SDK as the sessionToken parameter when manually generating a URL to initialize the onramp widget (the resulting URL will look like https://api.developer.coinbase.com/buy/select-asset?sessionToken=<token>&<other params>). This token is associated with the Destination Wallets and App ID header provided in the request. This token can only be used once per session.
channel_id	Not yet functional. Upcoming implementation: A socket.io channel ID that can be used to receive events from the Pay SDK while the customer goes through the transaction flow.

Example Request/Response

Request (cURL)

curl -X POST 'https://api.developer.coinbase.com/onramp/v1/token' \
  -H "Authorization: Bearer $JWT" \
  -d '{"destination_wallets": [{"address":"bc1qrdvlkt8rqsyj229thqzhm0q39edwdj2k7yps6x", "blockchains": ["bitcoin"]}]}'

Response 200 (JSON)

{
  "data": {
    "token": "ZWJlNDgwYmItNjBkMi00ZmFiLWIxYTQtMTM3MGI2YjJiNjFh",
    "channel_id": "MzMzNWMzNmItMDYxNy00MjliLTk1MDYtMWRhZTljYzIwNjRl",
  }
}

Generating the Onramp URL

If your application does not have a backend, or you do not wish to integrate with Onramp APIs, you can create an Onramp URL directly with your project ID.

Create Onramp URL with project ID

To create sessions without a token, disable Require secure initialization on the Onramp page in CDP.

Parameters for generating URLs

The following table outlines parameters to generate the OnRamp URL

Parameter	Req'd	Type	Description
defaultNetwork	No	String	Default network that should be selected when multiple networks are present
appId	Yes	String	The Project ID found on the project Dashboard
presetCryptoAmount	No	Number	Preset crypto amount value
presetFiatAmount	No	Number	Preset fiat amount value (for USD, CAD, GBP, EUR only). Ignored if presetCryptoAmount is also set.
defaultExperience	No	'send', 'buy'	Default visual experience: either (1) Transfer funds from Coinbase ('send') or (2) Buy assets ('buy')
handlingRequestedUrls	No	Boolean	Prevents the widget from opening URLs directly & relies on onRequestedUrl entirely for opening links
partnerUserId	No	String	Unique ID representing the end-user. Must be less than 50 chars. Use with the Transaction Status API to retrieve transactions made during the session.
sessionToken	Yes	String	Token generated by the Onramp Session Token API. Only required if Require secure initialization is true.
redirectUrl	No	String	URL to redirect the user to when they successfully complete a transaction.

info

All transactions made during the session are linked to partnerUserId which can be used with the Transaction Status API to retrieve these transactions later.