Quickstart

This guide takes you from zero to a working embed in under five minutes. You'll need:

  • A Wallet Sleuth tracking page that you own (or are a member of).
  • Shell access to the site where you'll paste the iframe.

1. Enable embedding on the tracking page

In the Wallet Sleuth dashboard, open your tracking page, go to Settings → Embed API, and make sure the page is set to Public and Embed enabled. The embed widget reads both flags; if either is off the iframe renders an error page.

2. Create a public API key

In the same Embed API section, click New key and pick Public. You'll be asked for:

  • Label — human-readable name. Shown to you in the dashboard; never sent to visitors.
  • Allowed origins — the list of origins (scheme + host + port) where your iframe will be embedded. For example: https://example.com, https://staging.example.com.

The key is shown once, at creation time. Wallet Sleuth stores only a secure hash, so you cannot retrieve it later. Copy it into your secrets manager or snippet now.

Public keys look like ws_pub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. The prefix encodes the tier; see Authentication.

3. Paste the snippet

The dashboard generates a ready-to-ship iframe snippet. It looks like this:

<iframe
  src="https://walletsleuth.app/embed/tracking/YOUR_PAGE_ID?key=ws_pub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  width="100%"
  height="600"
  frameborder="0"
  allow="clipboard-write"
  style="border-radius: 12px;"
></iframe>

Drop it into any page served from an allowed origin. The widget will load and render the token header, wallet table, and submission form.

4. Verify the embed is working

Open the page in a browser. You should see:

  • The token name and symbol in a header (e.g. "Jobcoin $JOBC").
  • A table of tracked wallets with tags and balances.
  • A Submit a wallet button that expands into a signing form.

If you instead see an error message, it's almost always one of:

SymptomCauseFix
"invalid_key" or blank error pageKey is wrong, revoked, or belongs to a different tracking page.Re-copy the key; confirm the page ID in the URL matches the key's tracking page.
Iframe loads but browser console says "refused to frame"Your site's origin isn't in the key's allowlist.Add the origin in Settings → Embed API → API Keys.
"missing_key_or_page"The ?key=... query parameter is missing.The iframe src must include the key.

5. Checklist before going live

  • Origin allowlist covers every host, including staging, preview URLs, and any subdomain that will frame the widget. Wildcards are not supported; add each origin explicitly.
  • No X-Frame-Options: DENY or restrictive frame-ancestors on the page that frames the iframe. Wallet Sleuth sets its own Content-Security-Policy: frame-ancestors <allowed origins> on the iframe response, so the iframe itself will only load inside allowlisted parents. Your parent page's CSP does not need to mention walletsleuth.app, but must not block iframes outright.
  • Public key, not secret key. Secret keys (ws_sec_…) will be rejected by the iframe route. Never expose a secret key in client-side HTML.
  • HTTPS everywhere. The session cookie used by the submission flow is set with SameSite=None; Secure, which requires HTTPS parent + iframe.

What next?