TonWise API

Real-time on-chain security layer for TON. Detect Puppet Masters, Sybil clusters and Unicode spoofs before your users lose money.

Authentication

Pass your API key in the X-API-Key header on every request.

curl https://tonguard.app/api/v1/shield \
  -H "X-API-Key: tw_live_your_key_here" \
  -G -d "contract=EQBHNioK..."

Rate Limits

Shield API responses are Redis-cached. Cache miss triggers live blockchain analysis (~2-5s). Cache hit returns in <50ms.

Pre-trade Contract Screening

Run a contract through TonWise before a trade executes. Returns risk score, dump probability and sybil cluster count. Cached responses return in under 50ms.

curl "https://tonguard.app/api/v1/shield?contract=EQBHNioKtx8Fu3pglkxSzvl9zt4KY1ixUl0miMSVCyHvDW60" \
  -H "X-API-Key: tw_live_your_key"

{
  "contract":         "EQBHNioKtx8Fu3pglkxSzvl9zt4KY1ixUl0miMSVCyHvDW60",
  "is_safe":          false,
  "dump_probability": 45,
  "reason":           "SYBIL_CONCENTRATION_DETECTED",
  "sybil_clusters":   1
}

Address Cluster Intelligence

Map the full scammer cluster around any TON address through the Lazarus graph. BFS-traversal at depth 3 returns linked scams, threat score, cluster membership, and (when available) cross-chain exit history. Where Shield scans one token, Threat Intel maps the network behind it.

curl "https://tonguard.app/api/v1/threat-intel/EQDa4VOnTYlLvDJ0gZjNYm5PXfSmmtL6Vs6A_CZEtXCNICq_" \
  -H "X-API-Key: tw_live_your_scale_key"

from tonwise import TonWiseClient, TierError

with TonWiseClient(api_key="tw_live_your_scale_key") as client:
    try:
        intel = client.threat_intel("EQDa4VOnTYlLvDJ0gZjNYm5PXfSmmtL6Vs6A_CZEtXCNICq_")
        print(f"Threat score: {intel.threat_score}/100")
        for scam in intel.linked_scams:
            print(f"  → {scam.contract} ({scam.symbol})")
    except TierError as e:
        print(f"Need Scale tier, you have: {e.current_tier}")

{
  "address":                  "0:dae153a74d894bbc32748198cd626e4f5df4a69ad2fa56ce80fc2644b5708d20",
  "threat_score":             40,
  "first_seen":               null,
  "last_activity":            null,
  "associated_addresses":     4999,
  "linked_scams": [
    {
      "contract":    "0:6e6d431b9bafe1...",
      "symbol":      "SYBIL",
      "first_seen":  null,
      "labels":      ["SCAM", "flagged"]
    }
  ],
  "puppet_master_cluster_id": null,
  "labels":                   ["SCAM", "PUPPET_MASTER"],
  "cross_chain_exits":        [],
  "graph_depth":              3,
  "computed_at":              "2026-05-10T12:00:00.000Z"
}

{
  "error":        "Threat Intel API requires Scale or Enterprise tier",
  "current_tier": "pro"
}

Shareable Threat Artifacts

Every Auto-Hunter catch is automatically materialized as a public receipt page at tonguard.app/r/{id}. Receipts are pre-rendered with Open Graph and Twitter Card meta tags — any link share (Twitter, Telegram, Discord, Slack, iMessage) surfaces a rich preview with severity badge, threat ID, and key stats.

How Receipts Are Created

The Auto-Hunter monitors new TON liquidity pools and flags scams in real time — Sybil clusters, dump-imminent setups, Unicode-spoof tokens. Each catch triggers two simultaneous actions:

• A threat report is published to @tonwise_intel Telegram channel.
• A persistent Receipt row is written to the database with severity, threat ID, sybil count, AI analysis, and a stable 8-hex ID (e.g. r_f698cc17).

The receipt URL is appended to the channel post. Subscribers get a one-tap shareable link; outsiders following the link land on a full threat-detail page.

Receipt Page Anatomy

Embedding in Your Product

Receipt URLs are stable and embeddable. If you operate a TON product (wallet, DEX, mini-app) that wants to surface threat context, you can:

• Link https://tonguard.app/r/{id} from within your UI for any flagged contract.
• Trust that Open Graph rendering works on Twitter, Telegram, Discord, Slack, iMessage out of the box.
• Receipts are not gated by API key — they exist independently of the B2B endpoints.

To map a contract address to its receipt, query the Shield endpoint; if the contract has been flagged, the receipt will exist on its public URL within seconds of the Auto-Hunter catch.

Real-time Event Stream

Register an endpoint and receive signed payloads the moment Auto-Hunter detects a threat. No polling required.

curl -X POST https://tonguard.app/api/v1/webhook/register \
  -H "X-API-Key: tw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-bot.com/hook","events":["dump_alert","spoof","sybil_cluster"]}'

{
  "webhook_id":  1,
  "url":         "https://your-bot.com/hook",
  "events":      ["dump_alert", "spoof", "sybil_cluster"],
  "secret":      "a3f9b2c1d4e5...",
  "created_at":  "2026-05-02T10:00:00Z",
  "hint":        "Store the secret securely — used to verify HMAC signatures"
}

curl -X POST https://tonguard.app/api/v1/webhook/test \
  -H "X-API-Key: tw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"webhook_id": 1}'

curl https://tonguard.app/api/v1/webhook/list \
  -H "X-API-Key: tw_live_your_key"

curl -X DELETE https://tonguard.app/api/v1/webhook/1 \
  -H "X-API-Key: tw_live_your_key"

Event Types

Payload Schema

Every webhook delivery includes the following fields plus an HMAC-SHA256 signature.

{
  "event":        "DUMP_ALERT",
  "contract":     "EQBHNioKtx8Fu3pglkxSzvl9zt4KY1ixUl0miMSVCyHvDW60",
  "symbol":       "TVL",
  "sybils":       22,
  "dump_prob":    92,
  "triggered_at": "2026-05-02T10:00:00Z",
  "source":       "tonguard.app",
  "signature":    "sha256=a3f9b2c1..."
}

Request Headers

Verify Signature

Always verify the HMAC-SHA256 signature before processing a webhook payload.

import hashlib, hmac

def verify(secret: str, payload: bytes, sig_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig_header)

const crypto = require('crypto');

function verify(secret, payload, sigHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sigHeader)
  );
}

Error Codes