x402 Payment Protocol SDK

2.9.0 verified Fri May 01 auth: no python

The x402 Python SDK implements the x402 Payment Protocol, enabling micropayments for HTTP resources. Version 2.9.0 supports Python 3.10+ and provides client and server utilities. Active development under the x402-foundation.

pip install x402

Common errors

error ModuleNotFoundError: No module named 'x402' ↓

cause The library is not installed or is installed in a different environment.

fix

Run pip install x402 to install the package.

error AttributeError: module 'x402' has no attribute 'client' ↓

cause Importing incorrectly. `x402.client` is a submodule, not an attribute of the top-level package.

fix

Use from x402.client import Client instead of import x402; x402.client.Client.

error ValueError: Private key must be in PEM format ↓

cause The private key provided is not in valid PEM format.

fix

Provide a PEM-formatted private key string (begins with '-----BEGIN PRIVATE KEY-----').

Warnings

breaking In version 2.x, the `private_key` parameter is required for Client instantiation. In version 1.x it was optional and a default test key was used. Code without explicit key will break. ↓

fix Always pass `private_key` to `Client()` or set `X402_PRIVATE_KEY` environment variable.

breaking The `PaymentRequest` class was removed in version 2.0. Use `x402.client.prepare_payment()` instead. ↓

fix Replace `from x402.payment import PaymentRequest` with `from x402.client import prepare_payment`.

gotcha The SDK expects the private key in PEM format. Plain hex or raw bytes will raise a `cryptography` error. ↓

fix Ensure the private key is in PEM format, e.g., read from file like `open('key.pem').read()`.

deprecated Method `Client.make_payment()` is deprecated since 2.8.0 and will be removed in 3.0. Use `Client.get()` or `Client.post()` directly. ↓

fix Call `client.get(url)` instead of `client.make_payment('GET', url)`.

Imports

Client
```
from x402.client import Client
```
Client is a class for making paywalled requests.
Server
```
from x402.server import Server
```
Server is a class for handling payment verification.
PaymentError
```
from x402.exceptions import PaymentError
```
PaymentError is the base exception for payment failures.

Quickstart

Initialize the x402 client and make a paywalled GET request. The private key is read from environment variable; leave empty for demo.

import os
from x402.client import Client

url = "https://api.example.com/protected"
# In production, set X402_PRIVATE_KEY environment variable
private_key = os.environ.get('X402_PRIVATE_KEY', '')
client = Client(private_key=private_key)
try:
    response = client.get(url)
    print(response.status_code)
    print(response.text)
except Exception as e:
    print(f"Error: {e}")