x402GuardBETA
x402Guard/Documentation

Documentation

API reference, integration guides, and configuration docs for x402Guard.

Quick Start

Install the SDK

The fastest way to get started. Install the core SDK and connect to the proxy in under a minute.

npm install @x402guard/core

Complete working example:

import { X402GuardClient } from "@x402guard/core";

const client = new X402GuardClient({
  proxyUrl: "https://x402guard-production.up.railway.app",
  agentId: "your-agent-uuid",
  apiKey: "your-api-key",
});

// Check proxy health
const alive = await client.healthCheck();

// Add guardrail: max $10 USDC per transaction
await client.createRule(agentId, {
  rule_type: { type: "MaxSpendPerTx", params: { limit: 10_000_000 } },
});

// Route payment through the proxy
const result = await client.proxyPayment({
  targetUrl: "https://api.example.com/paid-endpoint",
  x402Payment: "<signed-x402-payment>",
  x402Requirements: "<requirements-header>",
  agentId: "your-agent-uuid",
});
npm packageSource on GitHub

Option A: Docker Compose

git clone https://github.com/DzikPasnik/x402Guard.git
cd x402Guard
docker compose up

# Verify
curl http://localhost:3402/api/v1/health

Option B: TypeScript SDK

import { X402GuardClient } from "@x402guard/core";

const client = new X402GuardClient({
  proxyUrl: "http://localhost:3402",
  apiKey: "dev-api-key-change-me",
});

// Register agent
const agent = await client.registerAgent("my-bot", "0xOwnerAddress");

// Add guardrail: max $10 per transaction
await client.addRule(agent.id, {
  MaxSpendPerTx: { max_amount: 10_000_000 }, // 10 USDC (6 decimals)
});
Note: Management API endpoints require an X-Api-Key header. Set MANAGEMENT_API_KEY in your environment. If not set, the proxy denies all management requests (fail-closed).

API Reference

All endpoints are under /api/v1. Base URL for production: https://x402guard-production.up.railway.app

MethodPath
GET/api/v1/health
POST/api/v1/proxy
POST/api/v1/proxy/solana
POST/api/v1/agents
GET/api/v1/agents/{id}
POST/api/v1/agents/{id}/rules
GET/api/v1/agents/{id}/rules
PUT/api/v1/agents/{id}/rules/{rule_id}
DELETE/api/v1/agents/{id}/rules/{rule_id}
POST/api/v1/agents/{id}/session-keys
GET/api/v1/agents/{id}/session-keys
DELETE/api/v1/agents/{id}/session-keys/{key_id}
POST/api/v1/agents/{id}/revoke-all
GET/api/v1/solana/vault/{owner}

Guardrail Rules

Create guardrail rules via POST /api/v1/agents/{id}/rules. Each rule is evaluated on every payment request. If any rule is violated, the payment is rejected.

MaxSpendPerTx

10 USDC (6 decimals)

Maximum USDC an agent can spend in a single x402 payment.

{ "ruleType": { "MaxSpendPerTx": { "max_amount": 10000000 } } }

MaxSpendPerDay

100 USDC/day

Maximum total USDC across all transactions in a 24-hour window.

{ "ruleType": { "MaxSpendPerDay": { "max_amount": 100000000 } } }

AllowedContracts

Base USDC contract

Whitelist of contract addresses the agent is allowed to pay.

{ "ruleType": { "AllowedContracts": { "addresses": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"] } } }

MaxLeverage

Max 3x leverage

Limits DeFi leverage exposure for the agent.

{ "ruleType": { "MaxLeverage": { "max_leverage": 3 } } }

MaxSlippage

1% (100 basis points)

Maximum acceptable slippage tolerance for trades.

{ "ruleType": { "MaxSlippage": { "max_slippage_bps": 100 } } }

Session Keys (EIP-7702)

Session keys give your agent limited signing authority that auto-expires. Create them via the dashboard or API.

Create a session key

curl -X POST -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  http://localhost:3402/api/v1/agents/AGENT_ID/session-keys \
  -d '{
    "ownerAddress": "0xYourWallet",
    "chainId": 84532,
    "expiresAt": "2026-04-01T00:00:00Z",
    "maxSpend": 50000000
  }'

Emergency revocation

# Revoke ALL session keys and deactivate agent immediately
curl -X POST -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
  http://localhost:3402/api/v1/agents/AGENT_ID/revoke-all \
  -d '{ "ownerAddress": "0xYourWallet", "chainId": 84532 }'
Security: Revoke-all is an emergency operation. It immediately invalidates all active session keys and marks the agent as inactive. Re-activate via the dashboard.

Integrations

ElizaOS

TypeScript
npm install @x402guard/elizaos-plugin
Guide →Source

Virtuals Protocol

Python
pip install x402guard-game-plugin
Source

Cod3x

TypeScript
npm install @x402guard/cod3x-adapter
Source

OpenClaw

TypeScript
openclaw plugins install @x402guard/openclaw-plugin
Source

@x402guard/core

TypeScript
npm install @x402guard/core
Source

Solana Vault

The Solana guard is an Anchor program that creates a PDA vault with on-chain guardrails: per-transaction limits, daily caps, and a program whitelist.

PDA vault

Per-owner vault with configurable limits and whitelisted programs

Reserve-then-forward

spent_today updated atomically before CPI transfer

Program whitelist

Only approved programs can receive funds from the vault

Checked arithmetic

checked_add/checked_sub everywhere, zero `as` casts

# Build the Solana program
cd solana && anchor build

# Run integration tests
anchor test

Self-Hosting

x402Guard is fully self-hostable. You need PostgreSQL, Redis, and the Rust proxy binary.

Environment variables

VariableRequired
DATABASE_URLYes
UPSTASH_REDIS_URLYes
MANAGEMENT_API_KEYProd
PROXY_PORTNo
BASE_SEPOLIA_RPC_URLNo
BASE_MAINNET_RPC_URLNo
RUST_LOGNo

Docker production build

docker build -t x402guard-proxy -f proxy/Dockerfile .
docker run -p 3402:3402 \
  -e DATABASE_URL="postgresql://..." \
  -e UPSTASH_REDIS_URL="redis://..." \
  -e MANAGEMENT_API_KEY="your-secure-key" \
  x402guard-proxy

Ready to secure your AI agent?

Set up guardrail rules in minutes. Free and open-source.

Launch Dashboard
View on GitHub

© 2026 x402Guard. Open source under MIT License.