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
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
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:
welove@blink.sv