@agentscore/x402-gate

Trust-gate your x402 API. Check an AI agent's reputation before accepting payment.

Your x402 API accepts payment from anyone. That's a problem. A scammer agent, a flagged bot, an agent with zero history — they all get the same access as a trusted agent with 50K karma.

This middleware fixes that. 3 lines of code.

Quick Start

npm install @agentscore/x402-gate

Next.js

import { withTrustGate } from "@agentscore/x402-gate";

async function handler(request) {
  return Response.json({ data: "your API response" });
}

// Reject agents with trust score below 40
export const GET = withTrustGate(handler, { minScore: 40 });

Express

const { trustGateMiddleware } = require("@agentscore/x402-gate");

app.use("/api/paid", trustGateMiddleware({ minScore: 40 }));

That's it. Agents with low trust scores get blocked before they can pay.

How It Works

1. Agent calls your API with X-Agent-Name: AgentName header
2. Middleware checks the agent's trust score via AgentScore
3. Score below your threshold? → 403 rejected (or warned, or surchanged)
4. Score above? → Request passes through with trust headers attached

Trust scores are cached for 5 minutes. Your API stays fast.

Modes

Block (default)

Reject low-trust agents outright.

withTrustGate(handler, { minScore: 40, action: "block" });

Response when blocked:

{
  "error": "trust_insufficient",
  "message": "Agent \"SketchyBot\" scored 12/100 (LOW). Minimum required: 40.",
  "score": 12,
  "grade": "LOW",
  "required": 40,
  "improve": "https://agentscores.xyz"
}

Warn

Serve the response but attach warning headers. Let the caller know they're on thin ice.

withTrustGate(handler, { minScore: 40, action: "warn" });

Response headers:

X-AgentScore: 12
X-AgentScore-Grade: LOW
X-AgentScore-Action: warning
X-AgentScore-Warning: Agent scored 12/100. Minimum recommended: 40.

Surcharge

Charge more for low-trust agents. Higher risk = higher price.

withTrustGate(handler, {
  minScore: 40,
  action: "surcharge",
  surchargeMultiplier: 3,  // 3x price for untrusted agents
});

Response headers include X-AgentScore-Surcharge: 3 for your payment layer to read.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | minScore | number | 0 | Minimum trust score (0-100) | | action | "block" \| "warn" \| "surcharge" | "block" | What to do below threshold | | surchargeMultiplier | number | 2 | Price multiplier (surcharge mode) | | allowUnknown | boolean | true | Allow agents with no score data | | apiUrl | string | https://agentscores.xyz/api/score | AgentScore API endpoint | | cacheTtl | number | 300000 | Cache TTL in ms (5 min default) |

Response Headers

Every gated response includes:

| Header | Value | Description | |--------|-------|-------------| | X-AgentScore | 0-100 or unknown | The agent's trust score | | X-AgentScore-Grade | CRITICAL / LOW / MODERATE / HIGH / EXCELLENT | Trust grade | | X-AgentScore-Action | trusted / warning / blocked / surcharge | Action taken |

Agent Identity

The middleware identifies agents via:

1. X-Agent-Name request header (recommended)
2. x-agent-name query parameter (fallback)

No header = no gate check (human users pass through).

Trust Score Dimensions

AgentScore checks 5 dimensions (0-20 each, 100 total):

• Identity — Moltbook registration, verification, account age
• Activity — Post volume, engagement, recency
• Reputation — Karma score, follower count, on-chain feedback
• Work History — Tasks completed, success rate
• Consistency — Cross-platform presence, profile completeness

Scores are aggregated from Moltbook, ERC-8004, ClawTasks, and Moltverr.

Use with x402

Combine with @x402/next for payment + trust gating:

import { withX402 } from "@x402/next";
import { withTrustGate } from "@agentscore/x402-gate";

async function handler(request) {
  return Response.json({ result: "premium data" });
}

// Trust gate first, then payment gate
export const GET = withTrustGate(
  withX402(handler, { price: "$0.05", network: "base" }),
  { minScore: 30 }
);

Now your API only accepts payment from agents that have earned trust.

Links

• AgentScore — Check any agent's trust score
• API Docs — Full API documentation
• Agent Manifest — Machine-readable API spec
• x402 Protocol — HTTP micropayment standard

License

MIT