Supported widget parameters

Parameter	Type	Description
apiKey	string	The unique identifier provided by the Onramper team.
mode	string	A comma-separated list of widget modes to support (e.g., `buy,sell`).
partnerContext	string	A unique string used to identify each session.
successRedirectUrl	string	Specifies a redirect URL for successful transaction completion.
failureRedirectUrl	string	Specifies a redirect URL for a failed transaction.
defaultFiat	string	The default fiat currency is to be displayed.
onlyFiats	string	The only fiat currencies to be displayed.
excludeFiats	string	Fiat currencies that are to be excluded.
defaultAmount	number	The default amount to be displayed (must be used with `defaultFiat`).
defaultCrypto	string	The default cryptocurrency is to be displayed.
excludeCryptos	string	Cryptocurrencies to be excluded.
onlyCryptos	string	The only cryptocurrencies to be displayed.
excludeCryptoNetworks	string	Blockchain networks to be excluded.
onlyCryptoNetworks	string	The only blockchain networks to be displayed
defaultPaymentMethod	string	The default payment method is to be displayed.
excludePaymentMethods	string	Payment Methods to be excluded.
wallets	string	The wallet address(-es) to be passed to the widget.
networkWallets	string	Multiple wallet addresses can be specified for use with all tokens that are supported by a single blockchain network.
walletAddressTags	string	String of wallet address tags (destination tags/memos) that can be supplied to the widget
supportRecurringPayments	boolean	Enable repeat payments (DCA).
enableCountrySelector	boolean	Display the country selector.

API Key

Your API key uniquely identifies you as a client — and it’s essential for configuring features like coverage, recommendations, webhook support, and other important settings.

With your API key added, your URL will look something like this:

https://buy.onramper.com/?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT

Partner Context

partnerContext is a unique string used to identify each session. It must be a valid string format. This identifier will be included in every webhook payload and the response for each order retrieval request.

With the partnerContext, the URL will look like this

https://buy.onramper.com?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT&partnerContext=<partner_context>

Success Redirect URL

successRedirectUrl specifies a URL for redirecting the user after a successful transaction completion. It's important to note that not all providers support this feature. Availability can be checked on the Feature support (per onramp). The URL should be URL-encoded.

https://buy.onramper.com?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT&successRedirectUrl=https%3A%2F%2Fonramper.com%2F

Failure Redirect URL

failureRedirectUrl specifies a URL for redirecting the user after a failed transaction. It's important to note that not all providers support this feature. Availability can be checked on the Feature support (per onramp). The URL should be URL-encoded.

https://buy.onramper.com?apiKey=pk_prod_01HETEQF46GSK6BS5JWKDF31BT&failureRedirectUrl=https%3A%2F%2Fonramper.com%2F

Default Fiat

Set a default fiat currency to be displayed using thedefaultFiat

https://buy.onramper.com?defaultFiat=USD

Only Fiats

Force one or multiple fiat currencies in your widget using onlyFiats:

https://buy.onramper.com?onlyFiats=USD,EUR

Exclude Fiats

Omit certain fiat currencies with excludeFiats:

https://buy.onramper.com?excludeFiats=USD,EUR

Default Amount

When used in conjunction with defaultFiat, defaultAmount will pre-populate the fiat currency input with your desired amount.

The URL below will default to a EUR amount of €125 whenever a user accesses your widget:

https://buy.onramper.com?defaultFiat=EUR&defaultAmount=125

Default Crypto

By default, the widget will use its recommendation algorithm to set the output currency, based on the most-used crypto in the user’s country.

However, you can override this with defaultCrypto. Check out Crypto currencies to find your desired ID.

https://buy.onramper.com/?defaultCrypto=ETH

Exclude Cryptos

Right out of the box, the Onramper widget makes all cryptocurrencies available.

Use excludeCryptos if you want to remove some from your widget. For instance, the example below makes ether and bitcoin unavailable to buy:

https://buy.onramper.com?excludeCryptos=BTC,ETH

Only Cryptos

If you only want a specific set of cryptos to be displayed, use onlyCryptos. The string below ensures that only BTC and ETH can be bought through your widget:

https://buy.onramper.com?onlyCryptos=ETH,BTC

Exclude Crypto Networks

Similar to excludeCryptos, excludeCryptoNetworks allows you to remove entire crypto networks from the widget: Network ids can be found from Crypto networks

https://buy.onramper.com?excludeCryptoNetworks=bitcoin,ethereum

Only Crypto Networks

onlyCryptoNetworks enables you to force the use of certain networks.

https://buy.onramper.com/?onlyCryptoNetworks=ethereum,polygon

Default Payment Method

Load your preferred payment method with defaultPaymentMethod. You can find their Onramper IDs under Payment methods.

Below is an example of a URL that loads Bank Transfer:

https://buy.onramper.com/?defaultFiat=EUR&defaultAmount=200&defaultPaymentMethod=banktransfer

Exclude Payment Methods

Don’t want to show your users certain payment methods? Add excludePaymentMethods to your string:

https://buy.onramper.com/?defaultFiat=EUR&excludePaymentMethods=creditcard

Wallets

The wallets parameter allows you to pass a string containing wallet addresses to the widget.

Format-wise, each address should be a combination of the Token ID and the wallet address, separated by a colon. For instance, the example below shows the string for a wallet on the Bitcoin network:

BTC:3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5

Want to add multiple addresses? Just use the same format, separating each instance with a comma:

wallets=BTC:3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5,ETH:0xb794f5ea0ba39494ce839613fffba74279579268

Remember, the URL itself should also incorporate a valid production API Key:

https://buy.onramper.com?wallets=BTC:3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5,ETH:0xb794f5ea0ba39494ce839613fffba74279579268

Network Wallets

Want to pass a wallet that functions for multiple currencies or tokens on a network? For that, you’ll need networkWallets. Provide a valid Onramper Network ID, followed by the wallet address:

The wallet address can be prefixed with any valid).

https://buy.onramper.com/?networkWallets=ETHEREUM:0xb794f5ea0ba39494ce839613fffba74279579268

Wallet Address Tags

The walletAddressTags parameter allows you to pass a string of wallet address tags (destination tags/memos) that can be supplied to the widget.

Format-wise, each address should be a combination of the Token ID and the tag, separated by a colon.

https://buy.onramper.com/?wallets=xrp_ripple:rCoinaUERUrXb1aA7dJu8qRcmvPNiKS3d,xlm_stellar:0xb794f5ea0ba39494ce839613fffba74279579268&walletAddressTags=xrp_ripple:1234567890,xlm_stellar:1234567890

Repeat Payments

Onramper's feature for recurring cryptocurrency purchases allows users to set up plans for automatic crypto buying. To activate this feature, users should append supportRecurringPayments=true as a query parameter in the URL. This addition enables the repeat payments functionality, offering a streamlined way for regular crypto investments.

https://buy.onramper.com/?supportRecurringPayments=true

Country Selector

Onramper's widget includes a feature enabling users to select their country to obtain a tailored quote. To activate this country selector, add enableCountrySelector=true as a query parameter in the URL. This functionality provides a more personalized experience. However, it's important to note that there may be country-specific and geo-restrictions imposed by onramp services, potentially limiting the ability to proceed with transactions in certain regions.

https://buy.onramper.com/?enableCountrySelector=true