Trust Oracle

When to use this

Use the oracle when you need an authoritative wallet read, or the same ERC-20 score Token Shield uses, and you are willing to settle a micropayment. The widget and batch paths are free and thinner. This is the paid, hardened path. Do not send contract addresses to the wallet oracle. It returns CONTRACT_NOT_WALLET and tells you to use Token Shield.

Endpoints

Integrator-facing proxy (recommended):

GET  https://www.trustgated.xyz/api/oracle/{wallet}
GET  https://www.trustgated.xyz/api/oracle/token/{address}
POST https://www.trustgated.xyz/api/oracle/{…}   (body forwarded)

Open CORS. Forwarded payment headers: X-Payment, X-Payment-Required, X-Payment-Tx. There is also an upstream host configured as ORACLE_URL / NEXT_PUBLIC_ORACLE_URL. Browser clients should not call it. The proxy exists so they never hold those credentials.

Payment: x402

Paid endpoints use the x402 payment standard.

Challenge

Send the GET with no payment header.

GET /api/oracle/0x60C05e2d820CE989E944ED4e7bb33bAEB8705c62
→ 402 Payment Required

Body names the recipient, amount (0.001), currency (USDC), network (arc-testnet), and memo.

Settle

Transfer 0.001 USDC (6 decimals) on Arc Testnet to the stated recipient. USDC token: 0x3600000000000000000000000000000000000000.

Replay

Repeat the same GET with:

X-Payment: <base64 JSON { txHash, nonce, from, network: "Arc Testnet", chainId: 5042002, amount: "0.001", currency: "USDC", recipient }>
X-Payment-Tx: <txHash>

Successful payment replays return 200 with the score body. Rejected proofs return 422.

Wallet response (200)

The proxy re-scores a successful upstream body, strips any raw breakdown, and adds TrustGate fields:

{
  "address": "0x60C05e2d820CE989E944ED4e7bb33bAEB8705c62",
  "score": 57,
  "tier": "MEDIUM",
  "recommendation": "TIME_LOCKED",
  "confidence": 70,
  "flags": [],
  "summary": "Ordinary history. Nothing alarming, nothing exceptional.",
  "publicExplain": {
    "headline": "MEDIUM trust",
    "lines": []
  },
  "protocolExplain": {
    "categories": []
  },
  "scoreStability": "stable",
  "directionDrivers": [],
  "snapshotId": "snap_…",
  "scoringVersion": "v1.0",
  "queriedAt": "2026-08-15T10:42:13.094Z",
  "network": "arc-testnet",
  "source": "Arc Onchain Activity"
}

recommendation is how TrustGate’s own payment rails would route this score. It is not an instruction to your protocol.

`recommendation`	Meaning
`BLOCKED`	Score 0. Do not settle.
`TIME_LOCKED`	Score below 60. 24h hold path.
`INSTANT`	Score 60–79. Instant HIGH band.
`INSTANT_PRIORITY`	Score 80+. Same onchain HIGH band; UI-only priority.

tier is one of BLOCKED | LOW | MEDIUM | HIGH | HIGH_ELITE. publicExplain.tone is positive | neutral | caution | danger. NFT/contract branches on /api/oracle/token/{address} return confidence as HIGH|MEDIUM|LOW (string), not a number.

TypeScript sketch

async function getTrust(address: string) {
  const url = `https://www.trustgated.xyz/api/oracle/${address}`;
  const challenge = await fetch(url);
  if (challenge.status === 200) return challenge.json();
  if (challenge.status !== 402) {
    throw new Error(`Oracle error ${challenge.status}`);
  }
  const requirement = await challenge.json();
  const txHash = await sendUsdc({
    to: requirement.recipient,
    amount: requirement.amount,
  });
  const paid = await fetch(url, {
    headers: {
      "X-Payment": Buffer.from(
        JSON.stringify({
          txHash,
          nonce: crypto.randomUUID(),
          from: payer,
          network: "Arc Testnet",
          chainId: 5042002,
          amount: requirement.amount,
          currency: "USDC",
          recipient: requirement.recipient,
        })
      ).toString("base64"),
      "X-Payment-Tx": txHash,
    },
  });
  return paid.json();
}

Token oracle

GET /api/oracle/token/{address} is the Token Shield path. Official issuers short-circuit to VERIFIED. NFTs and non-token contracts are scored locally (free). ERC-20s go upstream and require x402 the same way. For a compact, free ERC-20 badge payload use /api/widget/score/{address} instead. TrustGate pays that hop.

Errors

Status	Meaning
`400`	Invalid address, or `CONTRACT_NOT_WALLET`
`402`	Payment required. Body is the requirement.
`422`	Payment proof rejected (wrong amount, recipient, or replayed nonce)
`502`	Upstream RPC / oracle failure. Retry once after backoff.

Wallet Trust Score

What the read means.

API reference

Every oracle-adjacent path.

Start Here

Guides

Reference

When to use this

Endpoints

Payment: x402

Wallet response (200)

TypeScript sketch

Token oracle

Errors

Wallet Trust Score

API reference

​When to use this

​Endpoints

​Payment: x402

​Wallet response (200)

​TypeScript sketch

​Token oracle

​Errors

​Related

Wallet Trust Score

API reference

When to use this

Endpoints

Payment: x402

Wallet response (200)

TypeScript sketch

Token oracle

Errors

Related