Migrating legacy search parameters

This guide helps you understand how legacy URL search parameters map to the new unified parameter format. Use this reference when updating your integration or troubleshooting parameter-related issues.

Overview

The widget uses a new, unified parameter format that simplifies configuration across all transaction flows. If you're currently using legacy parameters (like fiatCurrency, defaultAsset, swapAsset, etc.), this guide shows you:

• What changed: How each legacy parameter maps to the new format
• How to update: Examples showing the old vs. new parameter format
• What you need to do: Whether any action is required on your end

Good news: The widget automatically converts legacy parameters to the new format, so your existing URLs will continue to work. However, we recommend updating to the new parameters for better consistency and future compatibility.

Parameter migrations

1. enabledCryptoAssets

Legacy Parameters:

• swapAsset - Comma-separated list of crypto assets for onramp transactions
• offrampAsset - Comma-separated list of crypto assets for offramp transactions

New Parameter:

• enabledCryptoAssets - Comma-separated list of enabled crypto assets (applies to all flows)

Example:

Legacy: ?swapAsset=BTC,ETH&offrampAsset=USDC
New:    ?enabledCryptoAssets=BTC,ETH,USDC

2. inAsset

Legacy Parameters:

• fiatCurrency - ISO 4217 currency code (e.g., USD, EUR)
• defaultAsset - Crypto asset identifier (eg. BTC_BTC, BASE_USDC)

New Parameter:

• inAsset - The incoming asset (sent by the user), can be a crypto asset key or fiat currency code

How it works (Flow-Specific):

Flow	Legacy → New
ONRAMP	fiatCurrency → inAsset
OFFRAMP	defaultAsset → inAsset
SWAP	unsupported → inAsset

Examples:

ONRAMP:
  Legacy: ?defaultFlow=ONRAMP&fiatCurrency=USD
  New:    ?defaultFlow=ONRAMP&inAsset=USD

OFFRAMP:
  Legacy: ?defaultFlow=OFFRAMP&defaultAsset=BTC_BTC
  New:    ?defaultFlow=OFFRAMP&inAsset=BTC_BTC

SWAP:
  Legacy: unsupported
  New:    ?defaultFlow=SWAP&inAsset=BASE_USDC

3. outAsset

Legacy Parameters:

• fiatCurrency - ISO 4217 currency code (eg. USD, EUR)
• defaultAsset - Crypto asset identifier (eg. BTC_BTC, BASE_USDC)

New Parameter:

• outAsset - The outgoing asset (received by the user), can be a crypto asset key or fiat currency code

How it works (Flow-Specific):

Flow	Legacy → New
ONRAMP	defaultAsset → outAsset
OFFRAMP	fiatCurrency → outAsset
SWAP	unsupported → outAsset

Examples:

ONRAMP:
  Legacy: ?defaultFlow=ONRAMP&defaultAsset=BASE_USDC
  New:    ?defaultFlow=ONRAMP&outAsset=BASE_USDC

OFFRAMP:
  Legacy: ?defaultFlow=OFFRAMP&fiatCurrency=EUR
  New:    ?defaultFlow=OFFRAMP&outAsset=EUR

SWAP:
  Legacy: unsupported
  New:    ?defaultFlow=SWAP&outAsset=BASE_USDC

4. inAssetValue

Legacy Parameters:

• fiatValue - Fiat amount in accounting format (with decimals, e.g., "10.00")
• swapAmount - Crypto amount in units (no decimals, e.g., "1000000")

New Parameter:

• inAssetValue - The incoming asset value in units (no decimals)

How it works (Flow-Specific):

Flow	Legacy → New	Value Conversion
ONRAMP	fiatValue → inAssetValue	Accounting format → Units
OFFRAMP	swapAmount → inAssetValue	Already in units (no conversion)
SWAP	unsupported → inAssetValue	N/A

Value Conversion:

• For fiat values: fiatValue must be converted from accounting format (with decimals) to units (no decimals)
  • Example: "10.00" (EUR) becomes "1000" (units)
• For crypto values: swapAmount is already in units, so it doesn't require any changes

Examples:

ONRAMP (100 USD):
  Legacy: ?defaultFlow=ONRAMP&fiatCurrency=USD&fiatValue=100.00
  New:    ?defaultFlow=ONRAMP&inAsset=USD&inAssetValue=10000

OFFRAMP (0.05 BTC):
  Legacy: ?defaultFlow=OFFRAMP&defaultAsset=BTC_BTC&swapAmount=50000000
  New:    ?defaultFlow=OFFRAMP&inAsset=BTC_BTC&inAssetValue=50000000

SWAP (10 USDC):
  Legacy: unsupported
  New:    ?defaultFlow=SWAP&inAsset=BASE_USDC&inAssetValue=10000000

5. outAssetValue

Legacy Parameters:

• fiatValue - Fiat amount in accounting format
• swapAmount - Crypto amount in units

New Parameter:

• outAssetValue - The outgoing asset value in units (no decimals)

How it works (Flow-Specific):

Flow	Legacy → New	Value Conversion
ONRAMP	swapAmount → outAssetValue	Already in units (no conversion)
OFFRAMP	fiatValue → outAssetValue	Accounting format → Units
SWAP	unsupported → outAssetValue	N/A

Value Conversion:

• For fiat values: fiatValue must be converted from accounting format (with decimals) to units (no decimals)
  • Example: "50.00" (EUR) becomes "5000" (units)
• For crypto values: swapAmount is already in units, so it doesn't require any changes

Examples:

ONRAMP:
  Legacy: ?defaultFlow=ONRAMP&swapAmount=500000
  New:    ?defaultFlow=ONRAMP&outAssetValue=500000

OFFRAMP:
  Legacy: ?defaultFlow=OFFRAMP&fiatCurrency=EUR&fiatValue=50.00
  New:    ?defaultFlow=OFFRAMP&outAsset=EUR&outAssetValue=5000

SWAP:
  Legacy: ?defaultFlow=SWAP
  New:    ?defaultFlow=SWAP (outAssetValue not set)

Complete migration examples

ONRAMP example

Purchase 100 USD worth of BASE_USDC (user can change the asset)

Before:

?defaultFlow=ONRAMP&fiatCurrency=USD&fiatValue=100.00&swapAsset=BASE_USDC

After:

?defaultFlow=ONRAMP&inAsset=USD&inAssetValue=10000&enabledCryptoAssets=BASE_USDC

Purchase 0.05 BTC with EUR (user choice limited to BTC only)

Before:

?defaultFlow=ONRAMP&swapAsset=BTC&swapAmount=50000000&fiatCurrency=EUR

After:

?defaultFlow=ONRAMP&enabledCryptoAssets=BTC_BTC&inAssetValue=50000000&outAsset=EUR

OFFRAMP example

Sell 0.05 BTC for USD

Before:

?defaultFlow=OFFRAMP&defaultAsset=BTC_BTC&swapAmount=50000000&fiatCurrency=USD

After:

?defaultFlow=OFFRAMP&inAsset=BTC_BTC&inAssetValue=50000000&outAsset=USD

SWAP example

New flow introduced with the updated search parameters.

Swap 10 USDC for BTC

?defaultFlow=SWAP&inAsset=BASE_USDC&inAssetValue=10000000&outAsset=BTC_BTC