Guides

Trade Widget SDK

The Trade Widget SDK is a JavaScript library that initialises the same Coinify-hosted trading UI as the iframe embed, but programmatically. Instead of constructing a URL with query parameters, you configure the widget through a JavaScript API — and crucially, you get two-way communication between the widget and your app through events and messages.

Choose the SDK over the plain iframe when:

  • You need to react to trade events in your own app logic
  • You want to pass complex parameters like address or partnerContext as objects rather than URL-encoded strings
  • You're using Frictionless Sign-in and want a cleaner, menu-free widget experience

Setup

Load the SDK script in your HTML:

<!-- Sandbox -->
<script src="https://trade-ui.sandbox.coinify.com/widget/sdk/v1/trade.js"></script>

<!-- Production -->
<script src="https://trade-ui.coinify.com/widget/sdk/v1/trade.js"></script>

Add a container element for the widget to render into:

<div id="coinify-widget"></div>

Initialisation

Initialise the widget with your partner configuration, register any event listeners, then call .render():

const widget = Coinify.Trade({
    partnerId: 'your-partner-id',   // required
    partnerName: 'Your App Name'    // required
  })
  .on('trade.trade-prepared', (e) => console.log('Trade prepared:', e))
  .on('trade.trade-created', (e) => console.log('Trade created:', e))
  .on('trade.trade-placed', (e) => console.log('Trade placed:', e))
  .render({
    containerId: 'coinify-widget',
    parameters: {
      refreshToken: 'end-user-refresh-token',
      targetPage: 'buy',
      noMenu: true,
      address: { BTC: 'your-btc-address', ETH: 'your-eth-address' },
      partnerContext: { clientId: 123 }
    }
  });

The parameters object accepts the same configuration options as the iframe query parameters — currencies, amounts, payment methods, wallet address, theme, and so on. See Supported Query Parameters → for the full reference.

SDK-specific parameters

Two parameters are only available in the SDK (not the iframe):

ParameterDescription
noMenuSet to true to hide the burger menu. Recommended when using Frictionless Sign-in, where a separate login screen would be redundant.
addressPassed as a JavaScript object ({ BTC: 'address', ETH: 'address' }) rather than a URL-encoded string.

Listening to widget events

The widget emits three events you can listen to via .on():

EventWhen it fires
trade.trade-preparedThe user has reviewed the trade, before it is created in the backend. Contains a partial trade object.
trade.trade-createdThe trade has been created in the backend. Contains the full trade object.
trade.trade-placedThe user has completed placing the trade and returned to the quote page. Contains the tradeId.

A common use case for trade.trade-prepared is validating the wallet address before the trade is confirmed — see Sending messages to the widget below.

Sending messages to the widget

You can send messages back to the widget using widget.send(). This is useful when you need your app to confirm or reject a trade before it proceeds.

To enable this flow, pass confirmMessages: true in your parameters — the widget will then pause at key points and wait for your confirmation before continuing.

// Confirm or reject a prepared trade (before it's created in the backend)
widget.send('trade.confirm-trade-prepared', { confirmed: true });

// Confirm or reject a created trade (before the user is prompted to pay)
widget.send('trade.confirm-trade-created', { confirmed: true, tradeId: 123456 });

// Update the partner context dynamically at any point
widget.send('settings.partner-context-changed', {
  partnerContext: { clientId: 123, updatedAt: new Date().toISOString() }
});

For the full message payload reference, see Sending/Receiving Widget Messages →.

Next steps