x402-validate

CLI + library + GitHub Action + Chrome Extension to validate x402 HTTP payment protocol endpoints.

Detects x402-enabled endpoints via headers and JSON body, decodes PaymentRequired payloads, validates schema compliance, checks facilitator reachability, generates status badges, and monitors endpoints in watch mode.

Architecture

graph TB
    subgraph "x402-validate Ecosystem"
        CLI["🖥️ CLI<br/>x402-validate &lt;url&gt;"]
        LIB["📦 npm Library<br/>import { checkX402 }"]
        ACTION["⚙️ GitHub Action<br/>CI/CD pipeline"]
        EXT["🔌 Chrome Extension<br/>Browser detection"]
    end

    subgraph "Target"
        SITE["🌐 x402 Site<br/>HTTP 402 + headers"]
        WELL["📋 .well-known/x402.json<br/>Discovery endpoint"]
    end

    subgraph "Integration"
        A2A["🗂️ a2alist.ai<br/>x402 Directory"]
        BADGE["🏷️ Status Badge<br/>SVG via API"]
    end

    CLI -->|probe| SITE
    LIB -->|probe| SITE
    ACTION -->|probe| SITE
    EXT -->|probe| SITE
    EXT -->|discover| WELL
    EXT -->|submit listing| A2A

How x402 Works

sequenceDiagram
    participant C as Client
    participant S as x402 Server
    participant F as Facilitator
    participant B as Blockchain

    C->>S: GET /api/resource
    S-->>C: 402 Payment Required<br/>x-payment-required: {accepts, facilitatorUrl}
    
    Note over C: x402-validate detects this! ✅
    
    C->>F: POST /verify<br/>{payment proof}
    F->>B: Verify on-chain
    B-->>F: Confirmed ✅
    F-->>C: Payment receipt
    C->>S: GET /api/resource<br/>X-Payment: {receipt}
    S-->>C: 200 OK + content

Detection Flow

flowchart LR
    A[Visit URL] --> B{GET returns 402?}
    B -->|Yes| C{x-payment-required header?}
    C -->|Yes| C2[Decode header]
    C -->|No| C3{JSON body has x402Version/accepts?}
    C3 -->|Yes| C4[Parse body payload]
    C3 -->|No| F[🔴 No x402]
    B -->|No| D{/.well-known/x402.json exists?}
    D -->|Yes| E[Parse discovery document]
    D -->|No| F
    C2 --> G[Validate schema]
    C4 --> G
    E --> G
    G --> H{Valid?}
    H -->|Yes| I[Check facilitator reachability]
    H -->|No| J[⚠️ Invalid schema]
    I --> K[🟢 x402 Detected]

Components

Component	Description	Location
CLI	Command-line checker with colored output	`src/cli.ts`
Library	Importable npm package	`src/index.ts`
GitHub Action	CI/CD integration, zero deps	`action/`
Chrome Extension	Browser-native x402 detection	`extension/`

Quick Start

# Install globally
npm install -g x402-validate

# Check a URL
x402-validate https://pay.skillpacks.dev/api/skills/security-suite

# Verbose: schema validation + facilitator check
x402-validate --verbose https://pay.skillpacks.dev/api/skills/security-suite

# JSON output for CI
x402-validate --json https://api.example.com/resource | jq .

Output

✅ x402 DETECTED  https://pay.skillpacks.dev/api/skills/security-suite
  Status:      402
  Network:     eip155:8453
  Scheme:      exact
  Amount:      990000
  Resource:    https://pay.skillpacks.dev/api/skills/security-suite
  Pay to:      0xb92aab592c...
  Schema:      ✅ Valid
  Facilitator: ✅ Reachable (HTTP 200)

CLI Reference

x402-validate [options] <url> [url...]

Flag	Description
`--json`	Machine-readable JSON output
`--verbose`	Schema validation + facilitator check
`--timeout <ms>`	Request timeout (default: `10000`)
`--file <path>`	Read URLs from file (one per line, `#` comments)
`--badge <path>`	Generate SVG status badge
`--watch <secs>`	Re-check every N seconds
`--help`	Show help
`--version`	Show version

Exit Codes

Code	Meaning
`0`	x402 detected on at least one URL
`1`	No x402 detected
`2`	Error (network, timeout, invalid args)

Examples

# Check multiple URLs
x402-validate https://api.a.com/paid https://api.b.com/endpoint

# Read URLs from file
echo "https://pay.skillpacks.dev/api/skills/security-suite" > urls.txt
x402-validate --file urls.txt

# Generate a badge
x402-validate --badge badge.svg https://api.example.com/resource

# Watch mode — re-check every 60 seconds
x402-validate --watch 60 https://api.example.com/resource

# CI — exits 0 if x402 found
x402-validate https://api.example.com/resource && echo "x402 active!"

Library API

import {
  checkX402,
  validateSchema,
  checkFacilitator,
  decodePaymentRequired,
} from 'x402-validate';

`checkX402(url, options?)`

const result = await checkX402('https://api.example.com/resource', {
  timeout: 10000,
  verbose: true,
  checkFacilitator: true,
});

if (result.supported) {
  console.log('x402 detected!', result.paymentDetails);
  console.log('Schema valid?', result.schemaValidation?.valid);
  console.log('Facilitator up?', result.facilitatorCheck?.reachable);
}

`validateSchema(payload)`

const validation = validateSchema({
  x402Version: 1,
  accepts: [{
    scheme: 'exact',
    network: 'base-mainnet',
    maxAmountRequired: '1000000',
    resource: 'https://example.com/api',
    description: 'Access to AI API',
    mimeType: 'application/json',
    payTo: '0xDeadBeef',
    maxTimeoutSeconds: 300,
  }],
  facilitatorUrl: 'https://facilitator.example.com',
});

console.log(validation.valid);    // true
console.log(validation.errors);   // []

`checkFacilitator(url, timeout?)`

const fc = await checkFacilitator('https://facilitator.example.com', 5000);
// fc.reachable: true if 2xx/3xx

GitHub Action

Zero-dependency composite action for CI/CD pipelines.

- name: Verify x402 endpoint
  uses: suryast/x402-validate@master
  with:
    urls: |
      https://pay.skillpacks.dev/api/skills/security-suite
      https://a2alist.ai/api/submit
    fail-on-missing: 'true'
    timeout: '15000'

Inputs

Input	Required	Default	Description
`urls`	✅	—	Newline-separated URLs to check
`fail-on-missing`	❌	`false`	Fail the step if any URL lacks x402
`timeout`	❌	`10000`	Request timeout in ms

Outputs

Output	Description
`results`	JSON array of check results
`found-count`	Number of URLs with x402
`total-count`	Total URLs checked

Workflow Examples

# Scheduled monitoring
name: x402 Monitor
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: suryast/x402-validate@master
        with:
          urls: https://pay.skillpacks.dev/api/skills/security-suite
          fail-on-missing: 'true'

# PR gate — ensure x402 stays active
name: x402 Gate
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: suryast/x402-validate@master
        id: x402
        with:
          urls: https://your-api.com/paid-endpoint
          fail-on-missing: 'true'
      - run: echo "Found ${{ steps.x402.outputs.found-count }} x402 endpoints"

Chrome Extension

MV3 Chrome extension that passively detects x402 endpoints while you browse.

Features

🟢 Green x402 badge when x402 detected on current site
🔴 Red OFF badge when no x402 found
Auto-discovers via /.well-known/x402.json
Stores discovered x402 sites locally
One-click submit to a2alist.ai directory
Export discovered sites as JSON
Built-in directory browser (powered by a2alist.ai)

Screenshots

x402 Detected	Not Found

Install

From Chrome Web Store (recommended):

Manual (developer mode):

Download or clone extension/ directory
Open chrome://extensions
Enable Developer mode
Click Load unpacked → select extension/

How It Works

flowchart TD
    A[Page loads] --> B[Service worker triggers]
    B --> C{Direct probe<br/>GET returns 402?}
    C -->|Yes| D[Parse x-payment-required]
    C -->|No| E{Probe /.well-known/x402.json}
    E -->|Found| F[Parse discovery doc]
    E -->|Not found| G["🔴 Badge: OFF"]
    D --> H["🟢 Badge: x402"]
    F --> H
    H --> I[Store in chrome.storage]
    I --> J[Show notification]
    
    K[User clicks popup] --> L{x402 detected?}
    L -->|Yes| M[Show payment details<br/>+ Submit to a2alist.ai]
    L -->|No| N[Show empty state<br/>+ Browse directory]

Privacy

No data sent automatically — submission is user-initiated only
Discovered sites stored locally in chrome.storage.local
Extension only makes HEAD/GET probes to detect x402 headers

x402 Discovery Standard

This project introduces /.well-known/x402.json as a discovery mechanism for x402-enabled sites. Sites that use x402 on specific endpoints (not the homepage) can advertise their x402 support:

{
  "x402Version": 1,
  "endpoints": [
    {
      "path": "/api/submit",
      "method": "POST",
      "description": "Paid API endpoint",
      "price": "$0.99 USDC",
      "network": "eip155:8453"
    }
  ]
}

This enables passive detection by browser extensions and crawlers without probing every route.

Types

TypeScript interfaces

`X402Result`

interface X402Result {
  url: string;
  supported: boolean;
  status: number;
  paymentDetails?: PaymentRequired;
  rawHeader?: string;
  headers?: Record<string, string>;
  error?: string;
  schemaValidation?: ValidationResult;
  facilitatorCheck?: FacilitatorResult;
}

`ValidationResult`

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

`FacilitatorResult`

interface FacilitatorResult {
  url: string;
  reachable: boolean;
  status?: number;
  error?: string;
}

`PaymentRequired`

interface PaymentRequired {
  x402Version?: number;
  accepts?: AcceptsEntry[];
  facilitatorUrl?: string;
  scheme?: string;
  network?: string;
  maxAmountRequired?: string;
}

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.github		.github
action		action
docs/images		docs/images
extension		extension
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SECURITY-REVIEW.md		SECURITY-REVIEW.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

x402-validate

Architecture

How x402 Works

Detection Flow

Components

Quick Start

Output

CLI Reference

Exit Codes

Examples

Library API

checkX402(url, options?)

validateSchema(payload)

checkFacilitator(url, timeout?)

GitHub Action

Inputs

Outputs

Workflow Examples

Chrome Extension

Features

Screenshots

Install

How It Works

Privacy

x402 Discovery Standard

Types

X402Result

ValidationResult

FacilitatorResult

PaymentRequired

Related

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Uh oh!

Contributors

Uh oh!

Languages

`checkX402(url, options?)`

`validateSchema(payload)`

`checkFacilitator(url, timeout?)`

`X402Result`

`ValidationResult`

`FacilitatorResult`

`PaymentRequired`