x402-guard

v5 note: x402-guard is an ExecutionRail adapter inside Railguard v5 — not a standalone product identity. Primary integration: coinbase/vendor/x402-guard + @railguard/kernel Authority Engine. See v5execution.md.

Fail-closed policy, replay protection, and audit receipts for x402 agent payments.

Start here: Railguard PORTFOLIO · WORKSPACE

x402 lets agents pay for HTTP resources instantly. It does not stop a compromised agent from draining a wallet. x402-guard sits between agent intent and signature — durable multi-agent budget state, atomic reservations, crash recovery, and settlement reconciliation around x402 protocol hooks and payment identifiers.

x402 provides protocol hooks and payment identifiers. This project provides durable multi-agent budget state, atomic reservations, crash recovery and settlement reconciliation around those primitives.

Addresses open ecosystem gaps:

• mark3labs/x402-go#26 — spending policy middleware
• google-agentic-commerce/a2a-x402#60 — per-agent limits and provenance
• x402-foundation/x402#2294 — settlement recovery (roadmap)

Problem

Concern	x402 core	x402-guard
Per-call spending caps	Implementer responsibility	Yes
Rolling budgets	Implementer responsibility	Yes
Domain / payee allowlists	Implementer responsibility	Yes
Replay / idempotency hooks	Protocol identifiers	Durable multi-agent state + atomic claims
Audit receipts	Implementer responsibility	JSONL hash chain
AP2 mandate gate	Implementer responsibility	Escalate path
On-chain hard ceiling	Implementer responsibility	railguard-new hook (optional)

Install

Published packages (npm scope @railguard — not third-party @x402-guard/*):

Package	Role
@kuna5678/x402	Fail-closed middleware
@kuna5678/x402-core	Types / utilities
@kuna5678/x402-policy	Policy + durable store helpers
@kuna5678/x402-receipts	Audit receipts

npm i @kuna5678/x402

From source:

git clone https://github.com/prasanthkuna/x402-guard.git
cd x402-guard && npm install && npm run build

Quick start

import { parseResourceUrl } from "@kuna5678/x402-core";
import {
  X402Guard,
  defaultDevPolicy,
  withSpendingPolicy,
} from "@kuna5678/x402";

const guard = new X402Guard({ policy: defaultDevPolicy("agent_demo") });

const pay = withSpendingPolicy(yourX402SignCallback, guard, (amount, url) => ({
  agentId: "agent_demo",
  payer: "0xYourAgentWallet",
  payTo: "0xMerchant",
  amountAtomic: amount,
  asset: "USDC",
  network: "eip155:84532",
  resource: parseResourceUrl(url),
}));

await pay(50_000n, "https://api.example.com/v1/data");
console.log(guard.lastReceipt);
guard.recordSettlement(guard.lastReceipt!.receiptId, "0xabc...");

Monorepo packages

Package	Description
@kuna5678/x402-core	Shared types, URL parsing, canonical JSON
@kuna5678/x402-policy	Spend tracker, replay guard, policy engine
@kuna5678/x402-receipts	Tamper-evident audit ledger
@kuna5678/x402	X402Guard, withSpendingPolicy()
middleware-go	Go wrapper — upstream PR target for x402-go

Related projects

Repo	Role
railguard-new	Optional Authority Engine + ERC-7579 hook
Railguard / coinbase	Hosted control plane + CDP reconciliation

Development

cd x402-guard
npm install
npm run build
npm run test
cd packages\middleware-go
go test ./...
cd ..\..\examples\guarded-payment
npm run start

Roadmap

• x402-fetch / CDP AgentKit client integration
• AP2 mandate verifier module
• Settlement recovery adapter (#2294)
• Upstream PR to mark3labs/x402-go
• Railguard hook integration demo on Base Sepolia

License

Apache-2.0