Trade Widget

Basic setup

Add an iframe element to your page pointing to the Trade Widget URL, with your partnerId as a required query parameter:

<!-- Sandbox -->
<iframe
  src="https://trade-ui.sandbox.coinify.com?partnerId={your-partner-id}"
  width="100%"
  height="576px"
  allow="camera;fullscreen;accelerometer;gyroscope;magnetometer;payment"
  allowfullscreen>
</iframe>

<!-- Production -->
<iframe
  src="https://trade-ui.coinify.com?partnerId={your-partner-id}"
  width="100%"
  height="576px"
  allow="camera;fullscreen;accelerometer;gyroscope;magnetometer;payment"
  allowfullscreen>
</iframe>

Widget dimensions

The widget is responsive and adjusts its layout to the available width:

The minimum recommended height is 576px. Increasing the height stretches the widget and hides scrollbars on text-heavy pages like Trade Details. There is no maximum width, but a minimum of 320px is required — on the smallest mobile screens, avoid adding horizontal margin or padding around the widget.

Query parameters

Configure the widget's behaviour and appearance by appending query parameters to the URL.

Every query parameter must be URL-encoded, e.g. using encodeURIComponent() in JavaScript.

Partner configuration

Look & feel

Currencies

Trade amounts

Wallet address

Navigation & access

Payment methods

Return URL

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:

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:

How to use address

For 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 addressSignature and memo.

Securing the address with a signature

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.

Generate the signature using HMAC-SHA-256:

const crypto = require('crypto');

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

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

Then pass both address and addressSignature as query parameters.

addressSignature is an opt-in feature and requires a shared secret to be established with Coinify first.

Customised Landing Page

Coinify can provision a dedicated landing page URL for your Trade Widget with custom branding — your logo, brand colours, browser tab title, and page URL path. To set this up, contact Coinify through your dedicated communication channel and provide

• Partner Title — browser tab title (e.g. Crypto Company)
• Partner Name — defines the URL path (e.g. https://trade.coinify.com/YourCompanyName)
• Primary Colour — button colour (e.g. #4231c8)
• Light & Dark Colour — gradient background colours behind the widget
• Logo — an .svg file of your logo
• Website URL — linked behind your logo on the landing page

The returnURL query parameter is exclusively available on the Customised Landing Page, allowing you to redirect users back to your product after a completed trade.

Next steps

• Frictionless Sign-up Flow → — silently onboard your users without a Coinify sign-up screen
• Frictionless Sign-in → — pass an authenticated session into the widget via refreshToken
• Enable Apple Pay → — additional setup steps required for Apple Pay
• Trade Widget SDK → — prefer a JavaScript-based integration over a raw iframe