API reference

Rate limits

Scoring is synchronous, so plan for both the monthly quota and the burst behaviour below.

• Quota is per calendar month (UTC) and shared across all keys on an account. Each /score call is 1 unit; a /scores/batch of N agents is N units. Every scored response carries X-RateLimit-Limit, X-RateLimit-Used, and X-RateLimit-Remaining headers so you can track consumption without a separate call.
• No per-second burst throttle on authenticated calls today. Authenticated requests are governed by the monthly quota only — you may spend it as fast as you like — so pace client-side if you must not exhaust the month in one run. A 429 with Retry-After means the monthly quota is spent (retry after the reported seconds, i.e. next month).
• Abuse throttles (IP-based). To blunt key-guessing and scraping, some paths carry an IP burst cap independent of the quota: authentication failures are limited to 60/minute/IP, the unauthenticated demo scorer to 10/minute/IP, and the public /accuracy and payee-verify endpoints to 20 and 10/minute/IP respectively. Valid authenticated traffic does not hit these.

Score breakdown

Every scored verdict (agent and wallet endpoints, and each element of a batch) carries a breakdown object that decomposes the chain score into its four weighted components. It is derived from the same numbers the verdict used, so it can never disagree with trustScore.

• components — each of identity, reputation, wallet, x402 reports its 0–100 score, its weight, and its contribution (score × weight ÷ 0.8; the four contributions sum to weightedSubtotal). Weights are identity 0.2, reputation 0.3, wallet 0.2, x402 0.1 — divided by 0.8 because the customer whitelist/blacklist is a policy layer, not a signal.
• weightedSubtotal — the weighted average of the four components, before any sybil adjustment.
• sybilPenalty — points removed by sybil / data- availability flags (always ≤ 0). The specific flags are in signals.sybil.flags.
• prePolicyScore — weightedSubtotal + sybilPenalty, clamped to 0–100. This equals trustScore unless a manual list moved it, in which case manualOverride is true. The manual layer is deliberately kept out of the breakdown so the chain-derived explanation stays separable from policy.

Hard-blocked verdicts (wallet mismatch, unregistered agent) omit breakdown — no weighting ran — and carry a blockReason instead. Treat the field as optional.

Webhooks

vet402 is otherwise a pull API. Webhooks turn it into a monitoring service: register an endpoint once and we POST you a signed event when something you care about changes — most importantly a watched target whose verdict moved (e.g. an ALLOW you gated a payment on becoming a BLOCK). Register with POST /api/v1/webhooks (above); up to 5 endpoints per key.

POST https://your-host.example/vouch-hook
Content-Type: application/json
Vouch-Signature: t=1723000000,v1=5f2b…   (hex HMAC-SHA256)
User-Agent: vouch-webhooks/1

{
  "id": "evt_9f8a…",
  "type": "watch.verdict_changed",
  "createdAt": "2026-08-06T09:30:00.000Z",
  "data": {
    "watchId": "…",
    "targetType": "wallet",
    "target": "0x…",
    "chainId": 8453,
    "previous": { "score": 74, "recommendation": "ALLOW" },
    "current":  { "score": 31, "recommendation": "BLOCK" }
  }
}

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

function verify(secret, rawBody, header, toleranceSec = 300) {
  const parts = new Map(header.split(",").map(p => {
    const i = p.indexOf("="); return [p.slice(0, i), p.slice(i + 1)];
  }));
  const t = Number(parts.get("t"));
  const v1 = parts.get("v1");
  if (!Number.isFinite(t) || !v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay guard
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

Availability

vet402 is in closed beta, run by a single operator. We publish our real operating posture rather than a contractual uptime figure we can't yet stand behind:

• No SLA credits during beta. Service is best-effort, with no financial uptime guarantee. When we commit to a numeric target it will be backed by measured operating history — we would rather under-promise than publish a number the way some vendors publish accuracy claims they never measured.
• Infrastructure. Serverless compute (Vercel), managed Postgres (Neon), and Base RPC. Availability inherits from these providers; there is no independent multi-region failover today.
• Fail-closed, not fail-wrong. When an upstream (RPC, indexer, settlement store) is unavailable, the affected signal is marked with an *_unavailable flag and penalized rather than guessed — a degraded lookup returns a more cautious verdict, not a confidently wrong one. Each response's dataCoverage reports indexer and settlement freshness so you can see what the score could draw on.
• Monitoring. A public health endpoint, GET /api/health, returns 200/503 for uptime pollers. A deeper env/DB/RPC probe runs on a daily cron and returns 503 only on a critical failure (indexer catch-up lag is reported, not alerted, to avoid backfill alert fatigue).
• Status & incidents. No hosted status page yet; during beta, material incidents are communicated to integrators directly. Point your own uptime monitor at /api/health in the meantime.

Error codes

Error bodies are shaped as { "error": string, "details"?: object }.