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:
- address query parameter
- addressSignature query parameter
- transferInMedia and transferOutMedia query parameters

🚧
URL Encoding the query parameters:
Every provided query parameter has to be URL encoded. E.g. using encodeURIComponent(yourParameter) in JS.

Parameter	Description
`partnerId`	id you got from Coinify
`partnerName`	name to be displayed in the widget as partner name, currently used when displaying partner fee if enabled, defaults to 'Partner'. Can be string or object (just has be be provided as url encoded string, see example)
`partnerContext`	Free context for partners to receive in webhooks, can be stringified JSON as well. Partner context may also be provided using `settings.partner-context-changed`
`primaryColor`	color of the primary button; Accepted: named value e.g. `blue`, hash value e.g. `#00ff00`, or `rgba(0,255,0,1)`
`themeMode`	enables you to set the Trade Widget theme to `light` or `dark`. If not specified, defaults to `light`.
`cryptoCurrencies`	comma separated list of crypto currencies to support in the widget. Will include only the listed crypto currencies from those supported by default
`fiatCurrencies`	comma separated list of fiat currencies to support in the widget. Will include only the listed fiat currencies from those supported by default
`defaultCryptoCurrency`	defines the crypto currency initially selected on Buy/Sell quotes if multiple crypto currencies are available
`defaultFiatCurrency`	defines the fiat currency initially selected on Buy/Sell quotes if multiple fiat currencies are available
`buyAmount`	defines initial amount on Buy quotes. Note, often used with `targetPage`, `defaultCryptoCurrency`, and `defaultFiatCurrency` defined
`sellAmount`	defines initial amount on Sell quotes. Note, often used with `targetPage`, `defaultCryptoCurrency`, and `defaultFiatCurrency` defined
`isBuyAmountFixed`	If set to `true`, the specified `buyAmount` is locked and cannot be changed from the Trade Widget UI. Accepts `true` or `false` values.
`isSellAmountFixed`	If set to `true`, the specified `sellAmount` is locked and cannot be changed from the Trade Widget UI. Accepts `true` or `false` values.
`isBuyAmountWithFees`	If set to `true`, the provided `buyAmount` will include all the fees and the `buyAmount` will be the amount the end-user will spend. Accepts `true` or `false` values.
`isSellAmountWithFees`	If set to `true`, the provided `sellAmount` will include all the fees and the `sellAmount` will be the amount the end-user will spend. Accepts `true` or `false` values.
`address`	defines default wallet address to receive funds at when buying crypto currencies, and default wallet address to refund funds to when selling crypto currencies in case the sell cannot be completed. See details on how to use address below.
`addressSignature`	provides HMAC-SHA-256 signature for `address`. Only used if a shared secret has been established with Coinify. See details on how to use address below.
`walletType`	If this value is not provided via the query parameter, the customer has to provide it on the Trade Widget. Available values: `self_hosted` - provide this value when you know the user is sending the purchased crypto to their own wallet. `vasp` - provide this value when you know the user is sending the purchased crypto to a wallet managed/hosted by a 3rd party like a Centralised Exchange. If this value is provided, `vaspId` must be specified. See how to use walletType below.
`vaspId`	Must be specified if `walletType` is `vasp`. If `vaspId` is set then `walletType` will be inferred as `vasp` and the customer will not be asked to choose from the list of supported VASPs. Get the list of VASP IDs here.
`confirmMessages`	defines if external confirmation of trade messages is required. When provided the widget will await confirmation messages from hosting window before continuing flow. See details on how to use messages below.
`memo`	defines an optional memo/destination tag accepted by some crypto currencies. See details on how to use address below.
`noSignup`	defines whether to support signup through the widget. Note the negation! Available values are 'false' (allow signup for corporate & individuals), 'true' (allow no signup), 'corporate' (allow signup only for individual traders) and 'individual' (allow signup only for corporate traders).
`targetPage`	defines a target landing page other than the default. Available values are 'login', 'signup', 'signup-corporate', 'buy', 'sell' and 'trade-history'
`refreshToken`	used for custom onboarding flows. The `refeshToken`can be obtained by calling one of the auth endpoints. The refreshToken should be URL encoded so that the browsers interprets it correctly.
`transferInMedia`	list of transfer media for inbound payment method. Available: `card`, `bank`, `applepay`,`googlepay`, `blockchain`. See details on how to use.
`transferOutMedia`	list of transfer media for outbound payment method . Available: bank, blockchain. See details on how to use below.
`returnURL`	the URL that you want to redirect the customer to upon successfuly completed trade. The provided URL must be url-encoded. *Note that this query parameter is only available for the Customised Landing Page URL * .

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 transferInMedia are 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.

Improve Trade Widget UX by passing query parameters

By passing some of the parameter values in the Trade Widget URL, specific Trade Widget UI screens will be skipped, effectively simplifying the customer's flow. Please find detailed explanation of which UI screens are skipped based on the provided parameters:

Query Parameter	Description
`transferInMedia`	Providing this parameter will set the payment method accordingly and the customer will not have to select the payment method again on Coinify's Trade Widget.
`buyAmount`; `defaultFiatCurrency`; `defaultCryptoCurrency`	If these parameters are provided together, the Quote page will be skipped.
`address`	Providing this parameter will skip the screen where the customer is asked to provide the receiving crypto address.
`walletType`	If this value is not provided via the query parameter, the customer has to provide it on the Trade Widget.
`vaspId`	If `walletType` is `vasp` and this value is not provided via the query parameter, the customer has to choose among the list of available VASPs on the Trade Widget. To fetch the available VASP IDs and pass it instead of the customer fetch the available VASP IDs here.

If you're already collecting any of these datapoints on your end, it is recommended to pass them as Trade Widget query parameters for a more seamless customer experience. We encourage you to test the flow yourself to get a better understanding of the flow with and without providing these parameters.

How to use `address`

The address parameter should be provided in the format currency1:address1,currency2:address2,... to specify the default wallet address per cryptocurrency. Alternatively, if the widget is configured to have only a single currency, you may provide only the address and omit the currency. See examples:

<iframe src="...?address=BTC:2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD,ETH:0x44eae1E05F5f294f0f2a054D16605993FCd627a9&..." />

<iframe src="...?cryptoCurrencies=BTC&address=2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD&..." />

📘
Good to know:
When Buying a cryptocurrency the address provided for the currency is used to pre-fill the receiving wallet address input field. Equally, when Selling, the address is used to pre-fill the refund wallet address input field. (Note, some cryptocurrencies do not require a refund address to be provided). Buying or Selling currencies with no default address specified will require the end-user to manually enter the wallet address.

How to use `addressSignature`

❗️
Important:
For improved security, it is recommended to use the addressSignature parameter if you've set your system to provide the default receiving address.
Share a UUID format secret with Coinify via a secure channel to enable this feature. Once enabled, our system will refuse to create trades whose addresses do not have a valid signature.

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.

addressSignature follows the same format as the address parameter described above:

Single currency format:
- addressSignature=<sig>
  - ...?cryptoCurrencies=BTC&address=2N7gzbQsDnfAFdwabcFqyw1Q8y1ZUpeqUgD&addressSignature=<sig>
Multiple currencies format:
- addressSignature=BTC:<btcSig>,ETH:<ethSig>
- ...?address=BTC:<btcAddr>,ETH:<ethAddr>&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.

JavaScript example code for generating a signature from the shared secret and `address`

const crypto = require('crypto');

const address = 'crypto-address';
const secret = 'shared-secret';

const accountSignature = crypto.createHmac('SHA256', secret).update(address).digest('hex');

How to use `walletType`

Similar 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.

❗️
The walletType must be correct for a trade to succeed.