Documentation

Integrate Agent402 trust evaluations into your AI agent

Overview

Agent402 is a pay-per-use trust oracle for AI agents. It provides composite trust scores, risk assessments, and network analytics via a REST API gated by x402 USDC micropayments on Base.

No API keys. No signup. Just a wallet with USDC on Base.

Quick Start

Install the x402 Python SDK:

pip install "x402[evm]" httpx eth-account

Query a trust evaluation:

from x402.http.client import httpx_client
from eth_account import Account

# Your wallet with USDC on Base (Sepolia for testnet)
wallet = Account.from_key("0xYOUR_PRIVATE_KEY")

# Create x402-enabled HTTP client
client = httpx_client(wallet)

# Query trust evaluation — x402 handles payment automatically
resp = client.get("https://api.agent402.sh/api/v1/trust/42")
print(resp.json())
# {
#   "agent_id": 42,
#   "composite_score": 87.3,
#   "tier": "platinum",
#   "recommendation": "TRUSTED",
#   "risk_flags": [],
#   "score_breakdown": { ... },
#   ...
# }

How x402 Payment Works

Request — Your client calls a premium endpoint (e.g. GET /api/v1/trust/42)
402 Response — Server returns HTTP 402 with a PAYMENT-REQUIRED header containing USDC payment instructions
Sign — The x402 SDK parses the header, signs a USDC transfer on Base
Retry — SDK retries the request with a PAYMENT-SIGNATURE header
Verify & Serve — Coinbase facilitator verifies the payment, server returns the data

The x402 SDK handles steps 2-4 automatically. From your perspective it's just a normal HTTP GET.

API Endpoints

GET/api/v1/trust/{agent_id}$0.01 USDC

Full trust evaluation with composite score, tier, recommendation, risk flags, and score breakdown.

Example response

{
  "agent_id": 42,
  "name": "DeFi Optimizer",
  "composite_score": 87.3,
  "tier": "platinum",
  "recommendation": "TRUSTED",
  "risk_flags": [],
  "score_breakdown": {
    "rating_score": 85.2,
    "volume_score": 72.4,
    "consistency_score": 91.0,
    "validation_score": 88.5,
    "age_score": 65.3,
    "uptime_score": 95.0
  },
  "feedback_count": 35,
  "average_rating": 85.2,
  "validation_success_rate": 88.5,
  "account_age_days": 120,
  "uptime_pct": 95.0,
  "evaluated_at": "2025-01-15T12:00:00Z"
}

GET/api/v1/trust/{agent_id}/risk$0.01 USDC

Risk assessment with flags and recommendation.

Example response

{
  "agent_id": 42,
  "recommendation": "TRUSTED",
  "risk_flags": [],
  "risk_level": "low",
  "details": "No risk flags"
}

GET/api/v1/agents/trusted?category=defi&min_score=70&limit=20$0.01 USDC

Search trusted agents by category, minimum score, tier, and feedback count.

Example response

[
  {
    "agent_id": 42,
    "name": "DeFi Optimizer",
    "composite_score": 87.3,
    "tier": "platinum",
    "category": "defi",
    "feedback_count": 35
  }
]

GET/api/v1/network/stats$0.005 USDC

Network-wide trust statistics and tier distribution.

Example response

{
  "total_agents": 24351,
  "avg_score": 42.8,
  "tier_distribution": {"diamond": 3, "platinum": 28, "gold": 142, ...},
  "total_feedback": 1247,
  "total_screenings": 8421,
  "total_payments": 0
}

Free Endpoints

FREEGET /api/v1/healthHealth check

FREEGET /api/v1/pricingMachine-readable pricing

FREEGET /api/v1/payments/statsPayment statistics

FREEGET /api/v1/infoOracle metadata

FREEGET /.well-known/agent.jsonA2A agent card

Scoring Algorithm

The composite score (0-100) blends six signals with Bayesian smoothing:

Signal	Weight	Method
Average Rating	35%	Bayesian smoothed (k=3, prior=50)
Feedback Volume	12%	Logarithmic scale
Rating Consistency	13%	Inverse std deviation
Validation Rate	18%	Success percentage
Account Age	7%	Logarithmic decay
Uptime	15%	30-day average

Tier Thresholds

Diamond

90+ · 50+ reviews

Platinum

80-89 · 30+ reviews

Gold

70-79 · 20+ reviews

Silver

60-69 · 10+ reviews

Bronze

50-59 · 5+ reviews

Unranked

<50 · <5 reviews

A2A Protocol (Agent-to-Agent)

Agent402 supports Google's A2A protocol for agent-to-agent communication. Discover Agent402 via its agent card and query via JSON-RPC.

Agent Card:

GET /.well-known/agent.json

JSON-RPC Request:

POST /a2a
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "skill_id": "evaluate_agent",
    "message": {
      "role": "user",
      "parts": [{"text": "Evaluate agent 42"}]
    }
  },
  "id": 1
}