TrustGate Developer Documentation

curl https://api.trustgated.xyz/oracle/wallet/0xYourAddressHere

How It Works

Wallet or Contract Address
           ↓
   TrustGate Oracle
           ↓
Score + Tier + Confidence + Flags + Summary
           ↓
DEX  /  Lending  /  DAO  /  Wallet UI  /  AI Agent

1. Quick Start

Score a wallet:

curl -H "X-Payment: <x402_payment_header>" \
  https://api.trustgated.xyz/oracle/wallet/0xYourAddress

Score a contract or token:

curl https://api.trustgated.xyz/oracle/token/0xContractAddress

Wallet queries cost 0.001 USDC via the x402 payment standard. Token Shield queries for non-ERC-20 contracts are free.

2. Core Concepts

Wallet Score — A 0 to 100 behavioral score derived from a wallet's full onchain history. Deployments, transaction history, contract interactions, wallet age, USDC activity, and behavioral anomaly detection.

Contract Score — A 0 to 100 score for smart contracts. Auto-detects ERC-20 or non-ERC-20 and applies the correct scoring model.

Token Shield — The contract scoring engine. Scores ERC-20 tokens by holder quality and deployer credibility. Scores non-ERC-20 contracts by verification status, age, usage, unique interactors, deployer trust, and Arc ecosystem recognition.

Confidence — A percentage indicating how much historical data backs the score. A wallet with years of activity and thousands of transactions has high confidence. A wallet with minimal history has low confidence. Same tier, very different reliability. Protocols can set minimum confidence thresholds for high-stakes decisions.

Flags — Behavioral anomaly signals attached to a score. Each flag describes a detected pattern and carries a recommended protocol response.

Recommendation — An operational routing hint returned with every score: BLOCKED, TIME_LOCKED, INSTANT, or INSTANT_PRIORITY.

3. API Reference

GET /oracle/wallet/:address

Request:

curl -H "X-Payment: <x402_payment_header>" \
  https://api.trustgated.xyz/oracle/wallet/0xYourAddress

Response:

{
  "score": 82,
  "tier": "HIGH_ELITE",
  "confidence": 94,
  "recommendation": "INSTANT_PRIORITY",
  "flags": [],
  "summary": [
    "Consistent activity across 11 months",
    "12 verified contract deployments",
    "No coordinated behavior detected"
  ]
}

GET /oracle/token/:address

ERC-20 Response:

{
  "type": "ERC-20 TOKEN SCORE",
  "score": 71,
  "tier": "HIGH",
  "confidence": 88,
  "flags": ["COORDINATED_BUY"],
  "summary": [
    "Holder quality weighted: 340 qualified buyers",
    "Deployer tier: HIGH",
    "Coordinated buying pattern detected in first 3 hours"
  ]
}

Non-ERC-20 Response:

{
  "type": "CONTRACT SCORE",
  "score": 85,
  "tier": "HIGH_ELITE",
  "confidence": 91,
  "flags": [],
  "summary": [
    "Source code verified on Arcscan",
    "Contract age: 214 days",
    "Deployer tier: HIGH_ELITE",
    "Arc ecosystem interaction confirmed"
  ]
}

Error responses:

{ "error": "Address is not a contract. Use the Oracle page for wallet scoring." }

{
  "error": "Payment required",
  "paymentDetails": { "amount": "0.001", "currency": "USDC", "standard": "x402" }
}

4. Tier Meaning

Key caps to know:

• Any behavioral anomaly flag present: score cannot exceed MEDIUM tier
• Limited deployment history: score cannot exceed HIGH tier
• Unverified contract: score cannot exceed HIGH tier

5. Flag Reference

Wallet Flags

VELOCITY. Detected when a wallet exhibits abnormally high transaction activity within a short time window. Catches automated scripts and bot warm-up behavior. Suggested response: time-lock payments, increase collateral requirements.

INTERVAL_PATTERN. Detected when a wallet's transaction timing follows a suspiciously consistent mechanical cadence inconsistent with human behavior. Catches bots operating on fixed timers. Suggested response: same as VELOCITY.

SELF_INTERACTION. Detected when multiple transfers have matching sender and receiver addresses. Catches artificial activity inflation and wash loop manufacturing. Suggested response: reject for lending, time-lock for payments.

CLEAN_HISTORY_MANIPULATION. Detected when a fresh wallet has a volume of perfect contract interactions inconsistent with organic onchain behavior. Legitimate wallets almost always have some failed transactions. Wallets with sufficient age are completely immune to this flag. Suggested response: time-lock, require additional observation period.

COORDINATED_BUYING. Detected when multiple wallets funded from the same source interact with the same contracts in the same time window. Catches Sybil clusters, airdrop farming rings, and coordinated attacks. Suggested response: flag for governance review, reject for high-value lending.

Token and Contract Flags

HONEYPOT_PATTERN. Detected when sell volume is near zero relative to buy volume after the initial distribution period. Buyers cannot exit. Suggested response: surface warning to users, block trust badge from showing positive tier.

COORDINATED_BUY. Detected when a large share of token buyers are active within the same short window. Suggested response: discount holder quality signal, surface warning badge.

EXIT_SYNC. Detected when multiple credible wallets exit significant positions within the same rolling window, regardless of how long they held. A group of wallets holding for months then selling within the same short window is a coordinated exit, not coincidence. All participating wallets receive a persistent mark that affects future scoring. Suggested response: increase collateral ratio, monitor governance participation, lower leverage limits.

LOW_HOLDER_QUALITY. Detected when the majority of token holders are LOW or BLOCKED tier wallets. Suggested response: surface risk warning, reduce trust weighting for token.

WASH_TRADE. Detected when wallets repeatedly buy and sell the same token within short windows with circular address patterns. Suggested response: flag token, discount volume signals entirely.

INTERACTION_VELOCITY (contract). Detected when a contract receives an unusually high number of transactions shortly after deployment. Organic adoption is gradual. Suggested response: treat as MEDIUM regardless of other signals until the flag clears.

6. Integration Examples

React

import { useEffect, useState } from "react";

export function TrustBadge({ address }) {
  const [trust, setTrust] = useState(null);

  useEffect(() => {
    fetch(`https://api.trustgated.xyz/oracle/wallet/${address}`)
      .then(res => res.json())
      .then(data => setTrust(data));
  }, [address]);

  if (!trust) return <span>Checking trust...</span>;

  return (
    <div className={`trust-badge tier-${trust.tier.toLowerCase()}`}>
      <span>{trust.tier}</span>
      <span>{trust.score}/100</span>
      {trust.flags.length > 0 && <span>⚠ {trust.flags.join(", ")}</span>}
    </div>
  );
}

Node.js

const axios = require("axios");

async function checkWalletTrust(address) {
  const res = await axios.get(
    `https://api.trustgated.xyz/oracle/wallet/${address}`,
    { headers: { "X-Payment": process.env.X402_PAYMENT_HEADER } }
  );
  const { score, tier, recommendation, flags } = res.data;
  if (recommendation === "BLOCKED") throw new Error("Wallet blocked");
  if (flags.includes("COORDINATED_BUYING")) throw new Error("Coordinated behavior detected");
  return { score, tier, recommendation };
}

Solidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface ITrustGate {
    function getScore(address wallet) external view returns (uint8 score, string memory tier);
}

contract TrustGatedLending {
    ITrustGate public trustGate;
    uint8 public constant MIN_SCORE = 60;

    constructor(address _trustGate) {
        trustGate = ITrustGate(_trustGate);
    }

    modifier onlyTrusted(address wallet) {
        (uint8 score, ) = trustGate.getScore(wallet);
        require(score >= MIN_SCORE, "Trust score too low");
        _;
    }

    function borrow(uint256 amount) external onlyTrusted(msg.sender) {
        // lending logic
    }
}

Python

import requests

def get_trust_score(address: str) -> dict:
    url = f"https://api.trustgated.xyz/oracle/wallet/{address}"
    headers = {"X-Payment": "YOUR_X402_PAYMENT_HEADER"}
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
    return {
        "score": data["score"],
        "tier": data["tier"],
        "confidence": data["confidence"],
        "recommendation": data["recommendation"],
        "flags": data["flags"]
    }

7. Use Cases

Lending Protocol. Gate borrowing positions behind trust scoring. Require HIGH tier for standard loans, HIGH_ELITE for uncollateralized credit lines. Escrow or reject LOW and BLOCKED wallets automatically.

DEX Token Discovery. Rank token search results by trust score when multiple tokens share the same name or ticker. The token with the most credible deployer, legitimate holder base, and cleanest behavioral record surfaces first.

Governance Defense. Monitor proposals for coordinated voting patterns. Alert when low-trust wallets vote the same direction in a short window on a treasury proposal. Alert fires before the vote closes.

Wallet Warning System. Surface trust tier and active flags at the point of send before a user signs a transaction. A BLOCKED or LOW destination gets a warning. No code changes needed on the destination contract.

AI Agent Payments. Gate agent-to-agent USDC payments behind trust scoring. HIGH_ELITE agents receive instant settlement. LOW agents route through escrow with configurable release conditions.

Stablecoin Risk Management. Check trust tier of wallets interacting with stablecoin pools. Use confidence scores to weight risk decisions — the same tier at low confidence is treated differently than the same tier at high confidence.

8. Pricing and Limits

Rate limits: 60 requests per minute per API key.

Payment standard: Circle x402 Nanopayment on Arc. Every paid query includes an X-Payment header with the USDC transaction reference. No subscription required for per-query access.

9. Security and Philosophy

TrustGate analyzes behavioral reputation, not identity.

TrustGate models behavioral reputation, not personal identity. It cannot tell you who owns a wallet. It can tell you what that wallet has done, how its behavior has changed over time, and whether its patterns signal risk. This distinction matters legally and operationally — behavioral reputation infrastructure is a fundamentally different category from identity systems.

TrustGate scores reflect immutable onchain history. Rehabilitation mechanics are handled through longitudinal behavioral recovery rather than manual appeals.

Score hardening: exact formula weights, thresholds, and scoring mechanics are not published. Public responses return tier, score, confidence, flags, and summary only. This prevents adversaries from reverse-engineering an optimization path. Developers integrating TrustGate consume the signal — they do not need to reproduce the calculation.

10. Roadmap

• Token Behavior Intelligence — hold duration tracking, exit ratio analysis, wash trading detection, honeypot flagging, wallet score feedback loop
• Staking Intelligence — staking history as a trust signal dimension
• DAO Risk Alerts — subscription alerts for lending protocols and DAOs
• Send Address Shield — trust scoring at point of send in wallet UIs (Rabby, MetaMask Snaps)
• Multichain Expansion — Arc, Ethereum, Base, Arbitrum with cross-chain composite scoring
• Trust Graph — EigenTrust-style network analysis, Sybil resistance, coordinated cluster detection