> ## Documentation Index > Fetch the complete documentation index at: https://docs.trustgated.xyz/llms.txt > Use this file to discover all available pages before exploring further. # API reference > Every public TrustGate HTTP path: method, auth, body, response, and errors. ## Base ```text theme={null} https://www.trustgated.xyz ``` Use the `www` host. JSON in, JSON out. `Cache-Control: no-store` on score paths. CORS is open (`*`) on widget, batch, and oracle. **Gating and Protocol Guard send no CORS headers.** Call them from your backend. A third-party browser origin will fail. Arc paths below are **Arc Testnet** unless noted. Sui is a separate app (`https://sui.trustgated.xyz`) with its own widget and coin API. ## At a glance | Path | Method | Auth | Audience | | ----------------------------------- | ------ | ------------- | -------------- | | `/api/widget/score/{address}` | GET | none | Public embeds | | `/api/batch` | POST | none | Public embeds | | `/api/oracle/{address}` | GET | x402 | Integrators | | `/api/oracle/token/{address}` | GET | x402 (ERC-20) | Integrators | | `/api/token-shield/nft/{address}` | GET | none | Integrators | | `/api/gating/attest` | POST | none | Protocols | | `/api/gating/verify` | POST | none | Protocols | | `/api/gating/check` | POST | none | Protocols | | `/api/protocol-guard/check` | POST | none | Protocols | | `/api/protocol-guard/subscribe` | POST | none | Protocols | | `/api/protocol-guard/subscriptions` | GET | manage token | Protocols | | `/api/staking/analyze/{address}` | GET | none | Integrators | | `/api/staking/leaderboard` | GET | none | Integrators | | `/api/snapshots/{address}` | GET | none | Integrators | | `/api/graph-trust` | POST | platform | **Not public** | | `/api/stats` | GET | none | Site chrome | | `/api/agent-status` | GET | none | Site chrome | ## Widget score ```text theme={null} GET /api/widget/score/{address} ``` `address` must match `^0x[0-9a-fA-F]{40}$`. | Status | Body | | ---------- | --------------------------------------------------------------- | | 200 ERC-20 | `{ "score": number, "tier": string, "contractType": "ERC-20" }` | | 200 issuer | `{ "score": null, "tier": "VERIFIED", "label": "VERIFIED" }` | | 200 other | `{ "score": null, "tier": "NTT", "label": "NTT" }` | | 400 | `{ "error": "invalid_address" }` | | 429 | `{ "error": "rate_limited" }` + `Retry-After` | | 502 | `{ "error": "detection_failed" \| "scoring_unavailable" }` | Default IP cap: 8 requests / minute. OPTIONS enabled. ## Batch ```text theme={null} POST /api/batch { "addresses": string[] } ``` Max 40. 30 requests / minute / IP. Returns `BatchScore[]`: ```ts theme={null} { address: string score: number tier: "BLOCKED" | "LOW" | "MEDIUM" | "HIGH" | "ELITE" | "VERIFIED" confidence: number | string flags: string[] state: "graduated" | "mining" error?: string } ``` Errors: `invalid_json`, `addresses_required`, `too_many_addresses` (+ `max`), `invalid_addresses`, `rate_limited`, `batch_failed`. ## Oracle — wallet ```text theme={null} GET /api/oracle/{address} ``` Unpaid challenge returns `402` with payment details (0.001 USDC, `arc-testnet`). Replay with `X-Payment`. See [Oracle](/integrate/oracle). Contract on unpaid challenge: ```json theme={null} { "error": "This is a contract address. Use Token Shield to score contracts.", "code": "CONTRACT_NOT_WALLET", "redirect": "/token-shield" } ``` 200 body (hardened): `address`, `score`, `tier`, `recommendation`, `confidence`, `flags`, `summary`, `publicExplain`, `protocolExplain`, `scoreStability`, `directionDrivers`, `snapshotId`, `scoringVersion` (`v1.0` on oracle; `testnet-wallet-v1.0` on attestations), `queriedAt`, optional `limitations`. Raw `breakdown` is stripped. Other errors: `422` bad proof, `502` proxy / upstream. ## Oracle — token ```text theme={null} GET /api/oracle/token/{address} ``` VERIFIED short-circuit for official issuers. Local free path for NFT / other contract. ERC-20 is x402, same as the wallet oracle. ## NFT ```text theme={null} GET /api/token-shield/nft/{address} ``` Free local scorer. Sparse data degrades to low confidence rather than throwing. `400` invalid address, `502` Arcscan failure. ## Gating ### POST `/api/gating/attest` ```json theme={null} { "subject": "0x…", "subjectType": "wallet", "useClass": "financial_high", "chainId": 5042002, "ttlSeconds": 21600 } ``` `201` `{ attestation, pricing: "free", disclaimer, note? }`. Errors: `invalid_json`, `invalid_subject`, `attest_failed`. ### POST `/api/gating/verify` ```json theme={null} { "attestation": { }, "expectedSubject": "0x…", "expectedChainId": 5042002 } ``` Returns `{ valid, reasons, …, disclaimer }`. Errors: `invalid_json`, `attestation_required`. ### POST `/api/gating/check` Requires `wallet` plus `ladder.bands` (or testnet-only `ladderPreset`). Mainnet rejects presets, requires `protocolId`, forces multi-factor ack. Returns ladder evaluation (`allowed`, `allowedByCallerLadder`, `policySource: "caller_ladder"`, `scoreIsAuthoritative: true`), scores, attestation, `guidance`, `disclaimer`. Errors: `invalid_wallet`, `ladder_required`, `ladder_preset_forbidden`, `protocol_id_required`, `check_failed`. Full types: [Gate with attestations](/integrate/gating). ## Protocol Guard ### POST `/api/protocol-guard/check` ```json theme={null} { "wallet": "0x…", "context": "borrow", "amount": 50000, "economicReachUsd": 50000, "subscriptionId": "optional" } ``` `404 registration_not_found` if a bad `subscriptionId` is sent. Otherwise always attempts a check (`pricing: "free"`). ### POST `/api/protocol-guard/subscribe` ```json theme={null} { "protocolName": "my-dao", "channels": {}, "rules": [] } ``` `201` includes `manageToken` once. ### GET `/api/protocol-guard/subscriptions` * List (no id): thin `{ id, protocolName, status }` rows. No channel secrets. * One registration: `?id=sub_…` plus manage token via `Authorization: Bearer …`, `?token=`, or body. Returns subscription (channels redacted to booleans), last 20 alerts, last 20 onchain events. `401` / `404` otherwise. PATCH on the same path updates channels and rules. Same token. ## Staking ```text theme={null} GET /api/staking/analyze/{address} GET /api/staking/leaderboard ``` Analyze → `StakingSignal`. Leaderboard → ranked `{ rank, wallet, committedScore, totalPoints, … }`. `400 invalid_address`, `502 staking_analysis_failed`. ## Snapshots ```text theme={null} GET /api/snapshots/{address}?limit=20 GET /api/snapshots/{address}?id=snap_… ``` In-process memory. `limit` clamped to 1–50. `404 not_found` for unknown ids. ## Platform-only (do not integrate) `POST /api/graph-trust` is the Intuition proxy for the hosted Oracle / Token Shield toggle. It is not a public integrator API and is not covered by SLA or CORS guarantees for third parties. `GET /api/stats` and `GET /api/agent-status` power the marketing site counters (oracle queries, claims, USDC moved). They are not a product API. `GET /api/arc-score/{address}` is an **internal** local scorer used by the agent loop. It can include a raw formula `breakdown`. Do not call it from a product. Use `/api/oracle/{address}` instead. ## Sui HTTP | Method | Path | Notes | | ------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `https://sui.trustgated.xyz/api/coin?type=` | TokenShield. Mainnet coin types. Open CORS. Returns `coinType`, `score`, `tier`, `confidence`, `verified`, `signals`, `flags`, `metadata`, `scoredAt`, `nextRescoreAt`. | | POST | `https://sui.trustgated.xyz/api/score-wallet` | `{ "address" }`. Triggers the out-of-repo Sui wallet oracle. Testnet registry / cap mint. | Sui widget: `https://sui.trustgated.xyz/widget.js` + `data-trustgate-coin`. Onchain reads: `devInspect` against the testnet `ScoreRegistry`. Details: [Sui](/networks/sui) and [capability gate](/integrate/sui-cap). ## Shared vocabulary | Field | Values | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Product `tier` | `BLOCKED`, `LOW`, `MEDIUM`, `HIGH`, `ELITE` or `HIGH_ELITE`, `VERIFIED`, widget `NTT` | | Onchain tier | `0` LOW, `1` MEDIUM, `2` HIGH | | `state` | `graduated`, `mining` | | `scoringVersion` | Oracle/batch: `v1.0`. Attestations: `testnet-wallet-v1.0` / `testnet-token-v1.0` | | Known flags | See [Flags](/scoring/flags). Discovery highlights `HONEYPOT_PATTERN`, `COORDINATED_BUY`, `EXIT_SYNC`, `LOW_HOLDER_QUALITY`. Wallet and Token Shield add wash, staking, velocity, concentration, and exit-history codes. | | `useClass` | `financial_high`, `governance`, `allowlist`, `display` | ## Next Widget, oracle, gating, contracts. Pricing, gaming, graphs, mainnet.