httpayer 0.1.2

Python SDK for HttPayer

HTTPayer – Python SDK

HTTPayer is a Python SDK and decorator toolkit for accessing 402 Payment Required resources using the x402 protocol. It integrates with the HTTPayer router to enable seamless off-chain stablecoin payments using EIP-3009 and tokenized authorization headers.

This package provides:

• HttPayerClient: a programmatic client for automatically paying 402 responses using a hosted HTTPayer server
• X402Gate: a decorator for protecting Web2 API endpoints using 402-compliant authorization and on-chain token metadata
• Environment-variable support for network/facilitator configuration

---

Features

• Unified HTTPayer router integration
• Automatic retry on 402 with X-PAYMENT headers
• Flask endpoint protection with X402Gate
• EVM token metadata verification (name/version via web3)
• Compatible with Base Sepolia, Avalanche Fuji, and other testnets

---

Installation

Install from source or using pip:

pip install httpayer

Install with demo dependencies (for Flask/CCIP demos):

pip install httpayer[demo]

---

Environment Setup

Create a .env file or set environment variables directly:

NETWORK_TYPE=testnet
NETWORK=base
FACILITATOR_URL=https://x402.org
HTTPAYER_API_KEY=your-api-key
RPC_GATEWAY=https://your-gateway.example
PAY_TO_ADDRESS=0xYourReceivingAddress

---

Usage

HttPayerClient

A client for paying 402-gated endpoints using a hosted HTTPayer router.

from httpayer import HttPayerClient

client = HttPayerClient()

response = client.request("GET", "http://provider.akash-palmito.org:30862/base-weather")

print(response.status_code)      # 200
print(response.headers)          # Includes X-PAYMENT-RESPONSE
print(response.json())           # Actual resource data

You can also manually call pay_invoice(...) if you already received a 402 response.

---

X402Gate Decorator

A gate/decorator for protecting Flask API routes using x402 payment authorization headers.

from httpayer import X402Gate
from web3 import Web3
from flask import Flask, request, jsonify, make_response

gate = X402Gate(
    pay_to="0xYourReceivingAddress",
    network="base-sepolia",
    asset_address="0xTokenAddress",
    max_amount=1000,  # atomic units (e.g. 0.001 USDC = 1000)
    asset_name="USD Coin",
    asset_version="2",
    facilitator_url="https://x402.org"
)

def create_app():
    app = Flask(__name__)

    @app.route('/')
    def index():
        return "<h1>Weather Server</h1><p>Welcome to the Weather Server!</p>"

    @app.route("/weather")
    @gate.gate
    def weather():
        response = make_response(jsonify({"weather": "sunny", "temp": 75}))
        return response

    return app

We can dynamically generate the payment requirements in our Flask app and add it to specific endpoints in our app. Each endpoint can have its own specialized payment instructions.

gate_usdc = X402Gate(
    pay_to=...,
    network="base",
    asset_address=USDC_ADDRESS,
    max_amount=1000000,
    ...
)

gate_dai = X402Gate(
    pay_to=...,
    network="avalanche",
    asset_address=DAI_ADDRESS,
    max_amount=2000000,
    ...
)

@app.route("/api/usdc-data")
@gate_usdc.gate
def usdc_endpoint():
    ...

@app.route("/api/dai-data")
@gate_dai.gate
def dai_endpoint():
    ...

---

Examples

test1.py – Programmatic Client Example

Runs multiple GET requests to x402-protected endpoints and prints response metadata.

python tests/test1.py

test2.py – Flask Weather Server Demo

Starts a local API server (/weather) that requires a valid X-PAYMENT header:

python tests/test2.py

Send payment using HTTPayer:

http POST http://localhost:31157/httpayer \
  api_url=http://localhost:50358/weather \
  method=GET \
  x-api-key:your-api-key

---

Project Structure

httpayer/                 # Main package
├── __init__.py
├── client.py            # HttPayerClient class
├── gate.py              # X402Gate and helpers
tests/
├── test1.py             # Client-based demo
├── test2.py             # Flask server demo
.env.sample              # Environment config template
pyproject.toml
README.md

---

License

MIT License. See LICENSE for full details.

---

Author

Created by Brandyn Hamilton