📡 REST API v1

API Reference

The TrustGrade API provides programmatic access to trust scores for crypto entities. All endpoints return JSON. Base URL: https://api.trustgrade.ai

Authentication

All endpoints except /v1/health and /v1/stats require a Bearer token. Get your API key from the TrustGrade dashboard.

http Auth Header

Authorization: Bearer tg_live_xxxxxxxxxxxxxxxxxxxxxxxx

Rate Limits

Tier	Limit	Price	Best For
Free	100 requests/day	$0	Testing & prototypes
Builder	25,000 requests/day	$49/mo	Production agents
Pro	250,000 requests/day	$199/mo	High-volume platforms
Enterprise	Unlimited	Custom	Institutional

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Public Endpoints

GET /v1/health

Health check. No authentication required.

bash

curl https://api.trustgrade.ai/v1/health

# Response:
{
  "status": "ok",
  "version": "2.0.0",
  "timestamp": "2026-07-12T10:54:46.487Z"
}

GET /v1/stats

Protocol statistics. No authentication required.

bash

curl https://api.trustgrade.ai/v1/stats

# Response:
{
  "totalEntities": 45,
  "entityTypes": 8,
  "avgScore": 82,
  "avgResponseTime": "47ms",
  "lastUpdate": "2026-07-12T10:54:46.487Z"
}

GET /v1/entity-types

List all supported entity types for trust scoring.

bash

curl https://api.trustgrade.ai/v1/entity-types

# Response:
{
  "types": [
    { "type": "defi_protocol", "name": "DeFi Protocol" },
    { "type": "stablecoin", "name": "Stablecoin" },
    { "type": "ai_agent", "name": "AI Agent" },
    { "type": "smart_contract", "name": "Smart Contract" },
    { "type": "token", "name": "Token" },
    { "type": "nft_collection", "name": "NFT Collection" },
    { "type": "dao", "name": "DAO" }
  ]
}

GET /v1/score/:type/:id

Retrieve a cached trust score for a specific entity. Requires authentication.

bash Cached Score Lookup

curl https://api.trustgrade.ai/v1/score/defi_protocol/Uniswap \
  -H "Authorization: Bearer $TRUSTGRADE_KEY"

# Response:
{
  "entity": "Uniswap",
  "type": "defi_protocol",
  "score": 100,
  "grade": "A+",
  "confidence": 0.8837,
  "summary": "Exceptional trust profile. TVL stability and audit coverage above average.",
  "breakdown": {
    "wilson": 0.9855,
    "bayesian": 0.7866,
    "incidentPenalty": 0,
    "volumeBonus": 7.25
  },
  "computedAt": "2026-07-12T10:54:46.480Z"
}

POST /v1/score — Compute Trust Score

Compute a fresh trust score from raw signals. Accepts two formats: v1 core signals (simple) and v2 timestamped signals (advanced).

Request Body (v1 Core Signals)

Field	Type	Required	Description
`entityType`	string	Yes	Entity type (e.g. `defi_protocol`)
`entityId`	string	Yes	Entity name or identifier
`core.successRate`	number (0–1)	Yes	Observed positive outcome rate
`core.sampleSize`	number	Yes	Total observations backing successRate
`core.verificationRate`	number (0–1)	Yes	Secondary verification rate
`core.incidentShare`	number (0–1)	Yes	Share of incidents/anomalies
`optionals`	OptionalSignal[]	No	Entity-specific weighted signals

bash v1 Core Signals

curl -X POST https://api.trustgrade.ai/v1/score \
  -H "Authorization: Bearer $TRUSTGRADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "defi_protocol",
    "entityId": "MyProtocol",
    "core": {
      "successRate": 0.95,
      "sampleSize": 500,
      "verificationRate": 0.88,
      "incidentShare": 0.02
    },
    "optionals": [
      {
        "key": "tvl_stability",
        "label": "TVL Stability (30-day)",
        "value": 0.93,
        "weight": 14
      },
      {
        "key": "audit_coverage",
        "label": "Audit Coverage",
        "value": 1.0,
        "weight": 16
      }
    ]
  }'

bash v2 Timestamped Signals

// v2 timestamped signals format
curl -X POST https://api.trustgrade.ai/v1/score \
  -H "Authorization: Bearer $TRUSTGRADE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "stablecoin",
    "entityId": "MYUSD",
    "version": 2,
    "signals": [
      {
        "key": "successRate",
        "value": 0.97,
        "timestamp": "2026-07-12T10:00:00Z"
      },
      {
        "key": "sampleSize",
        "value": 1200,
        "timestamp": "2026-07-12T10:00:00Z"
      },
      {
        "key": "verificationRate",
        "value": 0.92,
        "timestamp": "2026-07-12T10:00:00Z"
      },
      {
        "key": "incidentShare",
        "value": 0.01,
        "timestamp": "2026-07-12T10:00:00Z"
      }
    ],
    "optionals": [...]
  }'

Scoring Methodology

The TrustGrade Score is a composite of five mathematical layers:

1. Wilson Score Lower Bound

W = (p + z²/2n − z·√(p(1−p)/n + z²/4n²)) / (1 + z²/n)

The conservative lower bound of the 95% confidence interval for a binomial proportion. Requires substantial evidence to score high — 95% success over 10 samples doesn't cut it. z = 1.96 (95% CI) for most entities; z = 2.24 (97.5% CI) for stablecoins.

2. Bayesian Beta Posterior

B = (v·n + α₀) / (n + α₀ + β₀)

Sceptical Beta(α₀, β₀) prior updated with observed data. When sample size is small, the estimate shrinks toward the conservative prior mean. Default: α₀=2, β₀=5.

3. Compound Incident Penalty

P = 1 − (1 − s)²

Quadratic penalty on incident share. Grows faster than linear: 10% incidents → 19% penalty, 30% → 51%, 50% → 75%. This ensures repeated incidents compound rather than average out.

4. Log-Credibility Volume Bonus

B = min(cap, log₁₀(n) × k)

Rewards sample size on a logarithmic scale. 100 samples → ~2×k bonus. 1000 → ~3×k. Diminishing returns prevent large datasets from dominating. Cap depends on entity type.

5. Optional Weighted Signals

contribution = (value − 0.5) × weight

Each entity type defines its own signals (TVL stability, audit coverage, exploit history, etc.). Value normalized to [0,1]. Contribution ranges from −weight/2 (worst) to +weight/2 (best).

Composite Score Formula

text Composite Formula

score = round(clamp(
  W × wilsonWeight
  + B × bayesianWeight
  + volumeBonus
  - P × incidentWeight
  + Σ(optional contributions)
, 0, 100))

Grade Thresholds

Score	Grade	Color
97–100	A+	🟢 Green
93–96	A	🟢 Green
90–92	A−	🟢 Teal
87–89	B+	🟢 Dark Green
83–86	B	🟢 Lime
80–82	B−	🟢 Light Lime
75–79	C+	🟡 Amber
70–74	C	🟡 Amber
65–69	C−	🟡 Light Amber
60–64	D+	🟠 Orange
55–59	D	🟠 Orange
50–54	D−	🟠 Light Orange
0–49	F	🔴 Red

CoreSignals Schema

Required for every score computation. These are the non-negotiable inputs.

Field	Type	Range	Description
`successRate`	number	0–1	Observed success/positive rate. For DeFi: audit pass rate. For stablecoins: peg stability. For agents: transaction success rate.
`sampleSize`	number	≥0	Total observations. More data = higher volume bonus and Wilson confidence.
`verificationRate`	number	0–1	Secondary verification rate (e.g. on-chain verification percentage).
`incidentShare`	number	0–1	Share of flagged incidents/anomalies. Feeds compound penalty.

OptionalSignal Schema

Entity-specific weighted signals. Each entity type defines its own set.

Field	Type	Range	Description
`key`	string	—	Unique identifier (e.g. `tvl_stability`)
`label`	string	—	Human-readable label
`value`	number \| null	0–1	Normalized signal value. null = not available.
`weight`	number	—	Max absolute point contribution. Contribution = (value − 0.5) × weight.

Error Codes

Code	Meaning	When
`400`	Bad Request	Invalid input — missing required fields, values out of range
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Entity not in registry (for cached lookups)
`429`	Rate Limited	Exceeded daily request quota. Check `X-RateLimit-Reset`.
`500`	Internal Error	Scoring engine failure. Retry with exponential backoff.

json Error Response

// 429 Response example
{
  "error": "Rate limit exceeded",
  "message": "Daily quota of 100 requests exceeded. Resets at 00:00 UTC.",
  "retryAfter": 3600,
  "tier": "free"
}

SDK Examples

Python

python agent.py

pip install trustgrade

from trustgrade import TrustGrade

client = TrustGrade(api_key="tg_live_xxx")

# Cached score lookup
score = client.score("defi_protocol", "Uniswap")
print(f"{score.entity}: {score.grade} ({score.score}/100)")

# Compute new score
result = client.compute(
    entity_type="defi_protocol",
    entity_id="MyProtocol",
    core={
        "successRate": 0.95,
        "sampleSize": 500,
        "verificationRate": 0.88,
        "incidentShare": 0.02
    },
    optionals=[
        {"key": "tvl_stability", "label": "TVL Stability", "value": 0.93, "weight": 14}
    ]
)
print(f"Computed: {result.grade} ({result.score}/100)")

JavaScript / TypeScript

javascript agent.ts

npm install @trustgrade/sdk

import { TrustGrade } from '@trustgrade/sdk';

const tg = new TrustGrade({ apiKey: process.env.TRUSTGRADE_KEY });

// Cached lookup
const score = await tg.score('stablecoin', 'USDC');
console.log(`${score.entity}: ${score.grade} (${score.score}/100)`);

// Compute new
const result = await tg.compute({
  entityType: 'defi_protocol',
  entityId: 'MyProtocol',
  core: {
    successRate: 0.95,
    sampleSize: 500,
    verificationRate: 0.88,
    incidentShare: 0.02,
  },
  optionals: [
    { key: 'tvl_stability', label: 'TVL Stability', value: 0.93, weight: 14 }
  ],
});

cURL

bash Quick Start

# Set your API key
export TRUSTGRADE_KEY="tg_live_xxx"

# Check a score
curl -s https://api.trustgrade.ai/v1/score/stablecoin/USDC \
  -H "Authorization: Bearer $TRUSTGRADE_KEY" | jq .grade
# → "B-"