Headless Client Quickstart

The Halliday Headless Client allows developers to build commerce into DApps without rendering any Halliday UI elements.

It provides a maximally flexible integration, enabling developers to build custom swap interfaces or integrate swap functionality into existing systems without a predefined UI. This powerful API comes with additional complexity which is discussed in this document.

To get the simplest means of integrating swaps, see the Commerce Widget documentation.

Installation

First, install the Halliday SDK in the root folder of a web project.

npm install @halliday-sdk/commerce

Next, import the Halliday SDK into an existing application.

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

Initialize the Client

First, create a swap client using an account's apiKey.

const client = await HallidaySwapClient.create({ apiKey })

To use testnets, construct a sandbox client.

const client = await HallidaySwapClient.create({ apiKey, useSandbox: true })

Authenticate the User

Authenticate to the client by prompting the user to sign a message.

await client.login(signer)

Get a Quote

Next, create a swap by providing a source of funds sourceAddress and recipient destinationAddress.

const swap = await client.createSwap({ sourceAddress, destinationAddress })

Fetch a quote for a given inputToken, outputToken, and inputAmount.

const quote = await swap.getQuoteExactInput({ inputToken, outputToken, inputAmount })

Accepting a Quote and Funding the Swap

If the user chooses to accept the quote, call the accept method on the quote object.

await quote.accept()

Alternatively, the user can request another quote using the same method as above.

Next, ensure the user approves or transfers in any necessary funds to perform the swap.

const approvalReqs = quote.approvalNeeded()
const transferReqs = quote.transferInNeeded()

The approvalReqs will describe the amount and token needing approval, if necessary. The transferReqs will describe the amount and token needing to be transferred in, if necessary.

Finally, wait for the swap to complete. In the event that the quote can no longer be obtained without slippage, new adjusted quotes will be provided that can be accepted or rejected.

for await (const newQuote of quote.acceptAndWait()) {
 if (await user.ask(newQuote))
  newQuote.accept()
 else
  newQuote.reject()
}

Recovering from Session Interruptions

If a session is interrupted by closing the browser window, it can be resumed by getting the active swaps and recovering.

const swaps = await client.getActiveSwaps()
// ...
const swap = await client.recover({ swapId })
await swap.execute()
await swap.wait()