open-agentpay 0.1.0__tar.gz

open_agentpay-0.1.0/.gitignore

@@ -0,0 +1,116 @@
+# Operating System Files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Environment & Secrets
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+*.p12
+*.keystore
+
+# Node.js & pnpm
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+.pnpm-store/
+.pnpm-debug.log*
+
+# Build outputs (TypeScript / JavaScript)
+dist/
+build/
+out/
+.turbo/
+*.tsbuildinfo
+.eslintcache
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+ENV/
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Java & Gradle
+.gradle/
+build/
+!src/**/build/
+bin/
+*.class
+*.jar
+*.war
+*.ear
+*.nar
+.gradletasknamecache
+
+# Maven
+target/
+pom.xml.tag
+pom.xml.releaseBackup
+pom.xml.versionsBackup
+pom.xml.next
+release.properties
+
+# IDE & Editors
+# IntelliJ IDEA
+.idea/
+*.iml
+*.ipr
+*.iws
+out/
+
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Eclipse
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings/
+.springBeans
+
+# Testing & Coverage
+coverage/
+.nyc_output/
+*.lcov
+test-results/
+reports/
+
+# Database & Local Infrastructure
+postgres-data/
+*.db
+*.sqlite
+*.sqlite3
+
+# Logs
+logs/
+*.log
+
+# Internal docs, design, and roadmap (local only)
+docs/

open_agentpay-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: open-agentpay
+Version: 0.1.0
+Summary: The Open-Source Payment Infrastructure & Financial Firewall for Autonomous AI Agents
+Project-URL: Homepage, https://github.com/july-whj/AgentPay
+Project-URL: Documentation, https://github.com/july-whj/AgentPay#readme
+Project-URL: Repository, https://github.com/july-whj/AgentPay
+Author: AgentPay Contributors
+License-Expression: Apache-2.0
+Keywords: agent,ai,arbitrum,eip-712,financial-firewall,langchain,llm,usdc,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.11.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: web3>=6.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# Open AgentPay (`open-agentpay`)
+
+[![PyPI Version](https://img.shields.io/pypi/v/open-agentpay.svg)](https://pypi.org/project/open-agentpay/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**The Open-Source Payment Infrastructure & Financial Firewall for Autonomous AI Agents.**
+
+AgentPay equips autonomous AI agents with gasless micro-payments (Circle USDC on Arbitrum Sepolia & Base) governed by an in-process, non-custodial **Financial Firewall**.
+
+---
+
+## ⚡ Quickstart
+
+### Installation
+```bash
+pip install open-agentpay
+```
+
+### Basic Usage: Transparent 402 Negotiation & Policy Guard
+```python
+from agentpay.client import AgentPayClient, LocalSigner
+from agentpay.policy import SQLitePolicyEngine, PolicyConfig
+
+# 1. Initialize local signer (non-custodial private key)
+signer = LocalSigner("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80")
+
+# 2. Configure local financial firewall
+policy = SQLitePolicyEngine.create_in_memory(
+    PolicyConfig(
+        id="agent_firewall",
+        wallet_address=signer.address,
+        max_per_tx_base_units=100_000,          # Max $0.10 per call
+        rolling_budget_24h_base_units=1_000_000, # Daily limit $1.00
+        circuit_max_rpm=5,                      # Tripped if > 5 requests/min
+    )
+)
+
+# 3. Create client with automatic x402 challenge negotiation
+client = AgentPayClient(signer=signer, policy=policy)
+
+# 4. Transparent call (auto-pays 402 challenge via EIP-712 off-chain signature)
+response = client.get("https://api.seller.com/v1/market-data?ticker=NVDA")
+print(response.json())
+```
+
+### LangChain Paid Tool Integration
+```python
+from agentpay.integrations.langchain import PaidTool
+
+market_tool = PaidTool(
+    name="get_stock_quote",
+    description="Fetch real-time stock price (costs $0.05 USDC per query)",
+    endpoint="https://api.seller.com/v1/market-data",
+    method="GET",
+    client=client,
+)
+```
+
+---
+
+## 🔒 Security Guarantees
+- **Non-Custodial**: Private keys never leave the agent's local trust domain.
+- **Fail-Closed**: Any policy violation, budget exhaustion, or circuit trip aborts immediately with zero funds spent.
+- **Gasless for Agents**: AI Agents hold only USDC; execution gas is sponsored via EIP-3009 by the seller or facilitator.
+
+For complete documentation, visit [AgentPay GitHub](https://github.com/july-whj/AgentPay).

open_agentpay-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Open AgentPay (`open-agentpay`)
+
+[![PyPI Version](https://img.shields.io/pypi/v/open-agentpay.svg)](https://pypi.org/project/open-agentpay/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**The Open-Source Payment Infrastructure & Financial Firewall for Autonomous AI Agents.**
+
+AgentPay equips autonomous AI agents with gasless micro-payments (Circle USDC on Arbitrum Sepolia & Base) governed by an in-process, non-custodial **Financial Firewall**.
+
+---
+
+## ⚡ Quickstart
+
+### Installation
+```bash
+pip install open-agentpay
+```
+
+### Basic Usage: Transparent 402 Negotiation & Policy Guard
+```python
+from agentpay.client import AgentPayClient, LocalSigner
+from agentpay.policy import SQLitePolicyEngine, PolicyConfig
+
+# 1. Initialize local signer (non-custodial private key)
+signer = LocalSigner("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80")
+
+# 2. Configure local financial firewall
+policy = SQLitePolicyEngine.create_in_memory(
+    PolicyConfig(
+        id="agent_firewall",
+        wallet_address=signer.address,
+        max_per_tx_base_units=100_000,          # Max $0.10 per call
+        rolling_budget_24h_base_units=1_000_000, # Daily limit $1.00
+        circuit_max_rpm=5,                      # Tripped if > 5 requests/min
+    )
+)
+
+# 3. Create client with automatic x402 challenge negotiation
+client = AgentPayClient(signer=signer, policy=policy)
+
+# 4. Transparent call (auto-pays 402 challenge via EIP-712 off-chain signature)
+response = client.get("https://api.seller.com/v1/market-data?ticker=NVDA")
+print(response.json())
+```
+
+### LangChain Paid Tool Integration
+```python
+from agentpay.integrations.langchain import PaidTool
+
+market_tool = PaidTool(
+    name="get_stock_quote",
+    description="Fetch real-time stock price (costs $0.05 USDC per query)",
+    endpoint="https://api.seller.com/v1/market-data",
+    method="GET",
+    client=client,
+)
+```
+
+---
+
+## 🔒 Security Guarantees
+- **Non-Custodial**: Private keys never leave the agent's local trust domain.
+- **Fail-Closed**: Any policy violation, budget exhaustion, or circuit trip aborts immediately with zero funds spent.
+- **Gasless for Agents**: AI Agents hold only USDC; execution gas is sponsored via EIP-3009 by the seller or facilitator.
+
+For complete documentation, visit [AgentPay GitHub](https://github.com/july-whj/AgentPay).

open_agentpay-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "open-agentpay"
+version = "0.1.0"
+description = "The Open-Source Payment Infrastructure & Financial Firewall for Autonomous AI Agents"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "AgentPay Contributors" }
+]
+requires-python = ">=3.10"
+keywords = ["agent", "ai", "llm", "x402", "usdc", "eip-712", "financial-firewall", "arbitrum", "langchain"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security",
+]
+dependencies = [
+    "eth-account>=0.11.0",
+    "web3>=6.15.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.6.0",
+    "pydantic-settings>=2.2.0"
+]
+
+[project.optional-dependencies]
+langchain = [
+    "langchain-core>=0.1.0"
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.3.0",
+    "mypy>=1.9.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/july-whj/AgentPay"
+Documentation = "https://github.com/july-whj/AgentPay#readme"
+Repository = "https://github.com/july-whj/AgentPay"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentpay"]

open_agentpay-0.1.0/src/agentpay/__init__.py

@@ -0,0 +1,45 @@
+"""
+AgentPay Python SDK
+The Open-Source Payment Infrastructure & Financial Firewall for Autonomous AI Agents.
+"""
+
+__version__ = "0.1.0"
+
+from agentpay.client import (
+    AgentPayClient,
+    AgentPayTransport,
+    AsyncAgentPayClient,
+    AsyncAgentPayTransport,
+    ISigner,
+    LocalSigner,
+)
+from agentpay.core import (
+    HEADER_PAYMENT_REQUIRED,
+    HEADER_PAYMENT_SIGNATURE,
+    PaymentAuthorization,
+    PaymentChallenge,
+    SignatureData,
+    decode_authorization,
+    decode_challenge,
+    encode_authorization,
+    encode_challenge,
+)
+
+__all__ = [
+    "HEADER_PAYMENT_REQUIRED",
+    "HEADER_PAYMENT_SIGNATURE",
+    "AgentPayClient",
+    "AgentPayTransport",
+    "AsyncAgentPayClient",
+    "AsyncAgentPayTransport",
+    "ISigner",
+    "LocalSigner",
+    "PaymentAuthorization",
+    "PaymentChallenge",
+    "SignatureData",
+    "__version__",
+    "decode_authorization",
+    "decode_challenge",
+    "encode_authorization",
+    "encode_challenge",
+]

open_agentpay-0.1.0/src/agentpay/budget/__init__.py

@@ -0,0 +1,37 @@
+"""
+AgentPay Budget sub-package.
+
+Exposes budget models, ledger records, and reservation tokens for buyer spending limits.
+"""
+
+from __future__ import annotations
+
+from agentpay.core.state import BudgetLedgerState
+from agentpay.policy.models import (
+    BreakerState,
+    LedgerEntryState,
+    PaymentRequest,
+    PolicyConfig,
+    PolicyDecision,
+    ReservationToken,
+)
+
+# Backward compatibility / convenient domain aliases
+BudgetReservation = ReservationToken
+LedgerEntry = LedgerEntryState
+PolicyEvaluationResult = PolicyDecision
+PolicyStatus = BreakerState
+
+__all__ = [
+    "BreakerState",
+    "BudgetLedgerState",
+    "BudgetReservation",
+    "LedgerEntry",
+    "LedgerEntryState",
+    "PaymentRequest",
+    "PolicyConfig",
+    "PolicyDecision",
+    "PolicyEvaluationResult",
+    "PolicyStatus",
+    "ReservationToken",
+]

open_agentpay-0.1.0/src/agentpay/client/__init__.py

@@ -0,0 +1,41 @@
+"""
+AgentPay Client SDK and Signers.
+"""
+
+from __future__ import annotations
+
+from agentpay.client.client import AgentPayClient, AsyncAgentPayClient
+from agentpay.client.errors import (
+    ClientError,
+    InvalidPrivateKeyError,
+    ReservationMismatchError,
+    SignerError,
+    UnsupportedNetworkError,
+)
+from agentpay.client.interfaces import ISigner
+from agentpay.client.signer import (
+    DEFAULT_TOKEN_NAMES,
+    EIP3009_MESSAGE_TYPES,
+    LocalSigner,
+    generate_nonce,
+    parse_caip2_chain_id,
+)
+from agentpay.client.transport import AgentPayTransport, AsyncAgentPayTransport
+
+__all__ = [
+    "DEFAULT_TOKEN_NAMES",
+    "EIP3009_MESSAGE_TYPES",
+    "AgentPayClient",
+    "AgentPayTransport",
+    "AsyncAgentPayClient",
+    "AsyncAgentPayTransport",
+    "ClientError",
+    "ISigner",
+    "InvalidPrivateKeyError",
+    "LocalSigner",
+    "ReservationMismatchError",
+    "SignerError",
+    "UnsupportedNetworkError",
+    "generate_nonce",
+    "parse_caip2_chain_id",
+]

open_agentpay-0.1.0/src/agentpay/client/client.py

@@ -0,0 +1,109 @@
+"""
+AgentPayClient: Drop-in httpx.Client with automatic 402 payment negotiation.
+
+Wraps the financial firewall and EIP-712 cryptographic signer to automatically
+satisfy HTTP 402 Payment Required challenges.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from agentpay.client.interfaces import ISigner
+from agentpay.client.transport import AgentPayTransport, AsyncAgentPayTransport
+from agentpay.policy.interfaces import IPolicyEngine
+
+
+class AgentPayClient(httpx.Client):
+    """
+    HTTP client for autonomous AI agents with integrated financial firewall.
+
+    Inherits from httpx.Client: fully compatible with LangChain, LlamaIndex,
+    and standard Python HTTP toolchains.
+    """
+
+    def __init__(
+        self,
+        signer: ISigner,
+        policy: IPolicyEngine,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        auto_retry_on_402: bool = True,
+        raise_on_policy_rejection: bool = False,
+        clock: Callable[[], int] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.signer = signer
+        self.policy = policy
+        self.auto_retry_on_402 = auto_retry_on_402
+        self.raise_on_policy_rejection = raise_on_policy_rejection
+        self._clock = clock
+
+        inner = transport or httpx.HTTPTransport()
+        agent_transport = AgentPayTransport(
+            inner_transport=inner,
+            signer=signer,
+            policy=policy,
+            auto_retry_on_402=auto_retry_on_402,
+            raise_on_policy_rejection=raise_on_policy_rejection,
+            clock=clock,
+        )
+
+        super().__init__(transport=agent_transport, **kwargs)
+
+    def async_client(
+        self,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        **kwargs: Any,
+    ) -> AsyncAgentPayClient:
+        """Create an asynchronous AsyncAgentPayClient sharing the same signer and policy."""
+        return AsyncAgentPayClient(
+            signer=self.signer,
+            policy=self.policy,
+            transport=transport,
+            auto_retry_on_402=self.auto_retry_on_402,
+            raise_on_policy_rejection=self.raise_on_policy_rejection,
+            clock=self._clock,
+            **kwargs,
+        )
+
+
+class AsyncAgentPayClient(httpx.AsyncClient):
+    """
+    Asynchronous HTTP client for autonomous AI agents with integrated financial firewall.
+
+    Inherits from httpx.AsyncClient.
+    """
+
+    def __init__(
+        self,
+        signer: ISigner,
+        policy: IPolicyEngine,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        auto_retry_on_402: bool = True,
+        raise_on_policy_rejection: bool = False,
+        clock: Callable[[], int] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.signer = signer
+        self.policy = policy
+        self.auto_retry_on_402 = auto_retry_on_402
+        self.raise_on_policy_rejection = raise_on_policy_rejection
+        self._clock = clock
+
+        inner = transport or httpx.AsyncHTTPTransport()
+        agent_transport = AsyncAgentPayTransport(
+            inner_transport=inner,
+            signer=signer,
+            policy=policy,
+            auto_retry_on_402=auto_retry_on_402,
+            raise_on_policy_rejection=raise_on_policy_rejection,
+            clock=clock,
+        )
+
+        super().__init__(transport=agent_transport, **kwargs)

open_agentpay-0.1.0/src/agentpay/client/errors.py

@@ -0,0 +1,28 @@
+"""
+Signer and Client Exceptions for AgentPay.
+"""
+
+from __future__ import annotations
+
+
+class ClientError(Exception):
+    """Base exception for all AgentPay client and signer operations."""
+
+
+class SignerError(ClientError):
+    """Base exception for cryptographic signing errors."""
+
+
+class InvalidPrivateKeyError(SignerError):
+    """Raised when an invalid EVM private key is provided."""
+
+
+class UnsupportedNetworkError(SignerError):
+    """Raised when a challenge specifies a network unsupported by the signer (e.g. non-EIP155)."""
+
+
+class ReservationMismatchError(SignerError):
+    """
+    Raised when an approved ReservationToken does not match the PaymentChallenge.
+    Critical financial firewall guardrail violation.
+    """

open_agentpay-0.1.0/src/agentpay/client/interfaces.py

@@ -0,0 +1,53 @@
+"""
+Signer interface protocols for AgentPay.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from agentpay.core.models import PaymentAuthorization, PaymentChallenge
+from agentpay.policy.models import ReservationToken
+
+
+@runtime_checkable
+class ISigner(Protocol):
+    """
+    Protocol for signing agents and cryptographic keystores.
+    Enforces firewall reservation binding before signing.
+    """
+
+    @property
+    def address(self) -> str:
+        """The canonical lowercase EVM address of the signing wallet."""
+        ...
+
+    def sign_payment_authorization(
+        self,
+        challenge: PaymentChallenge,
+        reservation: ReservationToken,
+        *,
+        nonce: str | None = None,
+        token_name: str | None = None,
+        token_version: str = "2",
+    ) -> PaymentAuthorization:
+        """
+        Sign an EIP-712/3009 transfer authorization for the given challenge.
+
+        MUST verify that the reservation matches the challenge before signing.
+
+        Args:
+            challenge: The PaymentChallenge from the 402 PAYMENT-REQUIRED header.
+            reservation: The Approved ReservationToken from the policy engine.
+            nonce: Optional 32-byte hex nonce. If omitted, a random nonce is generated.
+            token_name: Optional EIP-712 domain token name (e.g. 'USD Coin').
+            token_version: EIP-712 domain version (default '2').
+
+        Returns:
+            PaymentAuthorization populated with cryptographic signature.
+
+        Raises:
+            ReservationMismatchError: If the reservation does not match the challenge.
+            SignerError: If cryptographic signing fails.
+        """
+        ...