Drop in the badge

What you will end up with

A live trust badge sitting wherever you place it. No backend on your side, no wallet popup for your users, no API key. This is the fastest way to ship TrustGate. There are two scripts.

Script	Use when
`widget.js`	One ERC-20 input or one known token name
`widget-discovery.js`	A list, a search page, a launchpad feed

They are additive. They do not share state.

Load the script once

Add this anywhere on the page. One include covers every badge on it.

<script src="https://www.trustgated.xyz/widget.js"></script>

Always use the www host. The apex trustgated.xyz 307-redirects, and browsers drop Access-Control-Allow-Origin on that hop.

Mark what to score

Two modes. Choose based on how the address arrives.

<!-- Input mode: badge appears below the field 800ms after typing stops -->
<input type="text" data-trustgate="token-shield" placeholder="Token address" />

<!-- Inline badge mode: score a known address on load -->
<span data-trustgate="token-shield" data-trustgate-address="0xTOKEN_ADDRESS">USDC</span>

Pick a style

data-trustgate-style applies to inline mode.

<!-- full: numeric score and tier, e.g. "87 · HIGH_ELITE" -->
<span
  data-trustgate="token-shield"
  data-trustgate-address="0x..."
  data-trustgate-style="full"
>USDC</span>

<!-- minimal (default): tier only, e.g. "HIGH_ELITE" -->
<span
  data-trustgate="token-shield"
  data-trustgate-address="0x..."
  data-trustgate-style="minimal"
>USDC</span>

Only ERC-20s. Everything else is NTT and the badge is omitted.

Detection	Response	Badge
Official issuer	`{ "score": null, "tier": "VERIFIED", "label": "VERIFIED" }`	VERIFIED
ERC-20	`{ "score": 87, "tier": "HIGH_ELITE", "contractType": "ERC-20" }`	Score / tier
NFT, other contract, EOA	`{ "score": null, "tier": "NTT", "label": "NTT" }`	Input mode shows `NTT`. Inline badge renders nothing.
Invalid address	no request / no badge	Nothing
Upstream failure	`{ "error": "scoring_unavailable" }`	Nothing

A MutationObserver picks up fields added later, so SPAs are fine.

React / Next.js

import Script from "next/script";

export function TokenAddressField() {
  return (
    <>
      <Script
        src="https://www.trustgated.xyz/widget.js"
        strategy="afterInteractive"
      />
      <input type="text" data-trustgate="token-shield" placeholder="0x..." />
    </>
  );
}

Rate limits and payment

GET https://www.trustgated.xyz/api/widget/score/{address}

Auth: none. Open CORS (GET, OPTIONS).
Default 8 requests per minute per client IP. 429 with Retry-After.
The embedder does not pay. TrustGate’s server wallet settles the 0.001 USDC upstream query for ERC-20s. Cached addresses (1 hour) do not re-spend.
A global payment budget protects the hot wallet. If it is exhausted you get 429 / scoring_unavailable rather than a hanging badge.

<script src="https://www.trustgated.xyz/widget-discovery.js"></script>

<!-- anywhere in your markup, placed by you -->
<span data-trustgate-badge="0xTOKENADDRESS"></span>

The script collects every slot, calls POST /api/batch once, and fills a compact mark (58 MID). Optional attributes on the <script> tag:

Attribute	Effect
`data-trustgate-flags="on"`	Show flags next to each badge. Off by default.
`data-trustgate-batch-url`	Override the batch endpoint.
`data-trustgate-mock="1"`	Use fixtures instead of the live endpoint.
`data-trustgate-search="#token-results"`	Treat this container as a search list.
`data-trustgate-reorder="on"`	Opt in to client-side reorder inside that container.

On each result row, the address may be data-address, data-token, or data-token-address. Search-results intercept:

<script
  src="https://www.trustgated.xyz/widget-discovery.js"
  data-trustgate-search="#token-results"
  data-trustgate-reorder="on"
  data-trustgate-flags="on"
></script>

<ul id="token-results">
  <li data-trustgate-row data-address="0xaaa…">Yoshi</li>
  <li data-trustgate-row data-address="0xbbb…">Yoshi</li>
</ul>

Dynamic lists (SPA), after render:

window.TrustGateDiscovery.reorderContainer("#token-results");

Full batch contract and the JS reorder helper: Optional reorder.

Arc (EVM)
Sui

Both widgets are live on Arc Testnet addresses (0x + 40 hex).

A different script. Do not load the Arc widget.js on a Sui page.

<script
  src="https://sui.trustgated.xyz/widget.js"
  data-api="https://sui.trustgated.xyz/api/coin"
  defer
></script>
<span data-trustgate-coin="0x2::sui::SUI"></span>

The widget scans data-trustgate-coin (not data-trustgate-address). After a dynamic list render, call window.TrustGate.scan().Backing endpoint: GET https://sui.trustgated.xyz/api/coin?type=<coinType>. Open CORS. No x402. TokenShield here scores mainnet coins.Sui-specific flag codes: NEW_TOKEN, LOW_LIQUIDITY, CONCENTRATED_HOLDERS, MINTABLE_SUPPLY, UNVERIFIED_METADATA, DEPLOYER_UNTRUSTED, FEW_HOLDERS.

Good to know

The scripts load asynchronously and will not block your page. They need no wallet connection. They are framework-agnostic. During testnet they are free to embed.

The badge is non-invasive by design. It reports a signal in the spot you choose and never touches your wallet flow or the rest of your interface.

Want raw data instead?

Skip the badge and consume tiers and flags.

API reference

Widget and batch status codes.

Start Here

Guides

Reference

What you will end up with

Single-token widget

What the single-token widget scores

React / Next.js

Rate limits and payment

Discovery widget

Good to know

Next

Want raw data instead?

API reference

​What you will end up with

​Single-token widget

​What the single-token widget scores

​React / Next.js

​Rate limits and payment

​Discovery widget

​Good to know

​Next

Want raw data instead?

API reference

What you will end up with

Single-token widget

What the single-token widget scores

React / Next.js

Rate limits and payment

Discovery widget

Good to know

Next