x402lint

x402lint

x402エージェント決済プロトコルの適合性リンターです。 アクセスに課金する HTTP エンドポイントを指定すると、返される 402 Payment Required チャレンジが適切な形式かどうかを確認します。これは、 エージェントのランタイムが支払いを行う前に実行するチェックです。

$ x402lint check https://riddlex402.vercel.app/api/riddle
PASS  status: HTTP 402 Payment Required
INFO  format: x402 v2 (payment-required header)
PASS  header-decode: payment-required header is base64 JSON
PASS  x402Version: 2
PASS  error: 'Payment required'
PASS  resource.url: https://riddlex402.vercel.app/api/riddle
PASS  accepts: 1 payment option(s)
PASS  accepts[0].required: all required fields present
PASS  accepts[0].scheme: 'exact'
PASS  accepts[0].network: eip155:8453 (CAIP-2)
PASS  accepts[0].amount: 2000 atomic units
PASS  accepts[0].asset: valid EVM address
PASS  accepts[0].payTo: valid EVM address
PASS  accepts[0].maxTimeoutSeconds: 300
PASS  accepts[0].extra: EIP-712 domain: name='USD Coin' version='2'
INFO  discovery: advertises the 'bazaar' discovery extension

14 pass, 0 warn, 0 fail  (CONFORMANT)

インストール

pip install x402lint

リンター（check / decode / facilitator / survey）は標準ライブラリのみで動作し、 Python 3.12 以降が必要です。pay コマンドには EIP-712 署名機能も必要です。 pip install 'x402lint[pay]' を実行してください。

コマンド

x402lint check <url>

支払いヘッダーなしで <url> にアクセスし、402 が返されることを確認して、 支払いチャレンジを検証します。

• ステータスが正確に 402 であること
• ワイヤ形式 — v2（payment-required base64 ヘッダー。現在一般的な形式） または v1（x402Version: 1 JSON ボディ）。どちらかを報告します。
• チャレンジドキュメントをデコード／解析できること
• x402Version が整数で、error が人間に読める文字列であること
• accepts が空でない配列であり、各エントリーに以下が含まれること：
  • 必須フィールド（scheme、network、金額、asset、payTo、 maxTimeoutSeconds）
  • scheme が既知の値（exact、upto、batch-settlement）であること。不明な値は警告します。
  • network が CAIP-2 形式（v2）または認識可能な名前（v1）であること。不明な値は警告します。
  • 金額が正の整数を表す 10 進文字列（最小単位）であること
  • asset／payTo が EVM ネットワーク上の有効な 0x… アドレスであること
  • exact／EVM エントリーに、EIP-712 ドメイン用の extra.name と extra.version が含まれること
  • v1 エントリーに、絶対 URL の resource が含まれること
• 検出用メタデータ（extensions.bazaar／v1 outputSchema）—報告しますが、必須ではありません。

--json を指定すると、機械可読なレポートを出力します（CI 用）。終了コード：適合 （警告は許容）、失敗がある場合は 1、ツールエラーの場合は 2。

リクエストボディを検証してから 402 を返す POST エンドポイント（多くの LLM ゲートウェイ）の場合は、 --data でボディを指定してください（POST が有効になります。@file または - を指定すると、ファイル／標準入力から読み込みます）。

$ x402lint check https://x402.telnyx.com/v1/chat/completions \
    --data '{"model":"google/gemma-2b-it","messages":[{"role":"user","content":"hi"}]}'

x402lint decode <blob>

base64 形式の x402 ヘッダーブロブ（payment-required、X-PAYMENT、 payment-response）を整形して出力し、ドキュメントの種類を示します。- を指定すると標準入力から読み込みます。

curl -sD - https://weather.payapi.market/current \
  | grep -i ^payment-required: | cut -d' ' -f2 \
  | x402lint decode -

x402lint facilitator [url]

GET <url>/supported を取得し、ファシリテーターが verify／settle できる すべての (x402Version, scheme, network) の組み合わせと、公開されている拡張機能を一覧表示します。 不明なスキームや CAIP-2 形式ではない v2 ネットワークには警告します。url のデフォルトは https://x402.org/facilitator（公開テストネットのファシリテーター）です。--json。

$ x402lint facilitator
  v2  exact              eip155:84532
  v2  upto               eip155:84532 +extra
  v2  batch-settlement   eip155:84532
  ...
11 kind(s): schemes batch-settlement, exact, upto; 9 network(s); versions 1, 2

x402lint survey [catalogue]

検出カタログ（デフォルトでは Coinbase CDP の .../x402/discovery/resources リスト）を取得し、過去 30 日間の呼び出し量が多い順に --limit 件のリソースを選んで、それぞれに check を実行します。これにより、 「x402 適合状況」のスナップショットを手早く作成できます。各リソースで公開されている bazaar の入力方式とクエリパラメーターの例を再現し、実際にペイウォールまでリクエストが到達するようにします （通常の GET を強制するには --no-hints を指定します）。--json。

$ x402lint survey --limit 8
ok   v2  https://x402.twit.sh/tweets/search?from=elonmusk&minLikes=100&words=bitcoin
FAIL v2  https://x402.tavily.com/search
       - accepts[1].amount: 'amount' must be a base-10 string of a positive integer, got '0.016'
...
7/8 endpoints conformant

稼働中の x402 エンドポイントのうち、呼び出し量が多いものをホストごとにまとめた適合性テーブルなど、 定期的な調査結果は SURVEY.md で管理しています。日付入りのスナップショットは data/ にあります。

x402lint pay <url>

エンドポイントの 402 を取得し、最初の exact スキームの accepts[] エントリ（または --accept-index N）を選択して、EIP-3009 TransferWithAuthorization 支払いにオフラインで署名します。トランザクションもガスも不要で、必要なのは EIP-712 署名だけです。クライアントが返送する X-PAYMENT ヘッダー値を出力します。EIP-712 ドメイン（name／version／chainId／verifyingContract）は、ハードコードされた値ではなく、ワイヤー上の情報（accepts[].extra + network + asset）から読み取ります。

秘密鍵は環境変数（デフォルトは X402LINT_PRIVATE_KEY、変更するには --key-env NAME）から取得され、ログに記録されることはありません。pay エクストラが必要です。

pip install 'x402lint[pay]'
export X402LINT_PRIVATE_KEY=0x...
$ x402lint pay https://api.example.com/data
# payer     0x19E7E376E7C213B7E7e7e46cc70A5dD086DAff2A
# asset     0x036CbD53842c5426634e7929541eC2318f3dCF7e  (USDC v2, chain 84532)
# payTo     0x209693Bc6afc0C5328bA36FaF03C514EF312287C
# value     1000 atomic units
# expires   validBefore=1756431600

X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3Qi...

--json を指定すると、支払者、認可タプル、署名、完全な PaymentPayload、ヘッダーが出力されます。

x402lint roundtrip <url>

pay を実行し、続けて X-PAYMENT ヘッダーを付けてリクエストを再送信し、サーバーの応答を報告します。X-PAYMENT-RESPONSE ヘッダー（success、transaction、network）をデコードします。支払いが拒否された場合は、レスポンス本文の error 文字列を代わりに使用します。支払いが決済された場合のみ終了コード 0 を返し、それ以外は 1 を返します。

export X402LINT_PRIVATE_KEY=0x...
$ x402lint roundtrip https://api.example.com/data
# payer     0x19E7E376E7C213B7E7e7e46cc70A5dD086DAff2A
# payTo     0x209693Bc6afc0C5328bA36FaF03C514EF312287C
# value     1000 atomic units  (chain 84532)
# retry     HTTP 200

SETTLED  tx 0xabc123...

実際に決済するには、pay エクストラと、資金が入った鍵が必要です。資金がない場合も一連の処理を最後まで実行し、NOT SETTLED (insufficient_funds) と報告します。

--facilitator <url>

リソースサーバーにリクエストを再送信するのではなく、ファシリテーターの /verify + /settle に対して直接決済します。リソースサーバーが独自の（CAIP-2）paymentRequirements を構築し、そこで v1 のわかりやすい名前しか受け付けないファシリテーターとの照合に失敗する場合に便利です。x402lint はチャレンジを v1 の決済エンベロープ（base-sepolia、maxAmountRequired、x402Version: 1）に変換し、/verify が支払いを拒否した場合は /settle の前に処理を停止します。

$ x402lint roundtrip --facilitator https://x402.org/facilitator https://x402.org/protected
# payer        0xc838ED72fd5905C30801515DdC7B5cc13F36E88D
# payTo        0x209693Bc6afc0C5328bA36FaF03C514EF312287C
# value        10000 atomic units  (base-sepolia)
# facilitator  https://x402.org/facilitator
# verify       HTTP 200  -> valid

SETTLED  tx 0x188066d0...

GitHub Action

CI でリンターを実行すると、402 チャレンジを壊すデプロイでビルドが失敗するようにできます。このリポジトリには、ルートにコンポジットアクションが用意されており、GitHub Marketplace にも掲載されています。

# .github/workflows/x402.yml
name: x402 conformance
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: arden-instance/[email protected]
        with:
          url: https://your-endpoint.example/api
          # url: |               # multiple endpoints, one per line
          #   https://a.example/x
          #   https://b.example/y
          # version: 0.5.2        # pin the linter (default: latest)
          # strict: "true"        # also fail on WARN-level findings

エンドポイントが適合しない 402 を返した場合、このステップはゼロ以外の終了コードを返してジョブを失敗させ、具体的な検出事項を実行結果に注釈として追加します。

実行可能な使用例は、このリポジトリの .github/workflows/x402.yml にあります。週次スケジュールで、このアクションを正常な公開エンドポイントに対して実行します。コピーして、独自の URL に置き換えてください。

MCP サーバー

pip install 'x402lint[mcp]' を実行すると、x402lint mcp サブコマンド（x402lint-mcp としてもインストールされます）が追加されます。これは Model Context Protocol サーバー（stdio トランスポート）で、エージェントや IDE アシスタントがシェルコマンドを介さずに x402 エンドポイントを検査できます。次の 3 つのツールを公開します。

ツール	説明
lint_endpoint	URL に支払いなしでアクセスし、402 を想定して適合性レポートを返す
decode_payment	base64 の X-PAYMENT／accepts BLOB をデコードして分類する
check_facilitator	ファシリテーターが決済可能なスキーム／ネットワークの組み合わせを要約する

// claude_desktop_config.json / any MCP client
{
  "mcpServers": {
    // installed on PATH:
    "x402lint": { "command": "x402lint-mcp" }
    // or zero-install via uv:
    // "x402lint": { "command": "uvx", "args": ["--from", "x402lint[mcp]", "x402lint", "mcp"] }
  }
}

プロトコルに関する注意事項

ワイヤー形式は 2 種類あります。v2（x402Version: 2、Linux Foundation 仕様）は、2026 年時点で実際の利用において主流です。PaymentRequired ドキュメントは base64 エンコードされて payment-required レスポンスヘッダーで送信され、ネットワークは CAIP-2 ID（eip155:8453）、金額フィールドは amount です。v1 はレガシー形式です。ドキュメントは JSON 本文で、ネットワークはわかりやすい名前（base）、金額フィールドは maxAmountRequired です。x402lint は両方に対応しています。

ライセンス

MIT