Widget customization reference

The LayerHop widget is the swap card served at https://layerhop.com/embed, configured entirely through URL parameters and reporting back to your page with postMessage events. This page lists every parameter, option and event of embed protocol 1.1 (ready.version is 1.1.0); for a step-by-step setup see Embed the widget, or design it visually in the widget builder.

How are parameters validated?#

Each parameter is checked on its own. The embed ignores an invalid value and uses that parameter's default, so a typo never breaks the card. The contract is additive: parameters and events are only ever added, never renamed or removed.

The @layerhop/widget package is stricter: buildEmbedUrl(), mount() and <LayerHopWidget /> throw a LayerHopWidgetError on an invalid option, so integration mistakes show up during development.

Swap parameters#

These are the same parameters as a swap deep link.

The embed always quotes on the widget fee channel (0.30% LayerHop fee). A registered partner's fee is added on top and shown as its own line.

Theme parameters#

Focus rings always use a color with at least 3:1 contrast on the card: the accent, then success, then text.

Content and behaviour parameters#

When an allow-list or a locked recipient rules out the linked or default tokens, the card starts on the first allowed asset. Allow-lists also apply to wallet-based defaults, the flip button and setParams.

How do package options map to URL parameters?#

@layerhop/widget options use the URL parameter names, with these exceptions:

Options that only exist in the package (they never reach the URL):

For the <script> tag, every option is a kebab-case data- attribute on an element marked data-layerhop-widget: srcChain → data-src-chain, borderColor → data-border-color. Lists are comma-separated. A flag is on when the attribute is empty, 1, true or yes, and off with 0.

Which events does the widget send?#

The embed posts { source: "layerhop", type, payload } to window.parent with target origin "*". Payloads never contain secrets.

routes, walletConnected, walletDisconnected and amountChanged were added in protocol 1.1. With the script tag, each event is also dispatched on the host element as a bubbling DOM CustomEvent named layerhop:<type>, with the payload in event.detail.

Always check event.data.source === "layerhop" and, in production, event.origin === "https://layerhop.com". A connected wallet address is public data, but walletConnected does tell your page which address connected.

How does the host page control the widget?#

Parent → embed messages are opt-in. The embed only listens when its URL has allowParentOrigin, and only accepts a message when event.origin equals that origin exactly and event.source is its parent window.

iframe.contentWindow.postMessage(
  { source: "layerhop-host", type: "setParams", payload: { amount: "250", dstToken: "USDT", accent: "38bdf8" } },
  "https://layerhop.com",
);

Other keys and invalid values are ignored. Locks and allow-lists still apply: a locked side or a locked amount ignores changes. The integrator, recipient, locks and fees can never be changed this way.

With the package, mount(el, { liveUpdates: true }) sets allowParentOrigin for you, and widget.update() sends setParams for the live keys above and reloads the iframe only when another option changed.

What iframe settings does the widget need?#