Accounts5

Customers6

Deposit Destinations3

Disbursements3

End User Account Management9

End User Accounts26

EVM Accounts15

EVM Smart Accounts12

EVM Swaps2

EVM Token Balances1

Faucets2

Mandates12

Onchain Data2

Onramp7

Payment Methods2

Payment Sessions21

Policy Engine5

Solana Accounts11

Solana Token Balances1

SQL API3

Transfers5

Webhooks6

x402 Facilitator10

Webhooks

Customers2

Disbursements3

Health5

Mandates8

Onchain Data3

Onramp8

Payment Sessions14

Transfers7

Wallet Webhooks12

Onramp

Create an onramp session

Changed on Oct 6, 2026

Returns a single-use URL for an Onramp session. This API provides flexible functionality based on the parameters provided, supporting three cases:

Important: The returned URL is single-use only. Once a user visits the URL, no one else can access it.

Use Cases

1. Basic Session (Minimum Parameters)

Required: destinationAddress, purchaseCurrency, destinationNetwork

Returns: Basic single-use onramp URL. The quote object will not be included in the response.

2. One-Click Onramp URL

Required: Basic parameters + (paymentAmount OR purchaseAmount), paymentCurrency

Returns: One-click onramp URL for streamlined checkout. The quote object will not be included in the response.

3. One-Click Onramp URL with Quote

Required: One-Click Onramp parameters + paymentMethod, country, subdivision

Returns: Complete pricing quote and one-click onramp URL. Both session and quote objects will be included in the response.

Note: Only one of paymentAmount or purchaseAmount should be provided, not both. Providing both will result in an error. When paymentAmount is provided, the quote shows how much crypto the user will receive for the specified fiat amount (fee-inclusive). When purchaseAmount is provided, the quote shows how much fiat the user needs to pay for the specified crypto amount (fee-exclusive).

post/v2/onramp/sessions

Request

Base URL: https://api.cdp.coinbase.com/platform
URL: https://api.cdp.coinbase.com/platform/v2/onramp/sessions
Auth: HTTP bearer

Headers

X-Onramp-Partner-Idstring uuid

The Onramp-issued identifier of a disclosed end partner, scoped to an aggregator's developer app. Aggregators integrating Onramp on behalf of multiple end partners set this header to attribute a request to one of their registered partners; omit it for standard, non-aggregator integrations. Only honored for developer apps registered as an aggregator — requires Onramp aggregator onboarding, including registration of each end partner. Contact the Onramp team for access.

Request body

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

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

destinationAddressstring required

A blockchain address. Format varies by network (e.g., 0x-prefixed for EVM, base58 for Solana).

paymentAmountstring

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.

purchaseAmountstring

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.

paymentCurrencystring

The fiat currency to be converted to crypto.

The type of payment method used to generate the onramp quote.

countrystring

The ISO 3166-1 two letter country code (e.g. US).

subdivisionstring

The ISO 3166-2 two letter state code (e.g. NY). Only required for US.

redirectUrlstring uri

A valid URI.

clientIpstring

The IP address of the end user requesting the onramp transaction.

partnerUserRefstring

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

Example request

{
  "purchaseCurrency": "USDC",
  "destinationNetwork": "base",
  "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "paymentAmount": "100.00",
  "purchaseAmount": "10.000000",
  "paymentCurrency": "USD",
  "paymentMethod": "CARD",
  "country": "US",
  "subdivision": "NY",
  "redirectUrl": "foo://bar",
  "clientIp": "127.0.0.1",
  "partnerUserRef": "user-1234"
}

Response

Onramp session created successfully.

Example response

{
  "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"
  }
}

Changes

Oct 6, 2026156440e9f8df Revision changes
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new incompatible_event_types enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_headers enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new invalid_webhook_url enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_action_pending enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_canceled enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_expired enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_invalid_status enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_policy_violation enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new mandate_revoked enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- warning
  added the new subscription_limit_exceeded enum value to the response property for the response status
- info
  added the new optional header request parameter X-Onramp-Partner-Id
- info
  added the non-success response with the status
Sep 25, 2026229ed860a74b Revision changes
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new mfa_challenge_not_found enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status
- warning
  added the new operation_in_progress enum value to the response property for the response status

Operation history (15 revisions)