Widget Parameters
Configure the widget by passing parameters when building the URL or initializing the JS SDK.
- URL / plain iFrame — pass as URL query parameters in
snake_case - JS SDK (
mercuryoWidget.run()) — pass as properties incamelCase
Multi-word parameters follow a consistent naming rule: fiat_currency → fiatCurrency. Single-word parameters (currency, address, signature, network, etc.) are identical in both formats.
Full references: URL Parameter Docs · Interactive JS SDK Demo
Most Used Parameters
| URL parameter | JS SDK property | Description | Example |
|---|---|---|---|
widget_id |
widgetId |
Your Widget ID from the Dashboard | 67710925-8b40-4767-846e-3b88db69f04d |
address |
address |
User's crypto wallet address for receiving purchased crypto | 0x742d35Cc... |
merchant_transaction_id |
merchantTransactionId |
Your internal transaction ID | tx_123456 |
signature |
signature |
Security signature — see Signature Generation | v2:abc123... |
type |
type |
Lock operation type: buy or sell |
buy |
currency |
currency |
Pre-select cryptocurrency ticker | BTC |
amount |
amount |
Pre-fill cryptocurrency amount | 0.001 |
fiat_currency |
fiatCurrency |
Pre-select fiat currency ticker | EUR |
fiat_amount |
fiatAmount |
Pre-fill fiat amount | 100 |
network |
network |
Pre-select blockchain network | ETHEREUM |
fix_currency |
fixCurrency |
Prevent user from changing cryptocurrency | true |
fix_fiat_currency |
fixFiatCurrency |
Prevent user from changing fiat currency | true |
fix_amount |
fixAmount |
Lock cryptocurrency amount | true |
fix_fiat_amount |
fixFiatAmount |
Lock fiat amount | true |
payment_method |
paymentMethod |
Pre-select payment method: card, mobile_pay, spend, spend_card |
card |
fix_payment_method |
fixPaymentMethod |
Lock payment method (use with payment_method) |
true |
address_map |
addressMap |
Map of wallet addresses by currency (URL-encoded JSON) — formats below | — |
refund_address |
refundAddress |
Wallet address for refund on Mercuryo-side failure (Off-Ramp) | 0x123... |
init_token |
initToken |
Token for silent user sign-in — see Authentication | 0a25dd714163a9006 |
init_token_type |
initTokenType |
Always sdk_partner_authorization when using init_token |
sdk_partner_authorization |
share_token |
shareToken |
SumSub share token for pre-verified KYC — see KYC | _act-ca0dae00... |
theme |
theme |
Pre-built custom theme — see Customization | trustwallet |
lang |
lang |
Widget language (ISO 639-1) | de |
redirect_url |
redirectUrl |
URL to redirect user after transaction completes | https://yourapp.com/success |
widget_flow |
widgetFlow |
Enable a specific flow: recurrent for recurring payments |
recurrent |
address_map Formats
address_map accepts a URL-encoded JSON object that maps currency tickers to wallet addresses. Three formats are supported:
Simple (address only):
{"BTC": "2N2SJgCWoksfTmQySbMZhgwmdy9QNLRuD84", "ETH": "0x7E64..."}
With network specified:
{"BTC": {"address": "2N2SJgCW...", "network": "BITCOIN"}, "ETH": {"address": "0x7E64...", "network": "ETHEREUM"}}
Mixed (some currencies with network, some without):
{"BTC": "2N2SJgCW...", "ETH": {"address": "0x7E64...", "network": "ETHEREUM"}}
Full Parameter Reference
The table above covers the most commonly used parameters. For the complete list:
- URL Parameter Reference — all URL parameters with full descriptions
- Interactive Demo — try JS SDK parameters live in the browser