Skip to main content

Configuration

Ramp Network exposes multiple configuration options so that you can tailor the onramping experience to your users' needs.

Configuration​

Here's a list of the available configuration parameter options.

All of our SDKs encode parameters indirectly but if you want to use the hosted mode and for example your finalUrl contains some special characters like # or & then you have to encode parameters on your side before adding them to the URL. We recommend using encodeURIComponent for this purpose.

hostLogoUrl​

A required string parameter that allows you to brand your Ramp Network integration with your app's logo.

Example:

new RampInstantSDK({ ...rest, hostLogoUrl: 'https://example.com/logo.png' });

hostAppName​

A required string parameter that allows you to brand your Ramp Network integration with your app's name.

Example:

new RampInstantSDK({ ...rest, hostAppName: 'Maker DAO' });

hostApiKey​

A required string parameter that allows our system to properly recognize and count purchases made through your API integration. If you don't have an API key yet, you can find info on how to get one here

Example:

new RampInstantSDK({ ...rest, hostApiKey: 'the API key you received' });

swapAsset​

⚠️ Deprecated: This parameter is deprecated. Use enabledCryptoAssets instead, which provides a unified way to configure available crypto assets across all flows. See the search parameters migration guide for migration details.

An optional string parameter that sets a list of available crypto assets for user to choose from. If passed with a single asset, this parameter pre-sets the given asset for the user as the only option. If passed as a list (for example, swapAsset=ETH_DAI,ETH_ETH,ETH_USDC), it sets the available assets to the user with the first asset as the default selection. If left blank, the user will choose an asset on their own from all available assets. The list of all available assets can be accessed with GET /host-api/assets endpoint.

Additionally there is possibility to pass asset chain as a value (e.g. ETH, FLOW). When chain is passed it needs to to be suffixed with _* (e.g. ETH_*, FLOW_*). All symbols for provided chain will be parsed automatically (e.g ETH_* will be parsed as ETH_DAI,ETH_USDC,ETH_USDS,ETH_USDT). Chains and symbols could be mixed (e.g. MATIC_*,ETH_ETH). When providing only asset chain as argument, its assets could be used in defaultAsset param (e.g. swapAsset=ETH_*&defaultAsset=ETH_DAI).

Example:

new RampInstantSDK({ ...rest, swapAsset: 'ETH_ETH' });

offrampAsset​

⚠️ Deprecated: This parameter is deprecated. Use enabledCryptoAssets instead, which provides a unified way to configure available crypto assets across all flows. See the search parameters migration guide for migration details.

An optional string parameter, works exactly the same as swapAsset but applies only for off-ramp.

Example:

new RampInstantSDK({ ...rest, offrampAsset: 'ETH_ETH' });

swapAmount​

⚠️ Deprecated: This parameter is deprecated. Use inAssetValue or outAssetValue instead, depending on the flow. See the search parameters migration guide for migration details.

An optional int parameter that pre-sets the amount of crypto your user will buy. If left blank, the user will choose the amount on their own.

Note: the amount should be provided in wei or token units.

Example:

new RampInstantSDK({ ...rest, swapAmount: 10000000000000 });

fiatCurrency and fiatValue​

⚠️ Deprecated: These parameters are deprecated. Use inAsset/outAsset for currency/asset selection and inAssetValue/outAssetValue for values instead, depending on the flow. See the search parameters migration guide for migration details.

fiatCurrency (string) and fiatValue (float) are two optional parameters that allow you to pre-set the total fiat value and currency of the purchase that will be suggested to the user.

fiatCurrency can be used as a standalone parameter or together with fiatValue. Using fiatValue without fiatCurrency is not supported.

Passing fiatCurrency alone pre-sets the currency on the widget but if the given currency is not supported in the user's country there is a fallback to the country's default currency.

Passing both parameters together additionally pre-sets the total fiat value of the transaction. If the provided currency is not available for the payment method chosen by the user, we will recalculate the purchase amount into the user-selected fiat currency.

Example:

new RampInstantSDK({ ...rest, fiatCurrency: 'GBP', fiatValue: 10.0 });

enabledFlows​

An optional array of strings parameter that selects which modes are available on the widget. Acceptable values ONRAMP - for buying crypto, OFFRAMP - for selling crypto. If defaultFlow is not provided first item from the array is treated as defaultFlow. For the hosted mode value should be passed as comma separated string e.g. ONRAMP,OFFRAMP. Default value ['ONRAMP'].

Example:

new RampInstantSDK({ ...rest, enabledFlows: ['ONRAMP', 'OFFRAMP'] });

defaultFlow​

An optional string parameter that selects default mode of the widget. Acceptable values ONRAMP - for buying crypto, OFFRAMP - for selling crypto. Default value ONRAMP

Example:

new RampInstantSDK({ ...rest, defaultFlow: 'ONRAMP' });

userAddress​

An optional string parameter that pre-sets the address the crypto will be sent to. For off-ramp, will be treated as a source address from which the crypto will be sent from.

Example:

new RampInstantSDK({ ...rest, userAddress: 'user blockchain address' });

userEmailAddress​

An optional string parameter that pre-fills the email address for your user to make their onramping experience even quicker.

Example:

new RampInstantSDK({ ...rest, userEmailAddress: 'test@example.com' });

selectedCountryCode​

An optional string parameter that pre-selects user country. The value should be a two-letter country code (ISO 3166-1 alpha-2). Note: If a user already has used Ramp Network, their country will be selected automatically based on their last used methods.

Example:

new RampInstantSDK({ ...rest, selectedCountryCode: 'US' });

defaultAsset​

⚠️ Deprecated: This parameter is deprecated. Use inAsset or outAsset instead, depending on the flow. See the search parameters migration guide for migration details.

An optional string parameter that pre-selects an asset that will be shown to the user when they visit Ramp Network. The user will be able to change the selected asset.

Example:

new RampInstantSDK({ ...rest, defaultAsset: 'BTC_BTC' });

New Unified Parameters​

The following parameters provide a unified way to configure assets and values across all transaction flows (ONRAMP, OFFRAMP, and SWAP). These parameters replace the legacy flow-specific parameters for better consistency. See the search parameters migration guide for details on migrating from legacy parameters.

enabledCryptoAssets​

An optional string parameter that sets a list of available crypto assets for the user to choose from. This parameter applies to all flows (ONRAMP, OFFRAMP, and SWAP). If passed with a single asset, this parameter pre-sets the given asset as the only option. If passed as a comma-separated list (for example, enabledCryptoAssets=BTC_BTC,ETH_ETH,BASE_USDC), it sets the available assets with the first asset as the default selection. If left blank, the user will choose an asset from all available assets.

This parameter replaces the legacy swapAsset and offrampAsset parameters.

Example:

new RampInstantSDK({ ...rest, enabledCryptoAssets: 'BTC_BTC,ETH_ETH,BASE_USDC' });

inAsset​

An optional string parameter that sets the incoming asset (sent by the user). Can be a crypto asset identifier (e.g., BTC_BTC, BASE_USDC) or a fiat currency code (e.g., USD, EUR). The meaning depends on the flow:

  • ONRAMP: The fiat currency the user pays with (replaces legacy fiatCurrency)
  • OFFRAMP: The crypto asset the user sells (replaces legacy defaultAsset)
  • SWAP: The crypto asset the user swaps from

Example:

// ONRAMP: user pays with USD
new RampInstantSDK({ ...rest, defaultFlow: 'ONRAMP', inAsset: 'USD' });

// OFFRAMP: user sells BTC
new RampInstantSDK({ ...rest, defaultFlow: 'OFFRAMP', inAsset: 'BTC_BTC' });

// SWAP: user swaps from USDC to ETH
new RampInstantSDK({ ...rest, defaultFlow: 'SWAP', inAsset: 'BASE_USDC', outAsset: 'ETH_ETH' });

outAsset​

An optional string parameter that sets the outgoing asset (received by the user). Can be a crypto asset identifier (e.g., BTC_BTC, BASE_USDC) or a fiat currency code (e.g., USD, EUR). The meaning depends on the flow:

  • ONRAMP: The crypto asset the user receives (replaces legacy defaultAsset)
  • OFFRAMP: The fiat currency the user receives (replaces legacy fiatCurrency)
  • SWAP: The crypto asset the user swaps to

Example:

// ONRAMP: user receives USDC
new RampInstantSDK({ ...rest, defaultFlow: 'ONRAMP', outAsset: 'BASE_USDC' });

// OFFRAMP: user receives EUR
new RampInstantSDK({ ...rest, defaultFlow: 'OFFRAMP', outAsset: 'EUR' });

// SWAP: user swaps to BTC from ETH
new RampInstantSDK({ ...rest, defaultFlow: 'SWAP', outAsset: 'BTC_BTC', inAsset: 'ETH_ETH' });

inAssetValue​

An optional string parameter that sets the incoming asset value in units (no decimals). The meaning depends on the flow:

  • ONRAMP: The fiat amount in units (replaces legacy fiatValue, which was in accounting format with decimals)
  • OFFRAMP: The crypto amount in units (replaces legacy swapAmount)
  • SWAP: The crypto amount in units

Value Conversion:

  • For fiat values: Convert from accounting format (with decimals) to units (no decimals)
    • Example: "10.00" (EUR) becomes "1000" (units) (see ISO-4217 for more information)
  • For crypto values: Already in units, no conversion needed

Example:

// ONRAMP: 100 USD (10000 in units)
new RampInstantSDK({ ...rest, defaultFlow: 'ONRAMP', inAsset: 'USD', inAssetValue: '10000' });

// OFFRAMP: 0.05 BTC (50000000 in units)
new RampInstantSDK({ ...rest, defaultFlow: 'OFFRAMP', inAsset: 'BTC_BTC', inAssetValue: '50000000' });

// SWAP: 10 USDC (10000000 in units)
new RampInstantSDK({ ...rest, defaultFlow: 'SWAP', inAsset: 'BASE_USDC', inAssetValue: '10000000' });

outAssetValue​

An optional string parameter that sets the outgoing asset value in units (no decimals). The meaning depends on the flow:

  • ONRAMP: The crypto amount in units (replaces legacy swapAmount)
  • OFFRAMP: The fiat amount in units (replaces legacy fiatValue, which was in accounting format with decimals)
  • SWAP: The crypto amount in units

Value Conversion:

  • For fiat values: Convert from accounting format (with decimals) to units (no decimals)
    • Example: "50.00" (EUR) becomes "5000" (units) (see ISO-4217 for more information)
  • For crypto values: Already in units, no conversion needed

Example:

// ONRAMP: 500000 units of crypto
new RampInstantSDK({ ...rest, defaultFlow: 'ONRAMP', outAssetValue: '500000' });

// OFFRAMP: 50 EUR (5000 in units)
new RampInstantSDK({ ...rest, defaultFlow: 'OFFRAMP', outAsset: 'EUR', outAssetValue: '5000' });

url​

An optional string parameter that allows you to use a non-production version of our widget.

Example:

new RampInstantSDK({
  ...rest,
  url: 'https://app.demo.rampnetwork.com',
});

webhookStatusUrl​

An optional string parameter that allows you to subscribe to purchase events via webhooks.

Example:

new RampInstantSDK({
  ...rest,
  webhookStatusUrl: 'https://example.com/webhook/',
});

offrampWebhookV3Url​

An optional string parameter that allows you to subscribe to sale events via webhooks.

Example:

new RampInstantSDK({ ...rest, offrampWebhookV3Url: 'https://example.com/webhook/' });

finalUrl​

An optional string parameter that allows you to provide a link the user will be redirected to after completing the flow.

NOTE: this is only available for the hosted integration and on-ramp flow.

Example:

new RampInstantSDK({ ...rest, finalUrl: 'https://example.com/redirect' });

successUrl​

An optional string parameter that allows you to provide a URL the user will be redirected to after a successful transaction. When provided, the primary button on success screens will show "Back to partner" and open the given URL in a new tab.

This parameter works across ONRAMP and OFFRAMP flows and takes effect on delivery/payout completion screens.

Example:

new RampInstantSDK({ ...rest, successUrl: 'https://example.com/success' });

failureUrl​

An optional string parameter that allows you to provide a URL the user will be redirected to after a failed transaction. When provided, the primary button on failure/error screens will show "Back to partner" and open the given URL in a new tab.

This parameter works across ONRAMP and OFFRAMP flows and takes effect on error screens such as delivery failures, transaction failures, verification failures, and final check failures.

Example:

new RampInstantSDK({ ...rest, failureUrl: 'https://example.com/failure' });

useSendCryptoCallback​

Only applicable for OFFRAMP mode. An optional boolean parameter to inform the widget that Send with your wallet button should be visible. More details about this feature can be found here.

Example:

new RampInstantSDK({
  ...rest,
  defaultMode: 'OFFRAMP',
  useSendCryptoCallback: true,
});

variant​

An optional string parameter that determines how the widget is displayed. The options are auto, hosted, desktop, mobile, hosted-mobile, webview-desktop, webview-mobile, embedded-mobile and embedded-desktop. The default is auto. embedded-mobile and embedded-desktop must be passed along with the containerNode variable.

Example:

new RampInstantSDK({ ...rest, variant: 'auto' });

paymentMethodType​

An optional string parameter that pre-selects payment method for your user to make their onramping experience even quicker.

The options are MANUAL_BANK_TRANSFER, AUTO_BANK_TRANSFER, PIX, APPLE_PAY, GOOGLE_PAY, CARD_PAYMENT

These options are deprecated SEPA, CARD, APPLEPAY, GOOGLEPAY, OPEN_BANKING , PISP.

PISP is now deprecated and, if provided, will be mapped to OPEN_BANKING instead.

Deprecated options should be mapped as below:

PISP: AUTO_BANK_TRANSFER SEPA: MANUAL_BANK_TRANSFER APPLEPAY: APPLE_PAY GOOGLEPAY: GOOGLE_PAY CARD: CARD_PAYMENT OPEN_BANKING: AUTO_BANK_TRANSFER

Applies only for on-ramp.

Example:

new RampInstantSDK({ ...rest, paymentMethodType: 'CARD' });

containerNode​

An DOM node parameter that must be provided when using the embedded-mobile or embedded-desktop variants.

Example:

new RampInstantSDK({
  ...rest,
  containerNode: document.getElementById('ramp-container'),
});

hideExitButton​

An optional boolean parameter to show or hide internal exit button on widget. Useful if you want to close the widget on your own.

Example:

new RampInstantSDK({
  ...rest,
  hideExitButton: true,
});