Generating an Onramp URL

Coinbase Onramp is accessed by creating and directing users to a URL with query parameters specific to their request. There are two ways to create an Onramp URL:

1. Use the getOnrampBuyUrl util to generate a URL with default parameters
   • Most commonly used on the Frontend

Frontend developers love using our <FundCard /> and <FundButton />, customizable React components to fund a wallet without leaving your App!

2. Manually generate a URL with required parameters
   • Most commonly used on the Backend

Full API endpoint list

For a complete list of all API endpoints supported by Onramp/Offramp, visit our API Reference section.

Backend URL creation

For Apps with a backend, use our APIs to create a One-Click-Buy URL - a prefilled URL which takes users straight to the preview screen (existing Coinbase users) or Apple Pay + debit card (Guest checkout). This enables you to pass a user’s wallet addresses via API and avoid using query params for sensitive fields

Example URL without Session Token

https://pay.coinbase.com/buy/select-asset?appId=58a3fa2e-617f-4198-81e7-096f5e498c00&addresses={"0x4315d134aCd3221a02dD380ADE3aF39Ce219037c":["base"]}&assets=["USDC","ETH"]

Session tokens

To create URLs without a session token, disable Require secure initialization in your Onramp settings.

Onramp URL parameters:

Parameter	Required	Type	Description
appId	Yes	String	The Project ID found on the project Dashboard
addresses	Yes	Record<Address>	Addresses that the purchased crypto should be sent to. An object whose keys are addresses and values are arrays of networks each address supports. (e.g. addresses={"0x1":["base"]})
assets	No	String[]	List of assets that will be available for the user to buy/send. e.g. [“ETH”, “BTC”] or UUIDs retrieved from the Buy Options API. This optional parameter acts as a filter on the addresses parameter. If it is included then only the assets in this list that are available on one of the supported blockchains in the Addresses list will be available to the user. See the See the Buy Options API for the full list of assets.
defaultNetwork	No	String	Default network that should be selected when multiple networks are present
defaultAsset	No	String	Default asset that should be selected when multiple assets are present
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’)
defaultPaymentMethod	No	String	Default payment method used to purchase the asset
fiatCurrency	No	String	e.g: USD, CAD, GBP, etc.
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	No	String	Token generated by the Onramp Session Token API. Only required if Require secure initialization is true. If this is set, appId and addresses parameters not required.
redirectUrl	No	String	URL to redirect the user to when they successfully complete a transaction.

Getting a Session Token

Session tokens are optional. Developers can create and use a session token to securely authenticate users and manage sessions.

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

First call the Session Token API to obtain a token, then pass that token as the sessionToken query string parameter when generating the Coinbase Onramp or Offramp 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.

Full API endpoint list For a complete list of all API endpoints supported by Onramp/Offramp, visit our API Reference section.

Method

POST

URL

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

Request Parameters

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

Name	Type	Req	Description
addresses	Address[]	Y	List of addresses that the purchased crypto should be sent to. Each entry in this array is an object containing an address and a list of blockchains the address supports.
assets	String[]	N	List of assets that will be available for the user to buy/send. Assets can either be symbols e.g. “ETH” or “BTC”, or UUIDs retrieved from the Buy Options API. This optional parameter acts as a filter on the addresses parameter. If it is included then only the assets in this list that are available on one of the supported blockchains in the Addresses list will be available to the user. See the See the Buy Options API for the full list of assets.

Address Parameters

An Address object accepts the following parameters:

Parameter	Req’d	Type	Description
address	Yes	String	Destination address where the purchased tokens will be sent.
blockchains	Yes	String[]	List of blockchains enabled for the associated address. All tokens available per blockchain are displayed to the user. Available blockchains include: “ethereum”, “bitcoin”, “base”, “avacchain”, “optimism”, “solana”, “polygon”, “arbitrum”, “stellar” and many more. See the Buy Options API for the full list.

Response Fields

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

Example Request/Response

Request (cURL)

cdpcurl -X POST 'https://api.developer.coinbase.com/onramp/v1/token' \
  -k /tmp/cdp_api_key.json \
  -d '{"addresses": [{"address": "0x4315d134aCd3221a02dD380ADE3aF39Ce219037c", "blockchains": ["ethereum", "base"]}], "assets": ["ETH", "USDC"]}'