@xva402/middleware

Risk intelligence middleware for x402 payment servers. Score counterparty risk, detect anomalies, auto-reprice — one line of code.

Install

npm install @xva402/middleware

Quick Start

As Express Middleware (one line)

import express from "express";
import { paymentMiddleware } from "x402-express";
import { xvaMiddleware } from "@xva402/middleware";

const app = express();

// existing x402 payment middleware
app.use(paymentMiddleware({
  "GET /api/data": { price: "$0.01", network: "solana", token: "USDC" },
}));

// add XVA-402 risk layer
app.use(xvaMiddleware({
  apiKey: process.env.XVA_API_KEY,
  thresholdReject: 0.6,
  fallback: "passthrough",
}));

app.get("/api/data", (req, res) => {
  // req.xva contains the risk score
  console.log(req.xva.score);   // 0.12
  console.log(req.xva.action);  // "APPROVE"
  res.json({ data: "your protected resource" });
});

As Standalone Client

import { XvaClient } from "@xva402/middleware";

const client = new XvaClient({
  endpoint: "http://localhost:3402",
  apiKey: "your-api-key",
  detail: true,
});

// Risk score
const risk = await client.score("7xK..mPq", 0.5, "USDC");
console.log(risk.score);    // 0.12
console.log(risk.action);   // "APPROVE"

// Anomaly check
const anomaly = await client.anomaly("3bR..vZn", 60);
console.log(anomaly.flags); // ["VELOCITY_SPIKE"]

// Reprice
const fee = await client.reprice({
  agent_id: "3bR..vZn",
  base_fee_bps: 30,
  amount: "50",
  token: "USDC",
});
console.log(fee.total_fee_bps); // 280

// Registry
const agent = await client.registry("7xK..mPq");
console.log(agent.reputation); // "trusted"

CLI

# Score an agent
npx @xva402/middleware score --agent 7xK..mPq --amount 0.5

# Run integration tests
npx @xva402/middleware test --endpoint http://localhost:3402

# Health check
npx @xva402/middleware health

Middleware Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | http://localhost:3402 | XVA-402 server URL | | apiKey | string | | API key for authentication | | thresholdApprove | number | 0.3 | Below this → approve | | thresholdReject | number | 0.6 | Above this → reject | | maxFeeBps | number | 500 | Max fee adjustment | | fallback | string | "passthrough" | Action when XVA unreachable | | timeout | number | 5000 | Request timeout (ms) | | detail | boolean | false | Include full breakdown | | routes | string[] | | Routes to protect | | exclude | string[] | ["/health", "/metrics"] | Skip these paths |

How It Works

1. Request hits your x402 server
2. xvaMiddleware extracts the payer wallet from X-PAYMENT header
3. Queries XVA-402 engine for risk score
4. Score < 0.3 → APPROVE (next middleware runs)
5. Score 0.3–0.6 → REPRICE (fee adjusted, req.xva has details)
6. Score > 0.6 → REJECT (403 response, handler never runs)
7. XVA unreachable → PASSTHROUGH (fail-safe default)

Requirements

• Node.js 18+
• XVA-402 server running (see Core-project)

License

MIT