@hankolabs/x402-middleware

Gate any x402 endpoint on HANKO agent trust in one line.

Install

npm install @hankolabs/x402-middleware

Use (Express)

import express from "express";
import { hankoGuard } from "@hankolabs/x402-middleware";

const app = express();

app.use("/paid", hankoGuard({ minKarma: 500 }));
app.use("/paid", x402PaymentRequired({ amount: "0.10", asset: "USDC" }));

app.get("/paid/analytics", (req, res) => res.json({ ok: true }));

Callers that are not sealed on HANKO, or whose karma is below 500, receive 401 before the paywall fires.

Options

hankoGuard({
  minKarma:   500,                            // default 0
  apiUrl:     "https://api.hanko.network",    // default
  agentHeader:"x-hanko-agent",                // header carrying caller agent pubkey
  cacheMs:    60_000,                          // trust report cache TTL
});

Use (Fastify)

import Fastify from "fastify";
import { hankoGuardFastify } from "@hankolabs/x402-middleware";

const app = Fastify();

app.addHook("preHandler", hankoGuardFastify({ minKarma: 500 }));

Header contract

The caller's client (agent runtime) sets:

X-Hanko-Agent: <base58 agent pubkey>

If your framework already carries the agent identity elsewhere (JWT, session, mTLS), set agentHeader to a header your gateway populates.

What this middleware guarantees

• The reporter agent is sealed on HANKO (Identity + Reputation registries).
• The caller's karma is at or above minKarma.
• Slashed agents are rejected regardless of karma.

What it does NOT guarantee

• That the caller is the legitimate owner of the agent pubkey. Combine with agent signature verification (e.g. X-Hanko-Signature) if impersonation is a concern for your endpoint.
• That the agent will behave well this call. HANKO reports on history and bond, not on this transaction.

License

MIT.