The Headless Client

The Halliday Headless Client allows you to build commerce into your application 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.

If you want the simplest means of integrating swaps, please see the Commerce Widget.

Installation

Once you've installed the Commerce SDK, you can import the headless client like so:

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

Initialize the Client

First, create a swap client using your apiKey and initialize it:

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

If you want to test using testnets, you can construct a sandbox client:

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

Authenticate the User

To proceed, you will have to authenticate to the client by having the user sign a message:

await client.login(signer)

Get a Quote

Next, you can create a swap by providing a source of funds sourceAddress and recipient destinationAddress:

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

Now you can 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

At this point, if the user would like to accept the quote, simply call:

await quote.accept()

Alternatively, you may ask for another quote using the same method as above.

You should then make sure 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, you may 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 you may accept or reject:

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, you may resume by getting the active swaps and recovering:

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