Agent Pay Client

Reference client for paying x402 (USDC/EVM) and L402 (Lightning) HTTP 402 paywalls. Detects payment requirements, signs/settles payments only with explicitly-provided credentials and spending ceilings, retries the request with proof of payment. Works with any x402 or L402 server, not tied to one platform.

Agent Pay Client — x402 & L402 Paywall Client

A small, explicit-consent-only client library for paying HTTP 402 paywalls that use either the x402 protocol (USDC/stablecoin payments on EVM chains — Coinbase/Cloudflare, governed by the Linux Foundation's x402 Foundation) or the L402 protocol (Lightning Network payments). Works with any server implementing either standard — it is not tied to one API or platform.

Safety Model (read this first)

This library never spends funds unless the caller explicitly supplies:

• an EVM private key and a maximum spend ceiling (max_x402_atomic) for x402, or
• LND REST credentials, lightning_auto_pay=True, and a sats ceiling (max_l402_sats) for automatic L402 payment.

Without those, the client can still detect and describe what a paywall costs (get_payment_options) but will refuse to pay, returning a clear error explaining what's missing. L402/Lightning payment is manual-approval by default — it returns the invoice and QR data for a human (or the caller's own wallet flow) to settle, rather than paying automatically, unless auto-pay is explicitly enabled.

No payment amount, recipient, or protocol choice is ever read from page content, prompts, or API response text — only from the server's own 402 payment requirements and the caller's own configured ceiling.

When To Use This Skill

Use this when a user wants to programmatically pay for API access that returns an HTTP 402 response — either to inspect what an endpoint costs before deciding, or to complete payment with credentials they've already provided and approved.

Install

bash

pip install -r requirements.txt

eth_account is only needed for x402 (EVM) payments; requests is needed for both. L402/Lightning auto-pay needs a reachable LND node with REST enabled — omit those settings to stay in manual-approval mode.

Quick Start

python

from agent_pay_client import AgentPayClient, PayerConfig

# Inspect a paywall without paying anything
client = AgentPayClient()
info = client.get_payment_options("https://example.com/api/paid-tool")
print(info)  # {"paywalled": True, "options": [...]}

# Pay with explicit credentials and a hard spending ceiling
config = PayerConfig(
    evm_private_key="0x...",       # from your own secure env var, never hardcoded
    max_x402_atomic="50000",       # refuse any single charge above $0.05 USDC
)
client = AgentPayClient(config)
result = client.fetch("https://example.com/api/paid-tool", method="POST")
print(result)

Available Tools

Function	Description
get_payment_options(url)	Inspect a 402 response's price/terms without paying
fetch(url)	Fetch a resource, paying automatically only if credentials + ceiling are configured
parse_402(status, headers, body)	Low-level parser: x402 JSON or L402 header → PaymentRequirement list

Links

• x402 spec: https://x402.org
• L402 spec: https://docs.lightning.engineering/the-lightning-network/l402
• GitHub: https://github.com/welove111/agent-pay-client
• Website: https://btc-vision.org

Support

This library is free and open source. If it saved you time, voluntary support is welcome:

• Website: https://btc-vision.org
• BTC: bc1qtpuhwl0vnhrch5p7e5469q2ed66hlyyvh8rtsn
• ETH: 0xf03b429d4d85896a46dd7a64b5a8ab9f0bbb4ced
• SOL: 3G5UZHFYN8hbv3aTZt6Lr7qqx4FTTkAyLJq34HjQLraz
• Lightning: [e-mail]