Guardian SDK.

Quickstart

Create the client in your backend. Then a badge when the address is pasted, a verdict when the token is chosen, and the delisting list on a timer.

import { createGuardian, isUnavailable, matchDelistings } from '@marani/guardian';

const guardian = createGuardian({
  apiKey: process.env.GUARDIAN_KEY!,
  baseUrl: 'https://<your guardian host>',
});

// 1. The address is pasted: show a badge.
const badge = await guardian.address(to);

// 2. The token is chosen: get the verdict.
const verdict = await guardian.check({ to, mint, symbol });
if (isUnavailable(verdict)) {
  // We couldn't check in time. Say so, and never block on it.
} else {
  show(verdict.level, verdict.message);
  // e.g. "block", "Binance doesn't accept USDG on Solana. …"
  if (verdict.level === 'block') {
    // Disable Send. If verdict.swapTo is set, offer
    // "Swap to {swapTo.symbol} and send" instead.
  }
}

// 3. Delistings, e.g. hourly: fetch the whole list and match it locally.
const list = await guardian.delistings();
if (!isUnavailable(list)) {
  const affected = matchDelistings(list.notices, heldMints);
}

Client options

When to call what

Skip the call for sends to the user's own address. The service covers Solana mainnet only.

The answer

{
  "level": "block",
  "code": "CEX_TOKEN_NOT_LISTED",
  "message": "Binance doesn't accept USDG on Solana. If you send it, it won't be credited.",
  "exchange": "binance",
  "swapTo": { "symbol": "USDC", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" },
  "notes": [
    {
      "level": "warn",
      "code": "CEX_HOT_WALLET",
      "message": "This is Binance's own wallet, not a deposit address. Binance credits only what you send to the deposit address it gave you."
    },
    {
      "level": "warn",
      "code": "TOKEN2022_EXCHANGE_CREDIT",
      "message": "Binance may be slow to credit USDG: many exchanges credit Token-2022 tokens by hand."
    },
    {
      "level": "info",
      "code": "TOKEN2022_PERMANENT_DELEGATE",
      "message": "USDG's issuer can move or burn it from any wallet."
    }
  ]
}

Listing freshness lives in GET /v1/health (dataAsOf), not on every answer.

The badge

/v1/address answers the recipient alone: { "exchange": "kucoin", "addressType": "hot-wallet" }, where addressType is deposit or hot-wallet (the exchange's own wallet). An unknown address is { "exchange": null }, with "likelyExchange": true added when it is probably an exchange deposit address.

Levels: what to show

Codes

message is ready in English. For other languages, translate by code, on the answer and on each note:

New codes may be added. If you get one that isn't listed here, show message and act on the level.

Delisting notices

delistings() returns every active notice: { exchange, symbol, mint, kind, effectiveAt, announcedAt, sourceUrl }.

• kind is delist, deposit-suspend or withdraw-deadline.
• Every notice is pinned to an exact Solana mint. We never publish a notice by ticker alone, because tickers collide.
• matchDelistings(notices, heldMints) keeps the ones your user holds. Run it on the device.
• Link sourceUrl, the exchange's own announcement, but don't prefetch it.

Sources today: Binance, OKX, Bybit, KuCoin and Bitget delisting announcements, polled hourly.

Errors

The default timeout is 4 s. The service answers within about 3 s even for a never-seen address. createGuardian throws straight away on a missing key, a baseUrl that isn't an http(s) URL, or a runtime with no fetch. Caught later, those would read as "unavailable" on every call.

Coverage

• A deposit address that has been used before is usually recognised. A brand-new one answers ask.
• Listing data refreshes weekly; GET /v1/health shows when (dataAsOf).
• Warn, never guarantee. The guardian reduces lost deposits; it cannot promise an exchange's crediting.

Exchange ids

binance coinbase kraken kucoin gate bitget htx okx bybit mexc

Privacy

• For each check we receive the recipient address, the mint, and optionally a symbol and the user's mark. Never the sender, the amount or the user's IP (your backend makes the call).
• We keep exchange-address findings (an address that sweeps into Binance is Binance's, for every partner), token metadata, and per-key counts of verdicts. We keep no request logs with addresses.
• Delisting matching runs on the device; holdings never reach us.