Configuring in code

Configure the widget directly in code: every web component attribute and React prop, and how to update them at runtime to adapt to the user or the page.

Most partners should configure these settings visually in Widget Studio and copy the generated snippet, rather than writing attributes by hand. The reference tables here are for when you need to understand or fine-tune a value the snippet produced, maybe to adapt the behaviour to the specific user visiting the site or to the content of the page they are viewing.

Every setting is exposed in two places, and the two map one to one:

• Web component: kebab-case HTML attributes on <swapkit-widget> (e.g. input-asset).

• React: camelCase props on <SwapKitWidget /> (e.g. inputAsset).

You can set them statically in your embed, or set them programmatically so the widget reflects the current context. The full lists are in Full attribute reference and Full props reference.

Updating settings at runtime

This is the main reason to configure in code rather than from a static snippet: you can change the widget to match the user or the page they are on.

HTML

Registered attributes are observed, so setting an attribute with JavaScript re-renders the widget in place. For example, on a token page, preselect that token as the receive asset and narrow the wallet list:

const widget = document.querySelector("swapkit-widget");
widget.setAttribute("output-asset", "ETH.USDT-0xdAC17F958D2EE523A2206206994597C13D831EC7");
widget.setAttribute("wallets", "METAMASK,WALLETCONNECT");

React

Common things to drive dynamically:

• Default assets to match the product, token, or pair the page is about.

• Wallet list to suit the user's region or device.

• Theme to follow a light/dark toggle on the host page.

Caveats:

• Only attributes in the attribute reference are observed; setting an unrecognised attribute has no effect. Every documented attribute (including all theme tokens) re-renders on change.

• Do not swap auth values (widget-id / widget-key / api-key) at runtime in normal use. Set them once.

---

Authentication

The widget supports two mutually exclusive authentication modes.

Mode	Web component	React props	Notes
Widget auth (recommended)	widget-id + widget-key	widgetId + widgetKey	Recommended for all browser embeds. Both values are required together.
API key	api-key	apiKey	Supported, but exposes an API key client-side. Use only in trusted environments.

Behavior to be aware of:

• Both widget values are required. If only one of widget-id / widget-key is present, the widget logs a warning and API requests fail authentication.

• API key takes precedence. If an API key is present alongside a widget pair, the widget uses the API key and clears the widget auth. For public embeds, set only the widget pair.

• Widget auth is domain-bound. Keys are issued for an exact domain (example.com) or a wildcard (*.example.com, which also covers the base domain). The widget only authenticates on the registered domain.

To create a widget key, add a domain, or rotate the key, see Creating your widget keys.

---

Theming

The widget is themed with a set of tokens. Set them with the theme prop (React) or individual color-* / border-radius / font-family attributes (web component).

Color values are HSL channels without the hsl() wrapper, for example 155 86% 62%, not hsl(155 86% 62%). Use the form "H S% L%" or "H S% L% / A" (the / A adds an alpha channel). The widget composes these into hsl(...) internally.

Color tokens

All of these color tokens are observed at runtime. Every one except Accent Text is also exposed in Studio's Design tab and emitted in the generated snippet when changed from its default.

Token

Web component attribute

React theme key

Default

Affects

Background	color-primary	background	140 6% 8%	Main widget background
Surface	color-secondary	surface	120 3% 13%	Elevated surfaces (cards, dialogs)
Accent	color-accent	accent	140 87% 79%	Accent color (steppers, highlights)
Accent Text	color-accent-foreground	accentForeground	140 6% 8%	Text on accent backgrounds
Button	color-primary-button	primaryButton	0 0% 100% / 0.92	Primary button background
Button Text	color-primary-button-foreground	primaryButtonForeground	140 6% 8%	Primary button text
Text	color-text	text	0 0% 100% / 0.92	Main text
Muted Text	color-muted-foreground	mutedForeground	0 0% 100% / 0.64	Secondary text
Border	color-border	border	0 0% 100% / 0.12	Borders
Hover	color-bg-hover	hover	0 0% 100% / 0.08	Hover state
Active	color-bg-active	active	0 0% 100% / 0.12	Active / pressed state
Overlay	color-bg-overlay	overlay	0 0% 0% / 0.8	Modal backdrop overlay

Shape tokens

Token	Web component attribute	React theme key	Default	Affects
Border radius	border-radius	radius	0.5rem	Corner rounding (CSS length, not HSL)
Font family	font-family	fontFamily	system stack	Font applied to the widget root

Example:

HTML

<swapkit-widget
  widget-id="YOUR_WIDGET_ID"
  widget-key="YOUR_WIDGET_KEY"
  color-primary="220 18% 8%"
  color-secondary="220 14% 13%"
  color-accent="155 86% 62%"
  color-primary-button="155 86% 62%"
  color-primary-button-foreground="220 18% 8%"
></swapkit-widget>

React

---

Default assets

You can set which assets the widget loads with. Assets use the format CHAIN.SYMBOL (e.g. BTC.BTC) or CHAIN.SYMBOL-CONTRACT for tokens (e.g. ETH.USDT-0xdAC17F958D2EE523A2206206994597C13D831EC7).

	Web component	React prop	Default
Pay asset	input-asset	inputAsset	BTC.BTC
Receive asset	output-asset	outputAsset	ETH.USDT-0xdAC17F958D2EE523A2206206994597C13D831EC7

These are good candidates for runtime updates: set output-asset (or outputAsset) to whatever token the current page is about.

Chain selection

By default the widget operates on every API-supported chain. You can restrict the set with an allowlist or blocklist. Dropping a chain hides it from the asset selector and auto-disables any wallet whose only chains were removed (for example, removing XRP also removes Xaman).

HTML

There are three attributes, each taking a comma-separated list of chains. Set only one of them. (If you set more than one, the widget uses the first it finds, in the order chains, then chains-include, then chains-exclude.)

Show only the chains you list:

<swapkit-widget chains="BTC,ETH,SOL" ...></swapkit-widget>

chains-include is an alternative way to write that same allowlist:

<swapkit-widget chains-include="BTC,ETH,SOL" ...></swapkit-widget>

Or start from every chain and remove a few, with chains-exclude:

<swapkit-widget chains-exclude="TRON,DASH" ...></swapkit-widget>

To operate on every chain (the default), either omit these attributes or set chains="all".

React

Supported chains

Chain identifiers are the SwapKit chain keys. Unlike wallets, they are case-sensitive on the web component attribute, so pass them exactly as listed. Supported chains:

BTC, ETH, TRON, BSC, SOL, ZEC, XRP, ARB, BASE, OP, POL, AVAX, ADA, GAIA, SUI, NEAR, DOGE, LTC, BCH, DASH, GNO, XLAYER, THOR, MAYA, BERA, MONAD, XRD, KUJI, TON, and STARKNET.

---

Wallet selection

By default the widget shows every available wallet. You can restrict the list with an allowlist or blocklist.

Web component: use one of wallets, wallets-include, or wallets-exclude (mutually exclusive; precedence is wallets, then include, then exclude):

<swapkit-widget wallets="METAMASK,LEDGER,WALLETCONNECT" ...></swapkit-widget>

React: pass the wallets prop:

type WalletConfig =
  | WalletOption[]                  // explicit list
  | "all"                           // every available wallet (default)
  | "none"                          // disable wallet connection
  | { include: WalletOption[] }     // allowlist
  | { exclude: WalletOption[] };    // blocklist

Common WalletOption values: METAMASK, LEDGER, TREZOR, KEYSTORE, WALLETCONNECT, PHANTOM, COINBASE_WEB, COINBASE_MOBILE, XAMAN, RADIX_WALLET, PASSKEYS. But there are more than 20 different wallets.

The visible wallet list is also filtered automatically at runtime:

• Mobile filtering. Hardware wallets and desktop-only extensions are hidden on mobile user agents. Wallets with a mobile path (MetaMask, Coinbase, Phantom) stay visible because they may load inside the wallet's in-app browser.

• Experimental wallets (currently KEEPKEY and VULTISIG) are hidden in production and only surface when Developer Mode is enabled.

• Direct-signing support. A wallet is only shown if it supports at least one widget-supported chain.

---

Wallet-provider credentials

Some wallet providers require additional credentials before they can connect. Fill the corresponding fields in Studio's Settings tab and they are serialized automatically into the generated snippet's config JSON attribute (empty fields are omitted). You rarely need to write this JSON by hand.

Wallet / integration

Required fields

Recommended fields

Where to get it

WalletConnect	apiKeys.walletConnectProjectId	None	https://cloud.reown.com
Xaman (XRPL)	apiKeys.xaman	None	https://apps.xumm.dev
Radix Wallet	integrations.radix.dAppDefinitionAddress, applicationName, applicationVersion	Network ID / Name, Dashboard Base URL (have defaults)	https://console.radixdlt.com
KeepKey	integrations.keepKey.basePath, url	name, imageUrl	https://docs.keepkey.com
Passkeys	apiKeys.passkeys	None	Issued by SwapKit / dashboard
Trezor	None hard-required	integrations.trezor.email, appUrl	https://docs.trezor.io/trezor-suite/packages/connect
Coinbase Wallet	None hard-required	integrations.coinbase.appName, appLogoUrl	https://docs.cdp.coinbase.com/wallet-sdk/docs/installing
NEAR Wallet Selector	integrations.nearWalletSelector.contractId	None	Your NEAR contract/account setup

The config payload

The full shape accepted by the config attribute:

{
  "apiKeys": {
    "walletConnectProjectId": "...",
    "xaman": "...",
    "passkeys": "...",
    "keepKey": "..."
  },
  "integrations": {
    "coinbase": { "appName": "...", "appLogoUrl": "https://..." },
    "nearWalletSelector": { "contractId": "..." },
    "trezor": { "email": "[e-mail]", "appUrl": "https://example.com" },
    "keepKey": { "name": "...", "imageUrl": "https://...", "basePath": "...", "url": "..." },
    "radix": {
      "dAppDefinitionAddress": "...",
      "applicationName": "...",
      "applicationVersion": "...",
      "network": { "networkId": 1, "networkName": "mainnet", "dashboardBase": "https://dashboard.radixdlt.com" }
    }
  }
}

To use it, for the different integration options:

---

Developer settings

These control which environment the widget talks to. Production embeds should omit all of them.

Setting	Web component	React	Notes
API endpoint override	api-base-url	apiBaseUrl	Override the SwapKit API base URL (default https://api.swapkit.dev). Use only for staging/dev.
Developer Mode	develop-mode	None	Boolean attribute. Surfaces experimental wallets and dev behavior, and switches Studio's generated CDN to cdn-dev.swapkit.dev. Omit in production.
Dev API URL	dev-api-url	None	API URL used when Developer Mode is enabled.

A development embed looks like this (note the dev CDN):

<script type="module" src="https://cdn-dev.swapkit.dev/widget/latest/swapkit-widget.js"></script>

<swapkit-widget
  widget-id="YOUR_DEV_WIDGET_ID"
  widget-key="YOUR_DEV_WIDGET_KEY"
  develop-mode
></swapkit-widget>

---

URL sync

Set syncUrl (React) to mirror the selected assets and amount into the page's query string. The parameters are input_asset, output_asset, and amount (for example ?input_asset=BTC.BTC&output_asset=ETH.ETH&amount=0.1). This is a React-only prop; there is no web component attribute for it. Most partner embeds leave it off (default false). It is useful if you want the current selection to survive a reload or be shareable as a link.

---

Full attribute reference (web component)

Attribute	Type	Description
widget-id	string	Widget ID from the dashboard. Pair with widget-key.
widget-key	string	Widget Key from the dashboard. Pair with widget-id.
api-key	string	Alternative auth mode. Takes precedence over widget auth.
api-base-url	URL	Override the SwapKit API base URL.
develop-mode	boolean	Enable development behavior. Presence (or "true") is treated as enabled.
dev-api-url	URL	Development API URL used when develop-mode is set.
input-asset	asset string	Initial pay asset. Default BTC.BTC.
output-asset	asset string	Initial receive asset. Default Ethereum USDT.
wallets	all, none, or CSV	Restrict which wallet options are shown.
wallets-include	CSV	Explicit allowlist.
wallets-exclude	CSV	Blocklist, showing all wallets except these.
chains	all or CSV	Restrict which chains the widget operates on.
chains-include	CSV	Explicit chain allowlist.
chains-exclude	CSV	Chain blocklist, showing all chains except these.
config	JSON string	SDK config patch for wallet/provider credentials.
sentry-dsn	string	Override the bundled telemetry DSN (web component only).
color-*	HSL string	Color theme tokens. See Theming.
border-radius	CSS length	Corner rounding. See Theming.
font-family	font stack	Widget font. See Theming.

Registered attributes are observed: mutating one re-renders the widget.

Full props reference (React)

Prop	Type	Default	Description
widgetId	string	None	Widget ID. Pair with widgetKey.
widgetKey	string	None	Widget Key. Pair with widgetId.
apiKey	string	None	Alternative auth mode. Takes precedence over widget auth.
apiBaseUrl	string | null	https://api.swapkit.dev	Override the API base URL. Missing schemes are normalized.
inputAsset	string | null	BTC.BTC	Initial pay asset.
outputAsset	string | null	ETH.USDT-0x…	Initial receive asset.
theme	SwapKitThemeTokens	None	Theme tokens (colors, radius, fontFamily). See Theming.
colors	SwapKitThemeTokens	None	Deprecated alias for theme, kept for backwards compatibility.
wallets	WalletConfig	"all"	Wallet allow/deny configuration.
chains	ChainConfig	"all"	Chain allow/deny configuration.
config	{ apiKeys?; integrations? }	None	SDK credentials payload for wallet providers.
developMode	boolean	false	Enable developer mode (experimental wallets, dev API URL).
devApiUrl	string | null	None	API URL used when developMode is true.
className	string	None	Extra class name on the widget root.
disableTelemetry	boolean	false	Disable the widget's Sentry telemetry.
syncUrl	boolean	false	Sync selected assets and amount to URL query params.

The React component exposes disableTelemetry rather than a DSN override; sentry-dsn exists only on the web component path.

---

Troubleshooting

API requests fail authentication. Confirm that either api-key is present, or both widget-id and widget-key are present. For dashboard-created embeds, prefer the widget pair.

Works locally but fails in production. Confirm the production domain matches the domain registered under Widget Keys, and that you did not include https:// when creating the domain key.

A rotated key stopped the widget. Update the deployed snippet with the new Widget Key. The old one stops working immediately after rotation.

A wallet does not appear. Check wallets / wallets-include / wallets-exclude, confirm the wallet supports at least one widget-supported chain, and note that hardware and desktop-only options are hidden on mobile and experimental wallets are hidden outside Developer Mode.

Custom colors do not apply. Use HSL channel values without hsl(): 155 86% 62%, not hsl(155 86% 62%).

The widget renders unstyled (React). Import @swapkit/ui/swapkit.css once at your app root.