apay 0.1.0__py3-none-any.whl

apay/__init__.py

@@ -0,0 +1,44 @@
+"""
+A-Pay (AgentPay) Protocol
+Universal Micropayment & Economic Layer for Autonomous AI Agents.
+"""
+
+from .client import APayClient, APaySession
+from .integrations import (
+    APayCrewTool,
+    APayRequestsWrapper,
+    APayTool,
+    create_apay_tool,
+    create_crew_tool,
+)
+from .proxy import create_proxy_app
+from .relayer import ClaimJournal, ClaimRecord, SettlementRelayer
+from .wallet import (
+    DEFAULT_CHAIN_ID,
+    DEFAULT_EIP712_NAME,
+    DEFAULT_EIP712_VERSION,
+    DEFAULT_ROUTER_ADDRESS,
+    AgentWallet,
+    get_eip712_domain,
+)
+
+__all__ = [
+    "APayClient",
+    "APayCrewTool",
+    "APayRequestsWrapper",
+    "APaySession",
+    "APayTool",
+    "AgentWallet",
+    "ClaimJournal",
+    "ClaimRecord",
+    "DEFAULT_CHAIN_ID",
+    "DEFAULT_EIP712_NAME",
+    "DEFAULT_EIP712_VERSION",
+    "DEFAULT_ROUTER_ADDRESS",
+    "SettlementRelayer",
+    "create_apay_tool",
+    "create_crew_tool",
+    "create_proxy_app",
+    "get_eip712_domain",
+]
+__version__ = "0.1.0"

apay/cli.py

@@ -0,0 +1,216 @@
+"""A-Pay CLI: 1-Command Tooling for Website Owners & AI Agent Builders."""
+
+import time
+
+import click
+import httpx
+import uvicorn
+
+from .client import APaySession
+from .proxy import create_proxy_app
+from .relayer import ClaimJournal, SettlementRelayer
+from .wallet import AgentWallet
+
+
+@click.group()
+@click.version_option("0.1.0", prog_name="apay")
+def main() -> None:
+    """⚡ A-Pay: Universal HTTP 402 Micropayment Rail for AI Agents & APIs."""
+    pass
+
+
+@main.command()
+@click.option(
+    "--target", "-t", required=True, help="Upstream API/website URL to protect (e.g. http://localhost:8000)"
+)
+@click.option("--price", "-p", required=True, type=float, help="Price per request in USDC (e.g. 0.001)")
+@click.option("--wallet", "-w", required=True, help="Receiver wallet address to collect funds (0x...)")
+@click.option("--port", default=8080, type=int, help="Port to run the A-Pay Gateway on (default: 8080)")
+@click.option("--host", default="0.0.0.0", help="Host to bind gateway (default: 0.0.0.0)")
+@click.option("--network", default="base", help="Settlement network (default: base)")
+def protect(target: str, price: float, wallet: str, port: int, host: str, network: str) -> None:
+    """🛡️ Protect ANY website or API with an instant 1-command HTTP 402 Paywall."""
+    click.echo(click.style("==================================================", fg="cyan", bold=True))
+    click.echo(click.style("⚡ A-PAY GATEWAY IS ACTIVE", fg="green", bold=True))
+    click.echo(click.style("==================================================", fg="cyan", bold=True))
+    click.echo(f"  Target URL       : {target}")
+    click.echo(f"  Paywall Price    : ${price} USDC / request")
+    click.echo(f"  Receiver Wallet  : {wallet}")
+    click.echo(f"  Settlement Rail  : {network}")
+    click.echo(f"  Gateway Running  : http://{host}:{port}")
+    click.echo(click.style("\nIncoming AI bots will be challenged with HTTP 402 unless paid.\n", fg="yellow"))
+
+    app = create_proxy_app(target_url=target, receiver_wallet=wallet, price_usdc=price, network=network)
+    uvicorn.run(app, host=host, port=port, log_level="info")
+
+
+@main.group()
+def wallet() -> None:
+    """🔐 Manage Agent Wallets & Cryptographic Keys."""
+    pass
+
+
+@wallet.command("new")
+@click.option("--max-call", default=0.05, type=float, help="Max spend limit per API call in USDC")
+@click.option("--daily-budget", default=5.0, type=float, help="Max total daily budget in USDC")
+def wallet_new(max_call: float, daily_budget: float) -> None:
+    """Generate a new cryptographic Agent Wallet."""
+    w = AgentWallet.create(max_per_call_usdc=max_call, daily_budget_usdc=daily_budget)
+    click.echo(click.style("\n✨ New Agent Wallet Generated Successfully!\n", fg="green", bold=True))
+    click.echo(f"  Address         : {click.style(w.address, fg='cyan', bold=True)}")
+    click.echo(f"  Private Key     : {click.style(w.private_key, fg='red')}")
+    click.echo(f"  Max Per Call    : ${w.max_per_call_usdc} USDC")
+    click.echo(f"  Daily Budget    : ${w.daily_budget_usdc} USDC")
+    click.echo(
+        click.style("\n⚠️ Keep the private key safe. Pass it to APaySession(private_key=...)\n", fg="yellow")
+    )
+
+
+@main.command()
+@click.option("--url", "-u", required=True, help="URL of the protected API endpoint")
+@click.option("--key", "-k", required=True, help="Agent's private key (0x...)")
+@click.option("--budget", "-b", default=5.0, type=float, help="Daily budget limit in USDC")
+def pay(url: str, key: str, budget: float) -> None:
+    """🤖 Make a test auto-settling request to an A-Pay protected URL."""
+    click.echo(f"Contacting {url} with agent wallet...")
+    agent_wallet = AgentWallet(private_key=key, daily_budget_usdc=budget)
+    session = APaySession(agent_wallet)
+    try:
+        resp = session.get(url)
+        click.echo(click.style(f"\n✅ Status: {resp.status_code}", fg="green", bold=True))
+        click.echo(f"X-APay-Settled: {resp.headers.get('X-APay-Settled')}")
+        click.echo(f"Response Body : {resp.text[:300]}")
+    except Exception as e:
+        click.echo(click.style(f"❌ Error: {e!s}", fg="red"))
+    finally:
+        session.close()
+
+
+@main.group()
+def claims() -> None:
+    """📊 Inspect & manage offline verified micropayment claims."""
+    pass
+
+
+@claims.command("list")
+def claims_list() -> None:
+    """List all collected claims waiting for on-chain settlement."""
+    journal = ClaimJournal()
+    all_claims = journal.load_all()
+    unsettled = [c for c in all_claims if not c.settled]
+    total_unsettled_usdc = sum(c.price_usdc for c in unsettled)
+
+    click.echo(click.style("\n📜 A-Pay Claims Ledger Summary:\n", fg="cyan", bold=True))
+    click.echo(f"  Total Claims Recorded : {len(all_claims)}")
+    click.echo(f"  Unsettled Claims      : {len(unsettled)}")
+    click.echo(f"  Pending Gross Value   : ${total_unsettled_usdc:.4f} USDC")
+
+    if unsettled:
+        click.echo("\n  Recent Pending Claims:")
+        for c in unsettled[-5:]:
+            click.echo(
+                f"    • [{c.id}] Payer: {c.payer[:10]}... | Amount: ${c.price_usdc:.4f} USDC | Nonce: {c.nonce[:8]}..."
+            )
+        click.echo(
+            click.style("\nRun `apay settle --dry-run` to preview batch settlement breakdown.\n", fg="yellow")
+        )
+    else:
+        click.echo(click.style("\n✨ All claims are settled or ledger is clean.\n", fg="green"))
+
+
+@claims.command("clear")
+def claims_clear() -> None:
+    """Clear claims journal."""
+    journal = ClaimJournal()
+    journal.clear()
+    click.echo(click.style("✅ Claims ledger cleared successfully.", fg="green"))
+
+
+@main.command()
+@click.option("--key", "-k", help="Merchant / Relayer private key to sign on-chain settlement")
+@click.option("--dry-run", is_flag=True, help="Simulate batch settlement without broadcasting on-chain")
+def settle(key: str | None, dry_run: bool) -> None:
+    """⚡ Batch settle pending micropayment claims onto Base L2 APayRouter."""
+    relayer = SettlementRelayer()
+    unsettled = relayer.journal.get_unsettled()
+
+    if not unsettled:
+        click.echo(click.style("\n✨ No unsettled claims found in ledger.", fg="yellow"))
+        return
+
+    simulation = relayer.simulate_batch(unsettled)
+
+    click.echo(click.style("\n==================================================", fg="cyan", bold=True))
+    click.echo(click.style("⚡ A-PAY BATCH SETTLEMENT ENGINE", fg="green", bold=True))
+    click.echo(click.style("==================================================", fg="cyan", bold=True))
+    click.echo(f"  Settlement Rail     : {simulation['settlement_rail']}")
+    click.echo(f"  Target Claims Count : {simulation['claims_count']}")
+    click.echo(f"  Gross Volume        : ${simulation['gross_volume_usdc']:.4f} USDC")
+    click.echo(f"  Protocol Fee (1.0%) : ${simulation['protocol_fee_usdc']:.6f} USDC")
+    click.echo(f"  Net Merchant Payout : ${simulation['net_merchant_usdc']:.4f} USDC")
+    click.echo(f"  Router Contract     : {simulation['router_contract']}")
+
+    if dry_run or not key:
+        click.echo(
+            click.style(
+                "\nℹ️ Dry-run mode completed. Pass `--key 0x...` to broadcast live to Base Sepolia.\n",
+                fg="yellow",
+            )
+        )
+        return
+
+    click.echo("\n🚀 Broadcasting batch settlement to Base L2...")
+    result = relayer.execute_settle(private_key=key, dry_run=False)
+    click.echo(
+        click.style(f"✅ Batch Settled Successfully! Status: {result['status']}", fg="green", bold=True)
+    )
+    click.echo(f"  Transaction Hash    : {result['tx_hash']}")
+    click.echo(f"  Basescan Explorer   : {result['explorer_url']}\n")
+
+
+@main.command()
+def verify() -> None:
+    """🔬 Multi-dimensional system, cryptographic benchmark & RPC health check."""
+    click.echo(
+        click.style("\n⚡ Running A-Pay Multi-Dimensional System Health Check...\n", fg="cyan", bold=True)
+    )
+
+    # 1. Benchmark Cryptographic Signing
+    w = AgentWallet.create()
+    t0 = time.perf_counter()
+    iterations = 50
+    for i in range(iterations):
+        sig = w.sign_challenge(f"APAY:0x5eC0:1000:{i}")
+        AgentWallet.verify_signature(f"APAY:0x5eC0:1000:{i}", sig)
+    avg_latency_ms = ((time.perf_counter() - t0) / iterations) * 1000.0
+
+    click.echo(f"  🔐 Cryptographic Sign & Verify Latency : {avg_latency_ms:.2f} ms / op (Target: < 20ms)")
+    if avg_latency_ms < 20.0:
+        click.echo(click.style("     -> PASS: Ultra-low latency machine-to-machine verified.", fg="green"))
+    else:
+        click.echo(click.style("     -> WARN: Higher than expected latency.", fg="yellow"))
+
+    # 2. Check RPC Node Connectivity
+    rpc_url = "https://sepolia.base.org"
+    try:
+        with httpx.Client(timeout=5.0) as client:
+            resp = client.post(
+                rpc_url, json={"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}
+            )
+            if resp.status_code == 200 and "result" in resp.json():
+                block_hex = resp.json()["result"]
+                block_num = int(block_hex, 16)
+                click.echo(f"  🌐 Base Sepolia RPC Connectivity       : Connected (Block #{block_num:,})")
+                click.echo(click.style("     -> PASS: Live on-chain rail active.", fg="green"))
+            else:
+                click.echo(click.style("     -> WARN: RPC node returned non-standard response.", fg="yellow"))
+    except Exception as err:
+        click.echo(click.style(f"  🌐 Base Sepolia RPC Error             : {err!s}", fg="yellow"))
+
+    click.echo(
+        click.style("\n✅ A-Pay Protocol Core is operating at 100% capacity.\n", fg="green", bold=True)
+    )
+
+
+if __name__ == "__main__":
+    main()

apay/client.py

@@ -0,0 +1,146 @@
+"""Async & Sync HTTP Clients with Automatic HTTP 402 Micropayment Negotiation."""
+
+from typing import Any
+
+import httpx
+
+from .wallet import DEFAULT_CHAIN_ID, DEFAULT_ROUTER_ADDRESS, AgentWallet
+
+
+class APayClient:
+    """Asynchronous HTTP Client for AI Agents with auto-settling 402 handling."""
+
+    def __init__(self, wallet: AgentWallet, timeout: float = 30.0, use_eip712: bool = True) -> None:
+        self.wallet = wallet
+        self.client = httpx.AsyncClient(timeout=timeout)
+        self.use_eip712 = use_eip712
+
+    async def get(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self._request("GET", url, **kwargs)
+
+    async def post(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self._request("POST", url, **kwargs)
+
+    async def _request(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        # 1. Initial attempt
+        response = await self.client.request(method, url, **kwargs)
+
+        # 2. Intercept HTTP 402 Payment Required
+        if response.status_code == 402:
+            return await self._handle_402_and_retry(method, url, response, **kwargs)
+
+        return response
+
+    async def _handle_402_and_retry(
+        self, method: str, url: str, initial_response: httpx.Response, **kwargs: Any
+    ) -> httpx.Response:
+        headers = initial_response.headers
+        raw_amount = headers.get("X-APay-Amount", "0")
+        try:
+            price = float(raw_amount) / 1_000_000.0  # 6 decimals for USDC
+        except (ValueError, TypeError):
+            return initial_response
+        receiver = headers.get("X-APay-Receiver")
+        nonce = headers.get("X-APay-Nonce")
+
+        if not receiver or not nonce:
+            # Not a standard APay 402 response, return original response
+            return initial_response
+
+        # Check local wallet budget guardrails
+        can_pay, reason = self.wallet.can_spend(price)
+        if not can_pay:
+            raise PermissionError(f"[A-Pay Guardrail Triggered] Cannot pay ${price} USDC: {reason}")
+
+        scheme = headers.get("X-APay-Scheme", "eip712" if self.use_eip712 else "legacy")
+        chain_id = int(headers.get("X-APay-Chain-Id", str(DEFAULT_CHAIN_ID)))
+        router = headers.get("X-APay-Router", DEFAULT_ROUTER_ADDRESS)
+
+        if self.use_eip712 and scheme == "eip712":
+            signature = self.wallet.sign_typed_payment(
+                receiver=receiver,
+                amount_base_units=raw_amount,
+                nonce=nonce,
+                chain_id=chain_id,
+                router_address=router,
+            )
+            auth_header = f"APay eip712:{signature}:{self.wallet.address}:{nonce}:{raw_amount}"
+        else:
+            payload = f"APAY:{receiver}:{raw_amount}:{nonce}"
+            signature = self.wallet.sign_challenge(payload)
+            auth_header = f"APay sig:{signature}:{self.wallet.address}:{nonce}:{raw_amount}"
+
+        req_headers = dict(kwargs.get("headers") or {})
+        req_headers["Authorization"] = auth_header
+        kwargs["headers"] = req_headers
+
+        self.wallet.record_spend(price)
+        return await self.client.request(method, url, **kwargs)
+
+    async def aclose(self) -> None:
+        await self.client.aclose()
+
+
+class APaySession:
+    """Synchronous HTTP Session for simple Python scripts, LangChain, and CrewAI."""
+
+    def __init__(self, wallet: AgentWallet, timeout: float = 30.0, use_eip712: bool = True) -> None:
+        self.wallet = wallet
+        self.client = httpx.Client(timeout=timeout)
+        self.use_eip712 = use_eip712
+
+    def get(self, url: str, **kwargs: Any) -> httpx.Response:
+        return self._request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> httpx.Response:
+        return self._request("POST", url, **kwargs)
+
+    def _request(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        response = self.client.request(method, url, **kwargs)
+
+        if response.status_code == 402:
+            headers = response.headers
+            raw_amount = headers.get("X-APay-Amount", "0")
+            try:
+                price = float(raw_amount) / 1_000_000.0
+            except (ValueError, TypeError):
+                return response
+            receiver = headers.get("X-APay-Receiver")
+            nonce = headers.get("X-APay-Nonce")
+
+            if not receiver or not nonce:
+                return response
+
+            can_pay, reason = self.wallet.can_spend(price)
+            if not can_pay:
+                raise PermissionError(f"[A-Pay Guardrail Triggered] Cannot pay ${price} USDC: {reason}")
+
+            scheme = headers.get("X-APay-Scheme", "eip712" if self.use_eip712 else "legacy")
+            chain_id = int(headers.get("X-APay-Chain-Id", str(DEFAULT_CHAIN_ID)))
+            router = headers.get("X-APay-Router", DEFAULT_ROUTER_ADDRESS)
+
+            if self.use_eip712 and scheme == "eip712":
+                signature = self.wallet.sign_typed_payment(
+                    receiver=receiver,
+                    amount_base_units=raw_amount,
+                    nonce=nonce,
+                    chain_id=chain_id,
+                    router_address=router,
+                )
+                auth_header = f"APay eip712:{signature}:{self.wallet.address}:{nonce}:{raw_amount}"
+            else:
+                payload = f"APAY:{receiver}:{raw_amount}:{nonce}"
+                signature = self.wallet.sign_challenge(payload)
+                auth_header = f"APay sig:{signature}:{self.wallet.address}:{nonce}:{raw_amount}"
+
+            req_headers = dict(kwargs.get("headers") or {})
+            req_headers["Authorization"] = auth_header
+            kwargs["headers"] = req_headers
+
+            self.wallet.record_spend(price)
+            return self.client.request(method, url, **kwargs)
+
+        return response
+
+    def close(self) -> None:
+        self.client.close()

apay/integrations/__init__.py

@@ -0,0 +1,15 @@
+"""A-Pay Agent Framework Integrations.
+
+Provides integrations with LangChain, CrewAI, and other autonomous agent ecosystems.
+"""
+
+from .crewai import APayCrewTool, create_crew_tool
+from .langchain import APayRequestsWrapper, APayTool, create_apay_tool
+
+__all__ = [
+    "APayCrewTool",
+    "APayRequestsWrapper",
+    "APayTool",
+    "create_apay_tool",
+    "create_crew_tool",
+]

apay/integrations/crewai.py

@@ -0,0 +1,92 @@
+"""CrewAI Integration for A-Pay Protocol.
+
+Enables CrewAI autonomous agents to seamlessly execute HTTP 402 micropayments
+when accessing restricted data feeds or services.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from apay.client import APayClient, APaySession
+from apay.wallet import AgentWallet
+
+try:
+    from crewai.tools import BaseTool as CrewAIBaseTool
+except ImportError:  # pragma: no cover
+    CrewAIBaseTool = None  # type: ignore[assignment, misc]
+
+
+class APayCrewToolInput(BaseModel):
+    """Input arguments schema for CrewAI tool execution."""
+
+    query: str = Field(default="", description="Input or parameters passed to the paid API endpoint")
+
+
+class _BaseCrewToolImpl(BaseModel):
+    name: str
+    description: str
+    target_url: str
+    wallet: AgentWallet
+    method: str = "GET"
+    use_eip712: bool = True
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def _run(self, *args: Any, **kwargs: Any) -> str:
+        """Synchronously call API with auto-negotiating HTTP 402 payments."""
+        query = str(kwargs.get("query", args[0] if args else ""))
+        session = APaySession(wallet=self.wallet, use_eip712=self.use_eip712)
+        try:
+            if self.method.upper() == "GET":
+                params = {"q": query} if query else {}
+                resp = session.get(self.target_url, params=params)
+            else:
+                payload = {"query": query} if query else {}
+                resp = session.post(self.target_url, json=payload)
+            return resp.text
+        finally:
+            session.close()
+
+    async def _arun(self, *args: Any, **kwargs: Any) -> str:
+        """Asynchronously call API with auto-negotiating HTTP 402 payments."""
+        query = str(kwargs.get("query", args[0] if args else ""))
+        client = APayClient(wallet=self.wallet, use_eip712=self.use_eip712)
+        try:
+            if self.method.upper() == "GET":
+                params = {"q": query} if query else {}
+                resp = await client.get(self.target_url, params=params)
+            else:
+                payload = {"query": query} if query else {}
+                resp = await client.post(self.target_url, json=payload)
+            return resp.text
+        finally:
+            await client.aclose()
+
+
+if CrewAIBaseTool is not None:  # pragma: no cover
+
+    class APayCrewTool(_BaseCrewToolImpl, CrewAIBaseTool):  # type: ignore[misc]
+        args_schema: type[BaseModel] = APayCrewToolInput
+else:
+
+    class APayCrewTool(_BaseCrewToolImpl):  # type: ignore[no-redef]
+        args_schema: type[BaseModel] = APayCrewToolInput
+
+
+def create_crew_tool(
+    name: str,
+    description: str,
+    target_url: str,
+    wallet: AgentWallet,
+    method: str = "GET",
+    use_eip712: bool = True,
+) -> APayCrewTool:
+    """Factory helper to equip a CrewAI Agent with an A-Pay micropayment tool."""
+    return APayCrewTool(
+        name=name,
+        description=description,
+        target_url=target_url,
+        wallet=wallet,
+        method=method,
+        use_eip712=use_eip712,
+    )

apay/integrations/langchain.py

@@ -0,0 +1,137 @@
+"""LangChain Integration for A-Pay Protocol.
+
+Provides drop-in tools and requests wrappers enabling LangChain AI agents
+to autonomously navigate HTTP 402 payment-gated APIs using AgentWallet.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from apay.client import APayClient, APaySession
+from apay.wallet import AgentWallet
+
+try:
+    from langchain_core.tools import BaseTool as LangchainBaseTool
+except ImportError:  # pragma: no cover
+    LangchainBaseTool = None  # type: ignore[assignment, misc]
+
+
+class APayRequestsWrapper:
+    """Drop-in HTTP client wrapper for LangChain with automated HTTP 402 negotiation."""
+
+    def __init__(self, wallet: AgentWallet, use_eip712: bool = True, timeout: float = 30.0) -> None:
+        self.wallet = wallet
+        self.session = APaySession(wallet=wallet, timeout=timeout, use_eip712=use_eip712)
+        self.async_client = APayClient(wallet=wallet, timeout=timeout, use_eip712=use_eip712)
+
+    def get(self, url: str, **kwargs: Any) -> str:
+        """Synchronously execute GET request, auto-negotiating HTTP 402 if challenged."""
+        resp = self.session.get(url, **kwargs)
+        return resp.text
+
+    def post(self, url: str, **kwargs: Any) -> str:
+        """Synchronously execute POST request, auto-negotiating HTTP 402 if challenged."""
+        resp = self.session.post(url, **kwargs)
+        return resp.text
+
+    async def aget(self, url: str, **kwargs: Any) -> str:
+        """Asynchronously execute GET request, auto-negotiating HTTP 402 if challenged."""
+        resp = await self.async_client.get(url, **kwargs)
+        return resp.text
+
+    async def apost(self, url: str, **kwargs: Any) -> str:
+        """Asynchronously execute POST request, auto-negotiating HTTP 402 if challenged."""
+        resp = await self.async_client.post(url, **kwargs)
+        return resp.text
+
+    def close(self) -> None:
+        self.session.close()
+
+    async def aclose(self) -> None:
+        await self.async_client.aclose()
+
+
+class APayToolInput(BaseModel):
+    """Input arguments for invoking an A-Pay gated tool."""
+
+    query: str = Field(default="", description="Query string or instructions to pass to the endpoint")
+
+
+class _BaseToolImpl(BaseModel):
+    name: str
+    description: str
+    target_url: str
+    wallet: AgentWallet
+    method: str = "GET"
+    use_eip712: bool = True
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def _execute(self, query: str = "") -> str:
+        session = APaySession(wallet=self.wallet, use_eip712=self.use_eip712)
+        try:
+            url = self.target_url
+            if self.method.upper() == "GET":
+                params = {"q": query} if query else {}
+                resp = session.get(url, params=params)
+            else:
+                payload = {"query": query} if query else {}
+                resp = session.post(url, json=payload)
+            return resp.text
+        finally:
+            session.close()
+
+    async def _aexecute(self, query: str = "") -> str:
+        client = APayClient(wallet=self.wallet, use_eip712=self.use_eip712)
+        try:
+            url = self.target_url
+            if self.method.upper() == "GET":
+                params = {"q": query} if query else {}
+                resp = await client.get(url, params=params)
+            else:
+                payload = {"query": query} if query else {}
+                resp = await client.post(url, json=payload)
+            return resp.text
+        finally:
+            await client.aclose()
+
+    def run(self, tool_input: str | dict[str, Any] = "") -> str:
+        q = tool_input if isinstance(tool_input, str) else str(tool_input.get("query", ""))
+        return self._execute(query=q)
+
+    def _run(self, *args: Any, **kwargs: Any) -> str:
+        q = str(kwargs.get("query", args[0] if args else ""))
+        return self._execute(query=q)
+
+    async def _arun(self, *args: Any, **kwargs: Any) -> str:
+        q = str(kwargs.get("query", args[0] if args else ""))
+        return await self._aexecute(query=q)
+
+
+if LangchainBaseTool is not None:  # pragma: no cover
+
+    class APayTool(_BaseToolImpl, LangchainBaseTool):  # type: ignore[misc]
+        args_schema: type[BaseModel] = APayToolInput
+else:
+
+    class APayTool(_BaseToolImpl):  # type: ignore[no-redef]
+        args_schema: type[BaseModel] = APayToolInput
+
+
+def create_apay_tool(
+    name: str,
+    description: str,
+    target_url: str,
+    wallet: AgentWallet,
+    method: str = "GET",
+    use_eip712: bool = True,
+) -> APayTool:
+    """Convenience factory to create a LangChain-compatible tool for an HTTP 402 API."""
+    return APayTool(
+        name=name,
+        description=description,
+        target_url=target_url,
+        wallet=wallet,
+        method=method,
+        use_eip712=use_eip712,
+    )