Trace API · v1

Reputation as infrastructure.

A single drop-in endpoint to gate mints, roles, and apps by TRACE tier and score. Real wallets, real X accounts, real on-chain footprints, read live. Zero SDK required.

1 · Authentication

Every request carries a bearer token in the Authorization header. Each key has a configurable monthly request quota and can be rotated or revoked at any time without code changes on your side.

Authorization: Bearer trace_<your_key_here>

Keys start with trace_ so a leaked one is obvious in logs and GitHub secret-scan. Treat them like database passwords: keep them in environment variables, never commit them, rotate immediately if exposed.

2 · Eligibility check

Look up a wallet or a handle and check it against an optional minimum tier and/or score. AND-semantics on the filters.

GET /api/v1/check?wallet=0xabc...&min_tier=ELITE
GET /api/v1/check?handle=foo&min_score=750

Request

wallet	0x-prefixed 40-hex. Either this or handle required.
handle	X handle (no @). Either this or wallet required.
min_tier	CIVILIAN \| PRIME \| ORIGIN \| ELITE \| SOVEREIGN. Optional. Subject's tier must be at or above this rank.
min_score	0..1000. Optional. Subject's score must be at or above this value.

Response (200)

{
  "eligible": true,
  "handle": "foo",
  "wallet": "0xabc...",
  "tier": "ELITE",
  "score": 821,
  "verification": "VERIFIED",
  "min_tier": "ELITE",
  "min_score": 0,
  "reason": "ok",
  "usage": { "monthly_used": 412, "monthly_remaining": 9588 }
}

Reasons

ok	Subject meets every filter. Use eligible=true.
not_found	No TRACE profile for that wallet or handle.
tier_below_threshold	Subject's tier is below min_tier.
score_below_threshold	Subject's score is below min_score.

3 · Quotas and errors

Quotas reset on the first of each month UTC. Standard HTTP codes; the body always carries an error string on non-2xx.

200	Request succeeded. eligible may still be false.
400	Bad request. wallet/handle missing, malformed, or unknown query param.
401	Missing, invalid, revoked, or quota-exceeded API key. Body distinguishes the cause.

4 · Examples

curl

curl -s \
  -H "Authorization: Bearer $TRACE_API_KEY" \
  "https://traceeco.io/api/v1/check?wallet=0xabc...&min_tier=ELITE"

node / fetch

const r = await fetch(
  `https://traceeco.io/api/v1/check?wallet=${addr}&min_tier=ELITE`,
  { headers: { Authorization: `Bearer ${process.env.TRACE_API_KEY}` } }
);
const d = await r.json();
if (d.eligible) await grantMint(addr);

Discord role assignment

// On member join, look up their linked handle and assign a role
// only if they're Origin or higher with verification.
const r = await fetch(
  `https://traceeco.io/api/v1/check?handle=${handle}&min_tier=ORIGIN`,
  { headers: { Authorization: `Bearer ${process.env.TRACE_API_KEY}` } }
);
const d = await r.json();
if (d.eligible && d.verification === "VERIFIED") {
  await member.roles.add(VERIFIED_ROLE);
}

5 · Get a key

API keys are issued by request. Reach out via @traceeco_io with your project name and expected request volume.