Commerce Widget Quickstart

The Halliday Commerce Widget allows users to perform onramps, swaps, and exchanges withdrawals to or from any chain or token with minimal integration effort.

It provides the most rapid integration of Halliday with a feature-rich configuration.

To have more fine-grained control over the user interface, review the Headless Client documentation.

Installation

Install the Commerce SDK, which is available on NPM.

npm install @halliday-sdk/commerce

Next the SDK can be imported into a front-end TypeScript or JavaScript project.

import { openHalliday } from '@halliday-sdk/commerce'

Options

The openHalliday function accepts in the following configuration options:

Name	Type	Description
`apiKey`	string	The API key. Visit dashboard.halliday.xyz (opens in a new tab) to create one.
`destinationBlockchainType`	string	The blockchain of the target token to receive.
`destinationCryptoType`	string	The alias of the target token to receive.
`destinationAddress` (optional)	string	The token recipient address. Default is the signer address.
`getSigner` (optional)	() => Signer (opens in a new tab)	Function returning the embedded wallet signer to sign the authentication message. If not set, prompts user to connect wallet.
`services` (optional)	string[]	The services to allow. Each one of "ONRAMP", "SWAP", "EXCHANGE" or "OFFRAMP". Default is all services.
`userId` (optional)	string	Identifier for the user. Default is the signer address.
`useSandbox` (optional)	boolean	Whether to use testnets and the like, or operate for real. If set to true, use a sandbox API key. Default is false.
`windowType` (optional)	string	Either "POPUP" or "EMBED". Default is "POPUP".
`targetElementId` (optional)	string	The HTML element id to render the embedded iframe inside of. If set, `windowType` must be "EMBED".
`customStyles` (optional)	object	Custom styles for the widget. See customizing styles.

The meaning of these options and how they are typically used together is described in the sections that follow.

Usage Patterns

Using the wallet connector

Halliday can prompt users to choose a wallet to connect to the DApp. The wallet connector provides many options including MetaMask, Coinbase Wallet, Phantom, or Wallet Connect.

Clicking the button will trigger the connect-wallet prompt. If the application already prompts the user to connect a wallet, see using a connected wallet.

Try out onramping to an external wallet with this button:

import { openHalliday } from "@halliday-sdk/commerce";
 
openHalliday({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    // Arbitrum
    destinationChainId: 42161, 
    // USDC on Arbitrum
    destinationTokenAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", 
    services: ["ONRAMP"],
});

Using a connected wallet

Halliday can accept a wallet connection that the DApp has already established. With this flow, the user connects their wallet using the application's original flow. The DApp can pass a getSigner function that returns the connected wallet signer to the Halliday SDK for authentication.

This offers an enhanced user experience for Web3 applications, since users do not need to re-connect their wallet using the Halliday external wallet modal. If the application does not already have a connected wallet, see using the wallet connector.

Try out onramping to a demo embedded wallet with this button:

Temporary, TEST ONLY, signer address: ⚠ WARNING: The above wallet is in-memory and will dissapear on page-reload. This is just for demonstration purposes.

import { openHalliday } from "@halliday-sdk/commerce";
 
openHalliday({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    // Arbitrum
    destinationChainId: 42161, 
    // USDC on Arbitrum
    destinationTokenAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", 
    services: ["ONRAMP"],
    getSigner: () => connectedWalletSigner, // The signer for the previously connected wallet
});

Embedding as an iframe

By default, the commerce widget opens in a separate window or tab. Another option is embed it within a page using an iframe. This can be done by providing two additional options: windowType and targetElementId.

When using the iframe mode, the commerce widget will show up like this:

Temporary, TEST ONLY, signer address: ⚠ WARNING: The above wallet is in-memory and will dissapear on page-reload. This is just for demonstration purposes.

import { openHalliday } from "@halliday-sdk/commerce";
 
openHalliday({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    // Arbitrum
    destinationChainId: 42161, 
    // USDC on Arbitrum
    destinationTokenAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", 
    services: ["ONRAMP"],
    windowType: "EMBED",           // Enable the embedded iframe mode
    targetElementId: "element-id", // The HTML element id to render the iframe inside of
});

Customizing styles

Halliday supports setting custom styles on the commerce widget in order to match an application's existing user interface.

import { openHalliday } from "@halliday-sdk/commerce";
 
openHalliday({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    customStyles: {
     primaryColor: 'black',
     backgroundColor: '#fff',
     borderColor: 'rgba(0, 0, 0, 1)',
     textColor: 'green',
     textSecondaryColor: '#fafab9',
     logo: {
      src: 'https://example.com/images/logo.png',
      style: {
       height: '20px',
       width: '167px',
      },
     },
    },
    // ...
});

The following diagram shows how these values are used:

For further customization, consider using the Headless Client, or speak with the Halliday team about specific requirements.

Halliday Hello World Quickstart: Headless Client