// embeddable

// SCORE BADGE WIDGET

Show a SybilShield decision inline on your own claim page, airdrop checker, or DAO dashboard — one script tag, no backend integration.

Scope — read this first. By default the widget shows whatever decision SybilShield already has on record for an address; it does not run a fresh analysis and does not block anything on your page — it's a display badge, not a gate. An address nobody has ever submitted to SybilShield shows honestly as "Not yet scored", never a false "clean" result. An opt-in data-sybilshield-first-sight attribute (below) changes that for addresses with it set — see that section before enabling it.

// embed

<!-- Put this where you want the badge to appear -->
<span data-sybilshield-address="0xd8da6bf26964af9d7eed9e03e53415d37aa96045"></span>

<!-- Once per page, anywhere -->
<script src="https://www.sybilshield.org/widget.js" async></script>

Every element with data-sybilshield-address on the page gets its own badge — safe to use in a list of many addresses.

// opt-in: score on first sight

Add data-sybilshield-first-sight to an element and an unscored address gets a real, synchronous scoring call instead of always showing "Not yet scored":

<!-- Opt-in: score a never-before-seen address on the spot -->
<span
  data-sybilshield-address="0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
  data-sybilshield-first-sight
></span>

This runs real on-chain ingestion (Ethereum mainnet only) the first time any given address is seen — it costs real time (typically a couple of seconds, shown as "Scoring…") and real capacity, so it's rate-limited per-origin and globally shared with SybilShield's batch analysis capacity. If the budget is spent, it degrades to the same honest "Not yet scored" state rather than erroring. Because a fresh address has no batch of peers to compare against yet, its confidence is capped lower than a full analysis's — treat it as an early signal, same caveat as any other SybilShield score. Off by default for exactly this reason: existing embeds that copy-pasted the plain snippet above don't silently start driving this cost.

// states

Badge	Meaning
Looks clean	Decision is KEEP, or no decision on record but sybil_score is low
Under review	Decision is REVIEW — uncertain, not confirmed
Sybil risk flagged	Decision is DROP, or no decision but sybil_score ≥ 70
Not yet scored	The address has never been part of any SybilShield analysis
Unable to check	Network error — the widget degrades honestly instead of guessing

// options

data-sybilshield-api — point at a self-hosted SybilShield API instead of the public sandbox. Defaults to https://api.sybilshield.org.
data-sybilshield-first-sight — opt-in real-time scoring for unscored addresses. See the section above before enabling it.

// under the hood

One GET /v1/score/:address call per badge, against the same free, unauthenticated, public endpoint documented on /docs — falling back to a POST /v1/score/first-sight call only when the opt-in attribute is set and the address is unscored. No API key, no cookies, no tracking — the widget only talks to the SybilShield API (or your self-hosted override) and nothing else.

// next_steps

› Full API reference
› Methodology — how a decision is computed
› Run an analysis — score a cohort so the widget has something to show