API Documentation

Complete reference for the TrustSniffer REST API. Authenticate, submit targets, and receive structured risk intelligence.

Authentication

All API requests require a Bearer token in the Authorization header. Obtain your API key from the Dashboard settings page.

Authorization: Bearer ts_live_k7x9...

API keys are scoped per tenant. Never expose keys in client-side code.

Rate Limits

Requests are rate-limited per API key. Current limits:

Plan	Requests/min	Burst
Free	10	20
Pro	120	200
Enterprise	Unlimited	—

Rate limit headers (X-RateLimit-Remaining) are included in every response.

Error Handling

All errors return a consistent JSON envelope:

Code	Meaning
401	Invalid or missing API key
429	Rate limit exceeded
400	Validation error (see `details` field)
500	Internal server error

Webhooks

Deep wallet analysis and full web intelligence scans can take 10–60 seconds. Rather than polling, register a webhook URL to receive a POST request with the completed verdict payload as soon as processing finishes.

Configuration

Set your webhook URL per-request via the webhook_url parameter, or configure a global endpoint in your Dashboard → Settings → Webhooks panel.

Verification

Every webhook includes an X-TrustSniffer-Signature header containing an HMAC-SHA256 digest. Verify it against your webhook secret to ensure authenticity.

SDKs & Libraries

Official client libraries for rapid integration:

Node.js npm install @trustsniffer/sdk Stable

Python pip install trustsniffer Stable

Go go get github.com/trustsniffer/go-sdk Beta

Sanctions WebSocket — Live Feed

Connect to our real-time sanctions stream to receive freeze, unfreeze, and burn events across Ethereum and TRON the instant they occur. Propagation latency from on-chain event to your WebSocket client is sub-millisecond.

wss://api.trustsniffer.com/v1/feed?token=ts_live_k7x9...

Event Types

Type	Description
FREEZE	Address blacklisted — tokens immovable
UNFREEZE	Address removed from blacklist
BURN	Frozen tokens permanently destroyed by issuer

Subscription Filters

After connecting, send a JSON message to subscribe to specific chains or tokens:

{"type":"subscribe","chains":["ethereum","tron"],"tokens":["USDT","USDC"]}

Guide: Blocking Risky Withdrawals

Integrate TrustSniffer into your exchange withdrawal pipeline to block transfers to high-risk addresses before they leave your hot wallet.

User initiates withdrawal → your backend captures the destination address.
Call POST /v1/risk/analyze-wallet with sanctions_only: true for fast screening (< 200ms).
If verdict = "critical" or sanctions_hit = true, reject the withdrawal and flag for compliance review.
For non-critical verdicts, proceed with withdrawal and log the risk score for audit.

Guide: KYC Workflow Enhancement

Augment your Know-Your-Customer onboarding by screening submitted wallet addresses against our taint graph and sanctions database during identity verification.

User submits wallet address during onboarding.
Call POST /v1/risk/analyze-wallet with full depth analysis (depth: 4).
Store the verdict and score alongside the KYC record.
Apply your risk policy: auto-approve clear/low, escalate medium+.

POST /v1/web/scan

Submit a URL for full web intelligence analysis. The engine launches a headless browser, captures the rendered DOM, inspects behavioral JavaScript, maps DNS/SSL infrastructure, checks archive drift, and produces a composite risk score with granular module-level evidence.

Request Parameters

Param	Type	Required	Description
url	string	Required	Target URL to analyze (must include protocol)
capture_mode	string	Optional	`fast` (DOM + DNS only) \| `full` (all modules incl. archive & behavior). Default: `fast`
deep_scan	boolean	Optional	Enable visual similarity matching and phishing template detection. Default: false
modules	array	Optional	Subset of modules to run: `["dns","page","behavior","archive","external"]`. Default: all
webhook_url	string	Optional	URL to POST results when analysis completes
timeout_ms	integer	Optional	Max page load wait in ms (5000–30000). Default: 15000

Response Fields

Field	Type	Description
run_id	string	Unique analysis run identifier
verdict	string	`safe` \| `suspicious` \| `dangerous` \| `critical`
risk_score	number	Composite risk score (0–100)
modules	object	Per-module scores: `dns`, `page`, `behavior`, `archive`, `external`
visual_similarity	object\|null	Phishing template match (brand, confidence %). Only if `deep_scan: true`
infrastructure	object	DNS records, registrar, SSL issuer, hosting provider, domain age
signals	array	List of triggered heuristic signals with severity and evidence

POST /v1/risk/analyze-wallet

Analyze an on-chain address for taint exposure, sanctions hits, and entity classification. Returns a risk band verdict with full propagation provenance.

Request Parameters

Param	Type	Required	Description
address	string	Required	Wallet address (EVM or TRON)
chain	string	Required	`ethereum` \| `tron`
depth	integer	Optional	Max hops for taint propagation (1–6). Default: 3
include_paths	boolean	Optional	Include full taint path provenance. Default: false
sanctions_only	boolean	Optional	Skip taint propagation, check sanctions lists only. Default: false

Response Fields

Field	Type	Description
verdict	string	Risk band: `clear` \| `low` \| `medium` \| `high` \| `critical`
score	number	Noisy-OR probability score (0–100)
sanctions_hit	boolean	Direct match against OFAC/EU/UN lists
entity	object	Classified entity type and label
paths	array	Taint path provenance (if `include_paths: true`)

Webhook Payload

// POST to your webhook_url
{
  "event": "verdict.ready",
  "run_id": "run_a3f8c912",
  "address": "0x8a1d...2f7c",
  "verdict": "high",
  "score": 78.4,
  "sanctions_hit": false,
  "completed_at": "2026-06-01T13:17:02Z"
}

WebSocket — Node.js

const ws = new WebSocket(
  'wss://api.trustsniffer.com/v1/feed',
  { headers: { Authorization: 'Bearer ts_live_k7x9...' }}
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    chains: ['ethereum', 'tron']
  }));
};

ws.onmessage = (msg) => {
  const ev = JSON.parse(msg.data);
  // { type: "FREEZE", chain: "tron",
  //   address: "TXn9k...f3aB",
  //   token: "USDT", frozen_usd: 120500 }
  console.log(ev.type, ev.address);
};

Request Example

# Analyze a wallet for taint exposure
curl -X POST \
  https://api.trustsniffer.com/v1/risk/analyze-wallet \
  -H "Authorization: Bearer ts_live_k7x9..." \
  -H "Content-Type: application/json" \
  -d '{
  "address": "0x8a1d...2f7c",
  "chain": "ethereum",
  "depth": 4,
  "include_paths": true
}'

Response

// 200 OK
{
  "verdict": "high",
  "score": 78.4,
  "sanctions_hit": false,
  "entity": {
    "type": "eoa",
    "label": null
  },
  "taint_sources": 3,
  "max_exposure_usd": 142000,
  "paths": [
    {
      "root": "0xdead...beef",
      "hops": 3,
      "decay": 0.42
    }
  ]
}

Web Scan Request

curl -X POST \
  https://api.trustsniffer.com/v1/web/scan \
  -H "Authorization: Bearer ts_live_k7x9..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://suspicious-site.com",
  "capture_mode": "full",
  "deep_scan": true
}'

Web Scan Response

// 200 OK
{
  "run_id": "run_b7f2e1a4",
  "verdict": "dangerous",
  "risk_score": 82,
  "modules": {
    "dns": { "score": 18, "domain_age_days": 12 },
    "page": { "score": 24, "login_form": true },
    "behavior": { "score": 22, "obfuscated_js": true },
    "archive": { "score": 14, "first_seen": null },
    "external": { "score": 4 }
  },
  "visual_similarity": {
    "brand": "MetaMask",
    "confidence": 0.91
  },
  "infrastructure": {
    "registrar": "Namecheap",
    "hosting": "Cloudflare",
    "ssl_issuer": "Let's Encrypt",
    "domain_age_days": 12
  },
  "signals": [
    { "rule": "new_domain", "severity": "high" },
    { "rule": "phishing_template", "severity": "critical" },
    { "rule": "obfuscated_scripts", "severity": "high" }
  ]
}