Reputation over HTTP

curl -H "Authorization: Bearer $TRUST_LAYER_API_KEY" \
  $TRUST_LAYER_API/v1/risk/0x…

# 202 while the address is indexed:
{ "subject": "0x…", "indexing": { "status": "backfilling", … } }

# then 200:
{
  "status": "scored",
  "trust_score": 746,
  "band": "strong",
  "risk_level": "low",
  "confidence": 0.71,
  "flags": [],
  "score_model_version": "v0.3",
  "aleph": null
}

const res = await fetch(`${API}/v1/risk/${address}`, {
  headers: { Authorization: `Bearer ${process.env.TRUST_LAYER_API_KEY}` },
});
if (res.status === 202) return "pending"; // not rated yet: retry shortly
const risk = await res.json();

if (risk.status !== "insufficient_data" && risk.trust_score < 300) {
  warn(risk.flags);   // each flag links to its evidence
}

HTTP/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 12

{ "error": { "code": "RATE_LIMITED", "message": "…" } }

POST /v1/batch
Authorization: Bearer tl_live_…
Content-Type: application/json

{
  "addresses": ["0xAb12…", "0x9f8E…", "0xnot-an-address"],
  "view": "risk"
}

{
  "results": [
    { "address": "0xAb12…", "status": 200,
      "data": { "status": "scored", "trust_score": 746, … } },
    { "address": "0x9f8E…", "status": 202,
      "data": { "indexing": { "status": "queued", … } } },
    { "address": "0xnot-an-address", "status": 400,
      "error": { "code": "INVALID_ADDRESS", "message": "…" } }
  ]
}

POST /your/webhook/endpoint
Content-Type: application/json
X-TrustLayer-Event: score.updated
X-TrustLayer-Delivery: whd_01JA…
X-TrustLayer-Signature: t=1791633600,v1=5f2b…c9e1

{
  "id": "whe_01JA…",
  "type": "score.updated",
  "created_at": "2026-10-10T12:00:00.000Z",
  "network": "robinhood",
  "subject": "0x7F2c…A91b",
  "data": { … }
}

• X-TrustLayer-Signature is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 with your secret over <t>.<raw body>. More than one v1 may appear; accept the delivery when any one matches.
• Verify against the raw body exactly as received, compare in constant time, and reject a timestamp more than 300 seconds from your clock. That stops forged and replayed deliveries.
• Answer with a 2xx status quickly and do slow work afterwards. Other answers and timeouts count as failures and are retried with backoff, so de-duplicate on the event id. A subscription that keeps failing is disabled; GET /v1/webhooks shows consecutive_failures and disabled_reason.
• Treat data as a notification and read the subject again for its current state. An aleph.assessment.updated event is an inference: route it to review, never treat it as a fact.

import { verifyWebhook, WebhookVerificationError } from "@trust-layer/sdk";

// Next.js route handler (any Fetch-API runtime)
export async function POST(request: Request) {
  const payload = await request.text(); // the raw body, unparsed
  try {
    const event = await verifyWebhook({
      payload,
      header: request.headers.get("x-trustlayer-signature"),
      secret: process.env.TRUST_LAYER_WEBHOOK_SECRET!,
      // toleranceSeconds: 300 (default)
    });
    await enqueue(event); // de-duplicate on event.id
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(null, { status: 400 });
    }
    throw error;
  }
  return new Response(null, { status: 204 });
}

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact bytes received. header: X-TrustLayer-Signature.
export function isAuthentic(rawBody: Buffer, header: string, secret: string) {
  const fields = header.split(",").map((part) => part.trim().split("="));
  const t = fields.find(([key]) => key === "t")?.[1];
  if (!t || !/^\d+$/.test(t)) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${t}.`)
    .update(rawBody)
    .digest();
  return fields.some(([key, value]) =>
    key === "v1" && /^[0-9a-f]{64}$/i.test(value ?? "") &&
    timingSafeEqual(Buffer.from(value!, "hex"), expected));
}

# from this repository, until the first npm release
pnpm --filter @trust-layer/sdk build

# in a workspace package.json
"@trust-layer/sdk": "workspace:*"

# once published
npm install @trust-layer/sdk

import { TrustLayer, isPending } from "@trust-layer/sdk";

const tl = new TrustLayer({
  apiKey: process.env.TRUST_LAYER_API_KEY,   // server-side only
  baseUrl: process.env.TRUST_LAYER_BASE_URL, // default https://api.trustlayer.xyz
});

const risk = await tl.risk("0x7F2c…A91b");   // RiskResponse | Pending
if (isPending(risk)) {
  console.log("not rated yet:", risk.indexing?.status);
} else {
  console.log(risk.trust_score, risk.band, risk.flags);
}

// Or wait until the address is indexed (polls, then returns data):
const ready = await tl.trust("0x7F2c…A91b", { waitForReady: { timeoutMs: 30_000 } });

import { policy } from "@trust-layer/sdk";

const guard = policy({
  minTrustScore: 400,           // block below
  warnBelowTrustScore: 550,     // warn below
  maxRiskLevel: "elevated",     // block on high / severe
  requireScored: false,         // true: unscored and provisional block
  treatPendingAs: "pending",    // or "allow" | "warn" | "block"
  blockOnFlagSeverity: "high",  // VERIFIED / SIGNAL flags at or above block
  aleph: { warnAt: "medium" },  // an inference warns; blockAt is opt-in
});

const { decision, reasons } = guard.evaluate(await tl.risk(recipient));
// decision: "allow" | "warn" | "block" | "pending"
// reasons[]: { code, effect, message, classification?, inference, evidence }

• TRUST LAYER provides the evidence; your application makes the call. A policy turns a /v1/risk answer into allow, warn, block or pending, and every reason cites the score, the flag (with its class and event id) or the assessment behind it.
• Only the score thresholds and VERIFIED or SIGNAL flags block by default.
• An ALEPH INFERENCE adds at most a warning, marked as inference. It blocks only when your policy sets aleph.blockAt, and never changes the score.
• An address that is still being indexed, or has too little history to score, is not evidence of risk: the reason says so.