Guard — the toll gate
Any paid API,
one guard line.
x402 lets agents pay for API calls over HTTP — but payment is not trust. hankoGuard checks every caller against the registry before the paywall fires: sealed agents pass through, unregistered and slashed agents are turned away at the gate. A broken seal cannot buy its way in.
The one line
npm install @hankolabs/x402-middleware
import express from "express";
import { hankoGuard } from "@hankolabs/x402-middleware";
const app = express();
// Sealed agents pass. Unregistered and slashed
// callers get 401 before the paywall fires.
app.use("/paid", hankoGuard());
// Optional: raise the bar for sensitive endpoints
// with hankoGuard({ minKarma: 500, requireDomain: true })
app.get("/paid/analytics", (req, res) => {
res.json({ ok: true, tier: req.hanko?.tier });
});The caller identifies its agent with the X-Hanko-Agent header. Every decision is one cached call to the registry's verification endpoint — the same one this page's simulator hits.
Live simulator — mainnet registry
Walk an agent through the gate
GET /paid/analytics HTTP/1.1
X-Hanko-Agent: 4PtVeqJGfv4Pvx2jFTFXTA7GvM4XouNwpXgDLNE8UEdT
hankoGuard → POST /x402/verify
What the gate checks, in order
01
Identity
Is the agent registered on-chain? Unknown pubkeys are rejected before anything else runs.
agent_not_registered
02
Slash history
One broken seal is permanent. Slashed agents are rejected regardless of karma or payment.
agent_slashed
03
Domain binding
Optionally require the AgentCard JWS plus DNS binding to be verified end to end.
domain_binding_unverified
04
Karma floor
The indexer-computed score must clear your minKarma threshold for the endpoint.
karma_below_threshold
Where the guard sits in the x402 flow
Trust first, then the 402
Guard
POST /x402/verify — unregistered or slashed callers stop here with 401.
Challenge
Trusted caller without payment gets 402 with the exact-scheme requirements (CAIP-2 network id).
Sign
The agent signs the transfer for the quoted amount — no account, no API key, one HTTP retry.
Retry
Same request again, now carrying the X-PAYMENT header with the signed payload.
Serve
The payment layer settles and the endpoint responds 200 with X-PAYMENT-RESPONSE.
The guard never touches funds — it decides who is allowed to reach the paywall at all. Payment settlement stays with your x402 facilitator.