402coffee-verify

402coffee-verify

Gate payments on verified x402 agents. One free call to 402.coffee tells you whether a paying agent holds a current certificate proving it pays correctly, refuses deliberately over-priced orders, and checks who it's paying — before you transact with it.

• Free — the /verify check costs nothing. (An optional paid /score gives a decision-grade 0–100 risk number.)
• Zero dependencies, Node 18+.
• Composes with your existing trust/reputation stack: those tell you the counterparty was worth paying; this tells you the agent won't get swapped at signing.

Install

npm install 402coffee-verify

Library

import { verify, passesGate, verifyGate } from "402coffee-verify";

// Raw status
const result = await verify("0xAGENT…");
result.verified;                       // true = ≥1 current PASS, no current FAIL
result.capabilities.scam_resistance;   // { tested, result, fresh, expired, valid_until }

// One-shot gate
const { ok } = await verifyGate("0xAGENT…", {
  require: ["scam_resistance", "recipient_awareness"], // must hold these
  fresh: true,                                         // non-expired cert required
});
if (!ok) throw new Error("agent not certified safe");

CLI

npx 402coffee-verify 0xAGENT… --require scam_resistance,recipient_awareness
# exit 0 = pass, 1 = fail, 2 = usage/network error → drop straight into CI/scripts

Middleware (Express)

import { requireVerifiedAgent } from "402coffee-verify/middleware";

// Reads the wallet from the `x-agent-wallet` header (override with getWallet)
app.post("/paid-endpoint",
  requireVerifiedAgent({ require: ["scam_resistance"], fresh: true }),
  handler
);

Next.js App Router / hono / edge

import { guardAgent } from "402coffee-verify/middleware";

export async function POST(req) {
  const wallet = req.headers.get("x-agent-wallet");
  const gate = await guardAgent(wallet, { require: ["recipient_awareness"] });
  if (!gate.ok) return gate.response;   // ready 402 Response
  // …serve the paid action…
}

Paid score (optional, $0.10)

/score returns a deterministic 0–100 risk score with itemized on-chain evidence. It costs $0.10 in USDC on Base, so you must pass an x402-paying fetch (e.g. wrapFetchWithPayment from @x402/fetch) — with a plain fetch you get back the 402 payment terms, not a score.

import { score } from "402coffee-verify";
import { wrapFetchWithPayment } from "@x402/fetch";

const payingFetch = wrapFetchWithPayment(fetch, wallet);
const s = await score("0xAGENT…", { fetchImpl: payingFetch });
// s.score, s.tier, s.components, s.payment_history …

What "verified" means

verified === true only when the agent has at least one current (non-expired) PASS and no current FAIL. Certificates are valid for 30 days (behaviour drifts); require a fresh one for anything that matters. Every result 402.coffee returns is a fact it observed on-chain — never a subjective grade or a safety guarantee.

Docs: https://api.402.coffee/docs · Test your own agent: https://api.402.coffee/inspect

MIT © Agent Café / 402.coffee