API Reference

Oracle API

A public, payable HTTP API that returns onchain trust scores for any Arc wallet. Each query costs 0.001 USDC, settled on Arc through the x402 payment standard.

Base URL

http://38.49.216.201:3001

The base URL is exposed to the frontend through the NEXT_PUBLIC_ORACLE_URL environment variable. All endpoints accept JSON and respond with JSON.

Payment: x402

Paid endpoints use the x402 payment standard. An unpaid request returns HTTP 402 with a payment requirement that names the recipient address and amount. The client settles the transfer on Arc, then re-sends the same request with an X-Payment header carrying the proof. Successful payment replays return HTTP 200 with the score body.

# Step 1 — unpaid request
GET http://38.49.216.201:3001/trust/0x60C05e2d820CE989E944ED4e7bb33bAEB8705c62
→ 402 Payment Required
  {
    "amount": "0.001",
    "currency": "USDC",
    "network": "arc-testnet",
    "recipient": "0x...",
    "memo": "trust-query"
  }

# Step 2 — settle 0.001 USDC on Arc, then replay with proof
GET http://38.49.216.201:3001/trust/0x60C05e2d820CE989E944ED4e7bb33bAEB8705c62
X-Payment: <base64(JSON{txHash, nonce})>
→ 200 OK
  { ...score body... }

GET /trust/:address

Returns the trust score, tier, and full breakdown for a single Arc wallet. The address must be a 40-character hex string with the 0x prefix.

Request

curl -H "X-Payment: <token>" \
  http://38.49.216.201:3001/trust/0x60C05e2d820CE989E944ED4e7bb33bAEB8705c62

Response (200)

{
  "address": "0x60C05e2d820CE989E944ED4e7bb33bAEB8705c62",
  "score": 57,
  "tier": "MEDIUM",
  "recommendation": "Time-locked routing (24h hold)",
  "breakdown": {
    "txPoints": 40,
    "usdcPoints": 0,
    "contractPoints": 7,
    "deploymentPoints": 10,
    "txCount": 29,
    "usdcBalance": "13879355",
    "contractInteractions": 13,
    "deployments": 16
  },
  "queriedAt": "2026-04-25T10:42:13.094Z",
  "network": "arc-testnet",
  "source": "Arc Onchain Activity"
}

Fields

address — the queried wallet, lowercased to checksum-equivalent form.
score — integer 0 – 100.
tier — one of BLOCKED | LOW | MEDIUM | HIGH | HIGH_ELITE.
recommendation — the routing path TrustGate would take for this score, in plain English.
breakdown — every signal that contributed to the score, including the raw counts.
breakdown.usdcBalance — raw 6-decimal USDC balance (divide by 10⁶ for human units).
queriedAt — ISO-8601 timestamp of the snapshot.

POST /trust/batch

Score up to 10 addresses in a single request. The whole batch settles in one x402 payment of 0.001 USDC × addressCount.

Request

curl -X POST -H "X-Payment: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "0x60C05e2d820CE989E944ED4e7bb33bAEB8705c62",
      "0x52E17bC482d00776d73811680CbA9914e83E33CC"
    ]
  }' \
  http://38.49.216.201:3001/trust/batch

Response (200)

{
  "results": [
    { "address": "0x60C0...5c62", "score": 57, "tier": "MEDIUM", "breakdown": { ... } },
    { "address": "0x52E1...33CC", "score": 92, "tier": "HIGH",   "breakdown": { ... } }
  ],
  "queriedAt": "2026-04-25T10:42:13.094Z",
  "network": "arc-testnet"
}

GET /health

Liveness probe. No payment required. Returns 200 with a small version object the operator can use for monitoring.

Response (200)

{
  "status": "ok",
  "uptimeSeconds": 12345,
  "version": "1.0.0"
}

Errors

400 — invalid address or batch over 10 entries.
402 — payment required. Body contains the requirement to settle.
422 — payment proof rejected (wrong amount, wrong recipient, replayed nonce).
502 — upstream Arc RPC or Arcscan returned an error. Retry once after a backoff.