The widget supports a number of configuration options defined using query parameters.
This page describes the following topics related to the Trade Widget supported query parameters:
- List and description of supported query parameters
- Improving Trade Widget UX by passing specific query parameters
- How to use:
addressquery parameteraddressSignaturequery parametertransferInMediaandtransferOutMediaquery parameters
URL Encoding the query parameters:Every provided query parameter has to be URL encoded. E.g. using
encodeURIComponent(yourParameter)in JS.
Partner configuration
| Parameter | Description |
|---|---|
partnerId | Required. Your Partner ID as assigned by Coinify. |
partnerName | Name displayed in the widget (e.g. next to a partner fee). Defaults to 'Partner'. Can be string or object (just has be be provided as url encoded string, see example) |
partnerContext | Free-form context passed back to you in webhook payloads. Accepts a string or stringified JSON. |
Navigation and Access
| Parameter | Description |
|---|---|
targetPage | Landing page when the widget loads. Values: login, signup, signup-corporate, buy, sell, trade-history. |
refreshToken | Passes an authenticated session into the widget - used for Frictionless Sign-in. Must be URL-encoded. See Authentication Methods →. The refreshToken should be URL encoded so that the browsers interprets it correctly. |
noSignup | Controls sign-up availability. true disables sign-up entirely; corporate allows only individual sign-up; individual allows only corporate sign-up; false allows both. |
confirmMessages | When set, the widget waits for external confirmation before proceeding after key trade events. See Sending/Receiving Widget Messages →. |
Look and Feel
| Parameter | Description |
|---|---|
primaryColor | Colour of the primary button. Accepts a named value (e.g. blue), hex (e.g. #00ff00), or rgba. |
themeMode | Widget theme — light or dark. Defaults to light. |
Payment/Transfer Methods
| Parameter | Description |
|---|---|
transferInMedia | Comma-separated list of accepted inbound payment methods. Available: card, bank, applepay, googlepay, blockchain. |
transferOutMedia | Comma-separated list of accepted outbound payment methods. Available: bank, blockchain. |
Enabling Buy, Sell, or both
By default the widget enables both Buy and Sell with all available payment methods. Use transferInMedia and transferOutMedia to restrict this:
| Use case | Parameters |
|---|---|
| Buy only (card or bank), Sell disabled | transferInMedia=card,bank |
| Buy only (all methods), Sell disabled | transferOutMedia=blockchain |
| Buy via bank transfer only | transferInMedia=bank |
| Sell only (all methods), Buy disabled | transferInMedia=blockchain |
Currencies
| Parameter | Description |
|---|---|
cryptoCurrencies | Comma-separated list of cryptocurrencies to offer (e.g. BTC,ETH,XLM). Limits to a subset of Coinify-supported currencies. |
fiatCurrencies | Comma-separated list of fiat currencies to offer. |
defaultCryptoCurrency | The cryptocurrency pre-selected on the quote screen when multiple are available. |
defaultFiatCurrency | The fiat currency pre-selected on the quote screen when multiple are available. |
Trade amounts
| Parameter | Description |
|---|---|
buyAmount | Pre-fills the amount on the Buy quote screen. Often used with targetPage, defaultCryptoCurrency, and defaultFiatCurrency defined. |
sellAmount | Pre-fills the amount on the Sell quote screen. Often used with targetPage, defaultCryptoCurrency, and defaultFiatCurrency defined. |
isBuyAmountFixed | Set to true to lock the buyAmount so the end-user cannot change it. |
isSellAmountFixed | Set to true to lock the sellAmount so the end-user cannot change it. |
isBuyAmountWithFees | Set to true so that buyAmount is treated as fees-included — the amount the end-user will spend in total. |
isSellAmountWithFees | Set to true so that sellAmount is treated as fees-included. |
Wallet address
| Parameter | Description |
|---|---|
address | Pre-fills the receiving wallet address (Buy) or refund address (Sell). See How to use address below. |
addressSignature | HMAC-SHA-256 signature for the address value. Required if you have established a shared secret with Coinify. See how to use addressSignature below. |
walletType | Wallet type — self_hosted (user's own wallet) or vasp (hosted by a third-party exchange). If not provided, the end-user is prompted to select. See how to use walletType below. |
vaspId | Required when walletType is vasp. If provided, the VASP selection screen is skipped. See Supported VASPs →. |
memo | Optional memo or destination tag for cryptocurrencies that support it. See how to use memo below. |
Return URL
| Parameter | Description |
|---|---|
returnURL | URL to redirect the end-user to after a successfully completed trade. Must be URL-encoded. Only available on the Customised Landing Page. |
Improve UX by skipping screens
Passing certain parameters removes steps the end-user would otherwise have to complete manually. If you already hold any of this data, pass it through to streamline the flow:
| Parameter(s) | Screen skipped |
|---|---|
transferInMedia | Payment method selection screen |
buyAmount + defaultFiatCurrency + defaultCryptoCurrency | Quote screen |
address | Wallet address entry screen |
walletType | Wallet type selection screen |
vaspId | VASP selection screen (when walletType is vasp) |
Providing these parameters can only remove options from the user's view. There may be reasons (e.g legal or contractual) that some options are not available to your users in the underlying API. Adding parameters here will not change that.
Info:In general the widget will adjust to only present what makes sense with the given parameters (e.g. remove the Sell option if only Buy related
transferInMediaare found). It is currently possible to specify parameters that result in an invalid configuration. If you experience a blank widget, try to remove some parameters.
How to use address
addressFor a single cryptocurrency, pass the address directly:
<iframe src="...?cryptoCurrencies=BTC&address=2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD&..." />
For multiple cryptocurrencies, use the currency:address format:
<iframe src="...?address=BTC:2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD,ETH:0x44eae1E05F5f294f0f2a054D16605993FCd627a9&..." />
The same format applies to
addressSignatureandmemo.
Buying or Selling currencies with no default address specified will require the end-user to manually enter the wallet address.
Securing the address with a signature
Important:If you pre-fill wallet addresses, it is strongly recommended to sign them using a shared secret to prevent tampering. Share a UUID-format secret with Coinify via a secure channel to enable this feature — once enabled, trades with unsigned or incorrectly signed addresses will be rejected.
In order to ensure that the address passed into the widget has not been tampered with, you have the to sign the address(es) using a shared secret, and passing the signature to the widget as well.
Generate the signature using HMAC-SHA-256:
const crypto = require('crypto');
const address = 'crypto-address';
const secret = 'shared-secret';
const accountSignature = crypto.createHmac('SHA256', secret).update(address).digest('hex');addressSignature follows the same format as the address parameter described above.
- Single currency format:
addressSignature=<sig>
- Multiple currencies format:
addressSignature=BTC:<btcSig>,ETH:<ethSig>
Memo
Some crypto currencies accept a memo/destination tag in addition to the wallet address. The value for this can be specified in the memo query parameter.
Memo follows the same format as the address and addressSignature parameters, see examples above.
How to use walletType
walletTypeSimilar to providing the address, providing walletType differs depending on if you're passing values for one or multiple cryptocurrency wallets.
If multiple cryptocurrencies are being specified, the walletType parameter should be provided in the format currency1:walletType1,currency2:walletType2,... to specify the wallet type per each cryptocurrency you pass to the trade widget.
Alternatively, if the widget is configured to have only a single currency, you may provide only one value for the walletType parameter and omit the currency. See examples:
<iframe src="...?cryptoCurrencies=BTC&address=2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD&walletType=self_hosted..." />
<iframe src="...?walletType=BTC:vasp,ETH:vasp&..." />
You can get the list of supported VASPs here.
If the walletType is not specified, the customer will have to provide it on the Trade Widget.
If you are a VASP/CASP hosting wallets/addresses which receive the assets purchased by your end-users via Coinify Trade Widget, then you can pass vasp. If you are unsure whether the end-user is sending funds to their own wallet or to a VASP/CASP, then leave it to the customer to specify.