API reference

Base

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

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

POST /api/batch
{ "addresses": string[] }

Max 40. 30 requests / minute / IP. Returns BatchScore[]:

{
  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

GET /api/oracle/{address}

Unpaid challenge returns 402 with payment details (0.001 USDC, arc-testnet). Replay with X-Payment. See Oracle. Contract on unpaid challenge:

{
  "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

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

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`

{
  "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`

{
  "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.

Protocol Guard

POST `/api/protocol-guard/check`

{
  "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").

{ "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

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

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 and capability gate.

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. 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`

Pick a guide

Widget, oracle, gating, contracts.

FAQ

Pricing, gaming, graphs, mainnet.

Start Here

Guides

Reference

Base

At a glance

Widget score

Batch

Oracle — wallet

Oracle — token

NFT

Gating

POST `/api/gating/attest`

POST `/api/gating/verify`

POST `/api/gating/check`

Protocol Guard

POST `/api/protocol-guard/check`

GET `/api/protocol-guard/subscriptions`

Staking

Snapshots

Platform-only (do not integrate)

Sui HTTP

Shared vocabulary

Next

Pick a guide

FAQ

​Base

​At a glance

​Widget score

​Batch

​Oracle — wallet

​Oracle — token

​NFT

​Gating

​POST /api/gating/attest

​POST /api/gating/verify

​POST /api/gating/check

​Protocol Guard

​POST /api/protocol-guard/check

​POST /api/protocol-guard/subscribe

​GET /api/protocol-guard/subscriptions

​Staking

​Snapshots

​Platform-only (do not integrate)

​Sui HTTP

​Shared vocabulary

​Next

Pick a guide

FAQ

Base

At a glance

Widget score

Batch

Oracle — wallet

Oracle — token

NFT

Gating

POST `/api/gating/attest`

POST `/api/gating/verify`

POST `/api/gating/check`

Protocol Guard

POST `/api/protocol-guard/check`

POST `/api/protocol-guard/subscribe`

GET `/api/protocol-guard/subscriptions`

Staking

Snapshots

Platform-only (do not integrate)

Sui HTTP

Shared vocabulary

Next