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!

  1. 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

Session tokens are now required and will be enforced starting 7/31/2025. The URL should look like this:

https://pay.coinbase.com/buy/select-asset?sessionToken=<token>&<other params>

​
Onramp URL parameters:

ParameterRequiredTypeDescription
appIdYesStringThe Project ID found on the project Dashboard
addressesYesRecord<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"]})
assetsNoString[]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.
defaultNetworkNoStringDefault network that should be selected when multiple networks are present
defaultAssetNoStringDefault asset that should be selected when multiple assets are present
presetCryptoAmountNoNumberPreset crypto amount value
presetFiatAmountNoNumberPreset fiat amount value (for USD, CAD, GBP, EUR only). Ignored if presetCryptoAmount is also set.
defaultExperienceNo’send’, ‘buy’Default visual experience: either (1) Transfer funds from Coinbase (‘send’) or (2) Buy assets (‘buy’)
defaultPaymentMethodNoStringDefault payment method used to purchase the asset
fiatCurrencyNoStringe.g: USD, CAD, GBP, etc.
handlingRequestedUrlsNoBooleanPrevents the widget from opening URLs directly & relies on onRequestedUrl entirely for opening links
partnerUserIdNoStringUnique ID representing the end-user. Must be less than 50 chars. Use with the Transaction Status API to retrieve transactions made during the session.
sessionTokenYesStringToken generated by the Onramp Session Token API. Required if Require secure initialization is true which all apps must do by 7/31/2025. If this is set, appId and addresses parameters not required.
redirectUrlNoStringURL to redirect the user to when they successfully complete a transaction.

​
Getting a Session Token

All apps must use session tokens starting 7/31/2025. Developers can create and use a session token to securely authenticate users and manage sessions.

​
Authentication

To authenticate your requests to the Session Token API, you’ll need to:

  1. Create a CDP Secret API Key
  2. Follow the instructions for CDP API key authentication to make signed requests

Using the JWT token, you can make a request to 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.

NameTypeReqDescription
addressesAddress[]YList 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.
assetsString[]NList 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:

ParameterReq’dTypeDescription
addressYesStringDestination address where the purchased tokens will be sent.
blockchainsYesString[]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

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"]}'