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.
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)
- Response 200 (JSON)
curl -X POST 'https://api.developer.coinbase.com/onramp/v1/token' \
-H "Authorization: Bearer $JWT" \
-d '{"destination_wallets": [{"address":"bc1qrdvlkt8rqsyj229thqzhm0q39edwdj2k7yps6x", "blockchains": ["bitcoin"]}]}'
{
"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.
To create sessions without a token, disable Require secure initialization on the Onramp page in CDP.
![Confirm your payment method.](/assets/images/onramp-sec-init-a5cfc7767b29f4b9f7b64900474a7726.png)
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. |
All transactions made during the session are linked to partnerUserId
which can be used with the Transaction Status API to retrieve these transactions later.