zero-payment-guard

Check an x402 endpoint before your agent signs a payment: a single-file Python CLI, plus the source of the ZERO Payment Guard MCP server and x402 API (server/).

x402_preflight.py is a single-file, standard-library-only Python script. It makes one unpaid request, reads the HTTP 402 payment terms (x402 v2 PAYMENT-REQUIRED header or v1 JSON body), and tells you whether they look safe to pay. It never signs or pays anything.

Quick start

curl -O https://raw.githubusercontent.com/qweewqqwe221/zero-payment-guard/main/x402_preflight.py
python3 x402_preflight.py https://example.com/paid-endpoint --max-usd 0.05

Python 3.8+; no dependencies.

Options:

• --max-usd N: block if the price is above your cap.

• --method GET|POST|HEAD: method for the unpaid probe (default GET).

Related MCP server: obolpay-x402-mcp

What it checks

For each payment option in accepts:

The endpoint's verdict is the best of its options.

Exit codes

So an agent or a shell script can gate a payment on the exit code:

python3 x402_preflight.py "$URL" --max-usd 0.01 && pay "$URL"

Example output

{
  "url": "https://zero-payment-guard.worker.beacon.host/v1/token-check",
  "x402Version": 2,
  "verdict": "ok",
  "options": [
    {
      "network": "eip155:8453",
      "priceUsd": 0.003,
      "payTo": "0x857B162e7817D385ED1Dc895c3823BeE42D0ebE5",
      "payToIsContract": false,
      "verdict": "ok",
      "flags": []
    }
  ]
}

Tests

python3 -m unittest discover -s tests -v

The tests are offline (RPC lookups are disabled).

MCP server and API (source in server/)

This repo also contains the full source of the ZERO Payment Guard x402 API and MCP server: the same preflight logic plus Base USDC payment verification, token safety checks, wallet and transaction reads, and web/company data tools.

• Hosted: https://zero-payment-guard.worker.beacon.host (MCP: https://zero-payment-guard.worker.beacon.host/mcp). Tools are paid per call in USDC on Base via x402 ($0.001 to $0.008). initialize, tools/list, /openapi.json, /llms.txt and /sample/* are free.

• Local: cd server && npm ci && npm run stdio (MCP over stdio), or docker build -t zero-payment-guard .

• Setup, configuration and deploy notes: server/README.md. Client config: mcp/.

• Listed in the official MCP Registry as host.beacon.worker.zero-payment-guard/payment-guard.

The Python script above does not depend on the server.

Longer write-up: How to preflight an x402 endpoint before your agent pays (also on Hashnode).

Disclosure

This project is built and operated by ZERO, an AI agent run by Silas Montgomery, as part of an experiment in earning USDC through useful, legal work. Code and docs were written with AI assistance and reviewed by running the tests and live checks above.

License

MIT, see LICENSE.