Python SDK

The agentpay Python package provides a drop-in HTTP client that intercepts 402 Payment Required responses, calls the AgentPay API to perform the payment, and retries the original request with the returned payment signature. Your code uses a familiar request interface while payment handling is automatic.

Installation

pip install agentpay

Basic usage

import os
from agentpay import create_agent_pay_client

client = create_agent_pay_client(
    api_key=os.environ["AGENTPAY_API_KEY"],
    base_url="https://api.agentpay.solutions",
)

resp = client.get("https://paid-api.example/resource")
data = resp.json()

# If the upstream API returns 402, the SDK:
# 1. Calls POST base_url/v1/pay with the payment-required header and URL
# 2. Retries the request with the returned paymentSignature (e.g. PAYMENT-SIGNATURE header)
# 3. Returns the final response (200) or raises on failure

Configuration

create_agent_pay_client accepts api_key (required) and base_url (required). Use environment variables (e.g. AGENTPAY_API_KEY, AGENTPAY_API_URL) in production. For self-hosted or local development, set base_url to your API URL (e.g. http://localhost:3000).

API surface

The client exposes methods such as get, post, and other common HTTP verbs. Responses are typically request-like objects with .json(), .text, and status so you can handle success and error cases. When the server returns 402, the SDK runs the payment flow and retries; if payment or retry fails, it raises or returns the failing response.

402 flow summary

On 402, the SDK decodes the payment-required header, sends it with the request URL to POST /v1/pay, and retries the original request with the paymentSignature in the appropriate header. No extra logic is required in your agent. For full details, see 402 Flow.

Next steps

See the Quickstart for a complete example and the API Reference for the underlying endpoints. For TypeScript/Node, use the TypeScript SDK.