The Halliday Payments Widget allows users to perform onramps, swaps, and exchange withdrawals to or from any chain or token with minimal integration effort. It provides the most rapid integration of Halliday Payments with a feature-rich configuration. To have more fine-grained control over the user interface, review the Halliday API documentation.

Installation

Install the Payments SDK, which is available on NPM.
npm install @halliday-sdk/payments
Next the SDK can be imported into a front-end TypeScript or JavaScript project.
copy
import { openHallidayPayments } from '@halliday-sdk/payments'

Options

The openHallidayPayments function opens the Halliday Payments widget and accepts the following configuration options:
NameTypeDescription
apiKeystringYour API key for authorization.
outputsAsset[]The output assets for the widget.
sandboxbooleanWhether the widget is in sandbox mode. Defaults to false.
destinationAddress (optional)stringThe address of the destination of the widget.
inputs (optional)Asset[]The input assets for the widget.
onramps (optional)string[]The onramp providers to use.
offramps (optional)string[]The offramp providers to use.
customStyles (optional)object (CustomStyles)Custom styles for the widget. See customizing styles.
targetElementId (optional)stringThe ID of the DOM element where the widget should be embedded. Required if windowType is “EMBED”.
windowType (optional)“POPUP” | “EMBED”The desired display mode of the widget. Defaults to “POPUP”.
owner (optional)OwnerOwner wallet configuration with address and signing functions.
funder (optional)FunderFunder wallet configuration with signing functions.
statusCallback (optional)functionCallback to receive status events.

Type Definitions

type Asset = string; // Format: "chainId:tokenAddress" or native token identifier or fiat symbol

interface CustomStyles {
  primaryColor?: string;
  backgroundColor?: string;
  /**
   * In popup mode, the border only shows when the window is resized and made larger.
   * If you would like there to be no border at all, you can set it to the same color as backgroundColor.
   */
  borderColor?: string;
  textColor?: string;
  textSecondaryColor?: string;
  logo?: {
    src: string; // URL of the logo image
    alt: string;
    width: number;
    height: number;
  };
}

interface Owner {
  address: string; // Wallet address
  signMessage?: (input: {
    message: string;
    ownerAddress?: string;
  }) => Promise<string>;
  sendTransaction?: (
    transaction: TransactionRequest,
    chainConfig: EVMChainConfig
  ) => Promise<TransactionReceipt>;
  signTypedData?: (input: {
    typedData: string;
    ownerAddress?: string;
  }) => Promise<string>;
}

interface Funder {
  signMessage?: (input: {
    message: string;
    ownerAddress?: string;
  }) => Promise<string>;
  sendTransaction?: (
    transaction: TransactionRequest,
    chainConfig: EVMChainConfig
  ) => Promise<TransactionReceipt>;
  signTypedData?: (input: {
    typedData: string;
    ownerAddress?: string;
  }) => Promise<string>;
}

interface TransactionRequest {
  to: string;
  from?: string;
  nonce?: number;
  gasLimit?: bigint;
  gasPrice?: bigint;
  maxPriorityFeePerGas?: bigint;
  maxFeePerGas?: bigint;
  data?: string;
  value?: bigint;
  chainId: number;
}

interface TransactionReceipt {
  transactionHash?: string;
  blockHash?: string;
  blockNumber?: number;
  from?: string;
  to?: string;
  rawReceipt: any;
}

interface EVMChainConfig {
  chain_id: number;
  network: string;
  native_currency: {
    name: string;
    symbol: string;
    decimals: number;
  };
  rpc: string;
  image: string;
  is_testnet: boolean;
  explorer: string;
}

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.
copy
import { openHallidayPayments } from "@halliday-sdk/payments";

openHallidayPayments({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    // USDC on Base
    outputs: ["base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"],
    sandbox: false,
});

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. You can use the connectSigner utility function to prepare your app’s signer (works with Ethers) for use with Halliday, which will return the necessary signing and transaction functions. 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.
copy
import { openHallidayPayments } from "@halliday-sdk/payments";
import { connectSigner } from "@halliday-sdk/payments/ethers"

const connectedSigner = connectSigner(YOUR_ETHERS_SIGNER);

openHallidayPayments({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    // USDC on Base
    outputs: ["base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"],
    sandbox: false,
    owner: connectedSigner,
    funder: connectedSigner
});

Embedding as an iframe

By default, the Payments 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.
copy
import { openHallidayPayments } from "@halliday-sdk/payments";

openHallidayPayments({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    // USDC on Base
    outputs: ["base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"],
    sandbox: false,
    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 Payments Widget in order to match an application’s existing user interface.
copy
import { openHallidayPayments } from "@halliday-sdk/payments";

openHallidayPayments({
    apiKey: HALLIDAY_PUBLIC_API_KEY,
    // USDC on Base
    outputs: ["base:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"],
    sandbox: false,
    customStyles: {
     primaryColor: '#444',
     backgroundColor: '#000',
     borderColor: 'rgba(0, 0, 0, 1)',
     textColor: '#008000',
     textSecondaryColor: '#fafab9',
    },
    // ...
});
The following diagram shows how these values are used:
For further customization or to get access to the Halliday API documentation, please contact the Halliday team.