Trade Widget

Supported query parameters

The widget supports a number of configuration options defined using query parameters.

🚧

Important:

Every parameter has to be encoded to be used in the URL. E.g. using encodeURIComponent(yourParameter) in JS.

Skip Trade Widget UI screens:

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:

• Passing the transferInMedia will set the payment method accordingly and the customer will not have to select the payment method again on Coinify's Trade Widget.
• If buyAmount,defaultFiatCurrency, and defaultCryptoCurrency are provided, the Quote UI will be skipped.
• Providing the address value will skip the screen where the customer is asked to provide the receiving crypto address.

If you're already collecting any of this datapoints on your end, it is recommended to pass these values to Coinify's Trade Widget 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.

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)
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 ony 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.
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.
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 refeshTokencan 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, blockchain. See details on how to use below.
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.

Address signature

JavaScript

// Javascript example of how to generate signature from 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');

In order to ensure that the address passed into the widget has not been tampered with, we have the possibility for you to sign the address(es) using a shared secret, and passing the signature to the widget as well.

Widget Sizes

Trade Widget Sandbox Testing

In order to test trades in the Trade Widget, use the widget's sandbox environment base URL. Transactions completed in the sandbox environment have no value. Complete flow for Buy trades is available only for USDC on Ethereum's Sepolia testnet and BTCt on BTC testnet3 network. However, the complete Sell trades flow in sandbox is available only using the BTC testnet3 network.

Currency	Network	Wallet Setup Tutorial
USDC	Sepolia testnet	[Metamask Sepolia and USDC Setup] (https://help.coinify.com/hc/en-us/articles/10101842554012). Recommended for Buy Trade testing.
BTCt	Testnet3	[Bitcoin Testnet Wallet Setup] (https://help.coinify.com/hc/en-us/articles/4406615449500). Recommended for Sell Trade testing.

Use test credit card details to complete card buy trades

Use fake bank transfer API endpoint to complete bank buy trades

Buy Button

Buy Button is a simple web component that opens up trade widget in a 768x576 popup.

How to use

Add the following code into your web page:
for sandbox

HTML

  <script src="https://trade-ui.sandbox.coinify.com/components/buy-button.js"></script>
  ...
  <buy-button
        url="https://trade-ui.sandbox.coinify.com?partnerId={replace-with-assigned-id}&primaryColor=blue&cryptoCurrencies=BTC,ETH,XLM"
      />

for production

HTML

  <script src="https://trade-ui.coinify.com/components/buy-button.js"></script>
  ...
  <buy-button
        url="https://trade-ui.coinify.com?partnerId={replace-with-assigned-id}&primaryColor=blue&cryptoCurrencies=BTC,ETH,XLM"
      />

url property points to the trade widget just as in the example.

🚧

The partnerId queryString parameter must be set to the proper value so that users can be registered with your company.

Styling the Buy Button

Custom CSS properties exposed

Property	Description
background-color	color of the button
color	color of the text

Style using custom CSS properties

HTML

  <style type="text/css">
    buy-button {
      --background-color: #8fc065;
    }
  </style>

Style using CSS

CSS

  buy-button button {
    background-color: #8fc065;
  }