Integration FAQ

Questions specific to the embed widget SDK. For general protocol questions see the top-level FAQ.

Do I need a server to run this widget?

No. The widget is fully client-side. You drop a script tag (or import a React component) onto your existing site and the widget renders inside an iframe. No backend, no API keys to manage.

What referralId format should I use? Hex hash or vanity slug?

Both work. 8-hex-char hashes (for example 6fb85213) are used directly. Anything else is treated as a vanity slug and resolved against the dapp's slug mapping to the underlying hash. Most validators paste the hash shown on their validator self-serve page on atomcircuit.net. Vanity slugs work too if you registered one. Unknown slugs are stored as-is for forward compatibility but the widget's validity check rejects them until they exist in the slug mapping.

Can the widget access my page's data (cookies, storage, DOM)?

No. The iframe runs in a sandbox with allow-same-origin (required for Keplr to inject window.keplr) but the cross-origin browser boundary prevents the widget from reading the host page's DOM, cookies, or localStorage. The exact sandbox attribute list is defined in src/mount.ts in the SDK repo.

Does the widget work on mobile?

Yes for the Keplr in-app browser and for most standalone mobile browsers via WalletConnect. Cold-start signing in some mobile browsers (notably iOS Safari with WalletConnect) can time out after 90 seconds; the widget surfaces this as a "Signing timed out, copy link to Keplr app" prompt.

Can I change the widget's colors, fonts, and corner roundness?

Yes. Pass a theme object with mode, accentColor, background, foreground, border, radius, fontSize, fontFamily. See the Embed Widget page for the full surface and a themed example.

Can I hide the logo or wallet button?

Yes. Pass chrome: { logo: false, wallet: false, validator: false, footer: false }. Each flag defaults to true, so a no-config embed shows the full chrome. See the Embed Widget page for the full chrome surface.

Where do swap fees go and how much?

The current affiliate fee is 50 bps (0.5%) of swap output. The fee routes through Skip Go to the protocol's collector wallets, gets converted to ATOM on Cosmos Hub, and is delegated to the validator whose referralId you passed at mount time. See the Fee Flow page for the full pipeline.

What if my referralId is wrong, missing, or stale?

If referralId is missing, the widget renders an inline "Embed configuration error" message and refuses to render the swap form. If it is present but does not resolve to a known validator (not the 8-hex pattern, not the general sentinel, not a registered slug), the widget renders an "Invalid referral" message instead. Fees never route to an unknown validator. Test your referralId on a staging copy of your page before publishing.

Does the widget make any third-party requests beyond the swap API?

Only requests originated by the dapp loaded inside the iframe (Skip Go for routing, Cosmos REST endpoints for balances, the chain registry for asset metadata). The SDK itself does not make analytics, telemetry, or tracking calls. Verify by inspecting Network DevTools after onReady fires.

How do I get notified when a user completes a swap?

Pass onSwapSuccess to the SDK. It fires once per successful cross-chain delivery with { txHash } (the source-chain transaction hash). See the Embed Widget Callbacks section for the full event list.

Why is my widget still showing an old version after I updated the npm package?

If you embed via the unpkg CDN, browser cache or unpkg cache can hold the previous bundle for several minutes. Either bump your pinned version (bump the patch suffix) or use a cache-busting query param (?v=<git-sha>). If you bundle via npm install, run npm update and rebuild.

What browsers are supported?

Chromium 115+, Firefox 115+, Safari 16+. iOS Safari 16+ and Android Chrome 115+ on mobile. The widget targets the ES2020 baseline; older browsers without that baseline are not supported.

Where do I report bugs or request features?

Open an issue on the SDK repository: github.com/cosmosrescue/atom-circuit-embed-sdk/issues. For security issues, follow the private disclosure process documented in SECURITY.md on the repo.

How do I know the SDK on unpkg is the same as the published npm package?

Use Subresource Integrity. The release publishes a sha384-... hash for the IIFE bundle; the browser refuses to execute the bundle if the served bytes do not match the hash. See the Security Model section in the Embed Widget page for the script tag form.