abapay-sdk 0.1.0__tar.gz

abapay_sdk-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# Hardhat build output
+artifacts/
+cache/
+typechain-types/

abapay_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: abapay-sdk
+Version: 0.1.0
+Summary: Pay real-world bills (airtime, data, electricity, cable) from an agent's own Celo wallet — zero-setup x402, or a linked-wallet client for the fuller MCP tool catalog.
+Project-URL: Homepage, https://agents.abapays.com
+Project-URL: Repository, https://github.com/investorphem/AbaPay
+Project-URL: Documentation, https://docs.abapays.com
+Project-URL: Issues, https://github.com/investorphem/AbaPay/issues
+Author: Masonode Technologies Limited
+License-Expression: MIT
+Keywords: a2a,abapay,agent-payments,celo,cli,eip-3009,mcp,stablecoin,x402
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: eth-account<1.0,>=0.10
+Provides-Extra: dev
+Requires-Dist: pytest-httpserver>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# abapay-sdk (Python)
+
+Pay real-world bills — airtime, mobile data, electricity, cable TV — from an agent's own Celo
+wallet. Mirrors [abapay-sdk (npm)](https://www.npmjs.com/package/abapay-sdk) field-for-field.
+Two ways in, matching [agents.abapays.com](https://agents.abapays.com):
+
+- **`pay_bill_via_x402`** — zero setup. No account, no API key, no PIN, no visit to
+  abapays.com. Your agent's wallet signs one EIP-3009 authorization and the bill is paid.
+- **`AbaPayAgent`** — a linked-wallet client for the fuller MCP tool catalog (balances,
+  history, schedules). One on-chain signature to link, then an API key + PIN per payment.
+
+Full protocol details: [docs.abapays.com](https://docs.abapays.com). Celo mainnet only.
+
+## Install
+
+```bash
+pip install abapay-sdk
+```
+
+`eth-account` is the only runtime dependency — used for EIP-712/personal_sign signing, the
+Python-ecosystem equivalent of what viem does for the TypeScript SDK.
+
+## Zero setup: pay a bill via x402
+
+```python
+from eth_account import Account
+from abapay import pay_bill_via_x402, BillDetails
+
+account = Account.from_key("0x...")  # PRIVATE_KEY env var, not committed
+
+result = pay_bill_via_x402(
+    account,
+    BillDetails(
+        serviceID="mtn", serviceCategory="AIRTIME", network="MTN",
+        billersCode="08012345678", nairaAmount=1000, token="USDT",
+    ),
+)
+print(result.status, result.tx_hash)
+```
+
+That's the whole integration. `account` never touches abapays.com beyond this one HTTP call —
+no account creation, no API key, no PIN. Full wire format:
+[agents.abapays.com/x402](https://agents.abapays.com/x402) — nothing here is hidden, read
+`src/abapay/x402.py` to see or port it to another language yourself.
+
+## Linked wallet: the fuller tool catalog
+
+```python
+from eth_account import Account
+from abapay import AbaPayAgent, LinkParams
+
+account = Account.from_key("0x...")
+
+# One-time: prove wallet ownership, mint an Agent Hub api_key. Save agent.api_key somewhere —
+# there is no recovery flow other than linking again.
+agent = AbaPayAgent.link(LinkParams(signer=account, pin="1234"))
+
+# Elsewhere, an on-chain approve() + setSpendingAllowance() grants AbaPay a bounded, revocable
+# allowance — see examples/agent-quickstart.mjs in the main repo for the two calls. Nothing in
+# this SDK can raise that allowance on your behalf; only your own wallet can.
+
+print(agent.check_balance())
+
+agent.pay_bill(pin="1234", service="AIRTIME", provider="mtn", account_number="08012345678", amount_ngn=1000)
+```
+
+Reattach to a previously-minted key without signing again:
+
+```python
+agent = AbaPayAgent.from_api_key(saved_api_key, wallet_address)
+```
+
+## CLI
+
+```bash
+pip install abapay-sdk
+
+PRIVATE_KEY=0x... abapay pay --service AIRTIME --provider mtn --to 08012345678 --amount 1000
+PRIVATE_KEY=0x... abapay link --pin 1234
+abapay balance --api-key aba_mcp_xxxxx
+abapay history --api-key aba_mcp_xxxxx --limit 5
+```
+
+## Errors
+
+Every failure throws `AbaPayError` (`.message`, and `.response` carrying whatever AbaPay's API
+returned, when there was one). Full error code reference:
+[agents.abapays.com/errors](https://agents.abapays.com/errors).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against a real local HTTP server (`pytest-httpserver`), not a patched `urlopen` —
+`test_x402.py` specifically recovers the signer's address from the signed EIP-712 typed data
+and asserts it matches, the same correctness guarantee the TypeScript SDK's own test suite
+makes.
+
+## License
+
+MIT

abapay_sdk-0.1.0/README.md

@@ -0,0 +1,104 @@
+# abapay-sdk (Python)
+
+Pay real-world bills — airtime, mobile data, electricity, cable TV — from an agent's own Celo
+wallet. Mirrors [abapay-sdk (npm)](https://www.npmjs.com/package/abapay-sdk) field-for-field.
+Two ways in, matching [agents.abapays.com](https://agents.abapays.com):
+
+- **`pay_bill_via_x402`** — zero setup. No account, no API key, no PIN, no visit to
+  abapays.com. Your agent's wallet signs one EIP-3009 authorization and the bill is paid.
+- **`AbaPayAgent`** — a linked-wallet client for the fuller MCP tool catalog (balances,
+  history, schedules). One on-chain signature to link, then an API key + PIN per payment.
+
+Full protocol details: [docs.abapays.com](https://docs.abapays.com). Celo mainnet only.
+
+## Install
+
+```bash
+pip install abapay-sdk
+```
+
+`eth-account` is the only runtime dependency — used for EIP-712/personal_sign signing, the
+Python-ecosystem equivalent of what viem does for the TypeScript SDK.
+
+## Zero setup: pay a bill via x402
+
+```python
+from eth_account import Account
+from abapay import pay_bill_via_x402, BillDetails
+
+account = Account.from_key("0x...")  # PRIVATE_KEY env var, not committed
+
+result = pay_bill_via_x402(
+    account,
+    BillDetails(
+        serviceID="mtn", serviceCategory="AIRTIME", network="MTN",
+        billersCode="08012345678", nairaAmount=1000, token="USDT",
+    ),
+)
+print(result.status, result.tx_hash)
+```
+
+That's the whole integration. `account` never touches abapays.com beyond this one HTTP call —
+no account creation, no API key, no PIN. Full wire format:
+[agents.abapays.com/x402](https://agents.abapays.com/x402) — nothing here is hidden, read
+`src/abapay/x402.py` to see or port it to another language yourself.
+
+## Linked wallet: the fuller tool catalog
+
+```python
+from eth_account import Account
+from abapay import AbaPayAgent, LinkParams
+
+account = Account.from_key("0x...")
+
+# One-time: prove wallet ownership, mint an Agent Hub api_key. Save agent.api_key somewhere —
+# there is no recovery flow other than linking again.
+agent = AbaPayAgent.link(LinkParams(signer=account, pin="1234"))
+
+# Elsewhere, an on-chain approve() + setSpendingAllowance() grants AbaPay a bounded, revocable
+# allowance — see examples/agent-quickstart.mjs in the main repo for the two calls. Nothing in
+# this SDK can raise that allowance on your behalf; only your own wallet can.
+
+print(agent.check_balance())
+
+agent.pay_bill(pin="1234", service="AIRTIME", provider="mtn", account_number="08012345678", amount_ngn=1000)
+```
+
+Reattach to a previously-minted key without signing again:
+
+```python
+agent = AbaPayAgent.from_api_key(saved_api_key, wallet_address)
+```
+
+## CLI
+
+```bash
+pip install abapay-sdk
+
+PRIVATE_KEY=0x... abapay pay --service AIRTIME --provider mtn --to 08012345678 --amount 1000
+PRIVATE_KEY=0x... abapay link --pin 1234
+abapay balance --api-key aba_mcp_xxxxx
+abapay history --api-key aba_mcp_xxxxx --limit 5
+```
+
+## Errors
+
+Every failure throws `AbaPayError` (`.message`, and `.response` carrying whatever AbaPay's API
+returned, when there was one). Full error code reference:
+[agents.abapays.com/errors](https://agents.abapays.com/errors).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against a real local HTTP server (`pytest-httpserver`), not a patched `urlopen` —
+`test_x402.py` specifically recovers the signer's address from the signed EIP-712 typed data
+and asserts it matches, the same correctness guarantee the TypeScript SDK's own test suite
+makes.
+
+## License
+
+MIT

abapay_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "abapay-sdk"
+version = "0.1.0"
+description = "Pay real-world bills (airtime, data, electricity, cable) from an agent's own Celo wallet — zero-setup x402, or a linked-wallet client for the fuller MCP tool catalog."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Masonode Technologies Limited" }]
+keywords = ["abapay", "celo", "x402", "a2a", "mcp", "agent-payments", "stablecoin", "eip-3009", "cli"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+]
+dependencies = [
+  "eth-account>=0.10,<1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-httpserver>=1.0"]
+
+[project.urls]
+Homepage = "https://agents.abapays.com"
+Repository = "https://github.com/investorphem/AbaPay"
+Documentation = "https://docs.abapays.com"
+Issues = "https://github.com/investorphem/AbaPay/issues"
+
+[project.scripts]
+abapay = "abapay.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/abapay"]

abapay_sdk-0.1.0/src/abapay/__init__.py

@@ -0,0 +1,25 @@
+"""abapay — pay real-world bills from a Celo wallet, no browser required.
+
+Mirrors abapay-sdk (npm) field-for-field. Two ways in:
+
+- `pay_bill_via_x402` — zero setup. No account, no API key, no PIN.
+- `AbaPayAgent` — a linked-wallet client for the fuller MCP tool catalog.
+
+See https://agents.abapays.com/sdk and https://agents.abapays.com/tools.
+"""
+
+from .agent import AbaPayAgent
+from .types import AbaPayError, BillDetails, LinkParams, X402PayResult
+from .x402 import DEFAULT_BASE_URL, pay_bill_via_x402
+
+__all__ = [
+    "AbaPayAgent",
+    "AbaPayError",
+    "BillDetails",
+    "LinkParams",
+    "X402PayResult",
+    "DEFAULT_BASE_URL",
+    "pay_bill_via_x402",
+]
+
+__version__ = "0.1.0"

abapay_sdk-0.1.0/src/abapay/agent.py

@@ -0,0 +1,154 @@
+"""AbaPayAgent — mirrors sdk/src/agent.ts. Links a wallet ONCE (a signature, not a deposit)
+and then calls the fuller MCP tool catalog with an api_key + a PIN on every payment. See
+https://agents.abapays.com/a2a for why this and x402.py have genuinely different trust models.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+from .types import AbaPayError, LinkParams
+from .x402 import DEFAULT_BASE_URL
+
+_PIN_RE = re.compile(r"^\d{4,6}$")
+
+
+def _http_json(url: str, method: str, body: Optional[dict] = None, headers: Optional[dict] = None) -> dict:
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    all_headers = {"Content-Type": "application/json"}
+    if headers:
+        all_headers.update(headers)
+    req = urllib.request.Request(url, data=data, headers=all_headers, method=method)
+    try:
+        with urllib.request.urlopen(req) as res:
+            return json.loads(res.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8")
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            raise AbaPayError(f"AbaPay returned a non-JSON response (HTTP {e.code}): {raw[:300]}")
+
+
+class AbaPayAgent:
+    """A linked AbaPay agent session — one api_key, reusable across as many tool calls as
+    needed. Get one via `AbaPayAgent.link(...)`."""
+
+    def __init__(self, api_key: str, wallet_address: str, base_url: str = DEFAULT_BASE_URL):
+        self.api_key = api_key
+        self.wallet_address = wallet_address
+        self._base_url = base_url
+
+    @staticmethod
+    def link(params: LinkParams) -> "AbaPayAgent":
+        """Prove ownership of a wallet with a plain signed message (no OAuth, no browser) and
+        mint an Agent Hub api_key. This does NOT grant AbaPay any spending allowance by
+        itself — that's a separate on-chain step (approve + setSpendingAllowance), left to the
+        caller since it moves the caller's own funds.
+
+        Raises AbaPayError if the signature is rejected or the PIN is malformed.
+        """
+        if not _PIN_RE.match(params.pin):
+            raise AbaPayError("PIN must be 4-6 digits.")
+
+        timestamp = str(int(time.time() * 1000))
+        message = f"AbaPay Agent Action: POST:/api/agent/link: {timestamp}"
+        signed = params.signer.sign_message(_personal_sign_message(message))
+        signature = signed.signature.hex()
+        if not signature.startswith("0x"):
+            signature = "0x" + signature
+
+        data = _http_json(
+            f"{params.base_url.rstrip('/')}/api/agent/link",
+            "POST",
+            body={
+                "wallet_address": params.signer.address,
+                "channel": "MCP",
+                "pin": params.pin,
+                "approved_chain": params.approved_chain,
+                "approved_token": params.approved_token,
+                "mcp_key_label": params.label,
+            },
+            headers={
+                "x-wallet-address": params.signer.address,
+                "x-wallet-signature": signature,
+                "x-wallet-timestamp": timestamp,
+            },
+        )
+        if not data.get("success") or not data.get("api_key"):
+            raise AbaPayError(data.get("message") or "Link failed.", response=data)
+        return AbaPayAgent(data["api_key"], params.signer.address, params.base_url)
+
+    @staticmethod
+    def from_api_key(api_key: str, wallet_address: str, base_url: str = DEFAULT_BASE_URL) -> "AbaPayAgent":
+        """Reattach to an api_key minted earlier — no new signature needed."""
+        return AbaPayAgent(api_key, wallet_address, base_url)
+
+    def call_tool(self, name: str, args: Optional[dict] = None) -> str:
+        """Low-level: call any MCP tool by name. check_balance/pay_bill/etc below cover the
+        common ones with typed args."""
+        body = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {"name": name, "arguments": {"api_key": self.api_key, **(args or {})}},
+        }
+        data = _http_json(f"{self._base_url.rstrip('/')}/api/mcp", "POST", body=body)
+        if data.get("error"):
+            raise AbaPayError(data["error"].get("message") or "MCP tool call failed.", response=data)
+        content = (data.get("result") or {}).get("content") or []
+        text = next((c.get("text") for c in content if c.get("type") == "text"), None)
+        if text is None:
+            raise AbaPayError("MCP tool returned no text content.", response=data)
+        return text
+
+    def check_balance(self, chain: str = "CELO") -> str:
+        return self.call_tool("check_balance", {"chain": chain})
+
+    def pay_bill(
+        self,
+        pin: str,
+        service: str,
+        provider: str,
+        account_number: str,
+        amount_ngn: float,
+        chain: Optional[str] = None,
+        token: Optional[str] = None,
+        variation_code: Optional[str] = None,
+    ) -> str:
+        args: dict[str, Any] = {
+            "pin": pin,
+            "service": service,
+            "provider": provider,
+            "account_number": account_number,
+            "amount_ngn": amount_ngn,
+        }
+        if chain:
+            args["chain"] = chain
+        if token:
+            args["token"] = token
+        if variation_code:
+            args["variation_code"] = variation_code
+        return self.call_tool("pay_bill", args)
+
+    def schedule_bill(self, **args: Any) -> str:
+        return self.call_tool("schedule_bill", args)
+
+    def transaction_history(self, limit: Optional[int] = None, offset: Optional[int] = None) -> str:
+        args: dict[str, Any] = {}
+        if limit is not None:
+            args["limit"] = limit
+        if offset is not None:
+            args["offset"] = offset
+        return self.call_tool("transaction_history", args)
+
+
+def _personal_sign_message(message: str):
+    from eth_account.messages import encode_defunct
+
+    return encode_defunct(text=message)

abapay_sdk-0.1.0/src/abapay/cli.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""abapay-cli (Python) — pay real-world bills from a Celo wallet, no browser required.
+Mirrors sdk/src/cli.ts's abapay command-for-command; see that file's own header comment for
+why this exists as a thin argparse wrapper over the library, not a second implementation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .agent import AbaPayAgent
+from .types import AbaPayError, BillDetails, LinkParams
+from .x402 import pay_bill_via_x402
+
+
+def _fail(message: str) -> None:
+    print(f"abapay: {message}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _require_private_key() -> str:
+    pk = os.environ.get("PRIVATE_KEY")
+    if not pk:
+        _fail("PRIVATE_KEY env var is required (a 0x-prefixed hex private key).")
+    return pk  # type: ignore[return-value]
+
+
+def _account(pk: str):
+    from eth_account import Account
+
+    return Account.from_key(pk)
+
+
+def cmd_pay(args: argparse.Namespace) -> None:
+    account = _account(_require_private_key())
+    print(f"Paying as {account.address} — {args.service} {args.amount} NGN to {args.to}…")
+    bill = BillDetails(
+        serviceID=(args.provider or args.service).lower(),
+        serviceCategory=args.service,
+        network=args.network or (args.provider.upper() if args.provider else args.service),
+        billersCode=args.to,
+        nairaAmount=float(args.amount),
+        token=args.token,
+    )
+    try:
+        result = pay_bill_via_x402(account, bill)
+        print(f"✓ {result.status} — tx: {result.tx_hash or '(pending)'}")
+    except AbaPayError as e:
+        _fail(f"{e.message}" + (f"\n{e.response}" if e.response else ""))
+
+
+def cmd_link(args: argparse.Namespace) -> None:
+    account = _account(_require_private_key())
+    print(f"Linking {account.address}…")
+    try:
+        agent = AbaPayAgent.link(
+            LinkParams(signer=account, pin=args.pin, approved_chain=args.chain, approved_token=args.token, label=args.label or "abapay-cli-py")
+        )
+        print(f"✓ Linked. api_key: {agent.api_key}")
+        print("  This does NOT grant a spending allowance by itself — see agents.abapays.com/agents/developers/quickstart.")
+    except AbaPayError as e:
+        _fail(e.message)
+
+
+def cmd_balance(args: argparse.Namespace) -> None:
+    agent = AbaPayAgent.from_api_key(args.api_key, args.wallet or "")
+    try:
+        print(agent.check_balance(args.chain))
+    except AbaPayError as e:
+        _fail(e.message)
+
+
+def cmd_history(args: argparse.Namespace) -> None:
+    agent = AbaPayAgent.from_api_key(args.api_key, args.wallet or "")
+    try:
+        print(agent.transaction_history(limit=args.limit, offset=args.offset))
+    except AbaPayError as e:
+        _fail(e.message)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="abapay", description="Pay real-world bills from a Celo wallet.")
+    sub = parser.add_subparsers(dest="command")
+
+    p_pay = sub.add_parser("pay", help="Pay a bill via x402 — zero setup.")
+    p_pay.add_argument("--service", required=True)
+    p_pay.add_argument("--provider")
+    p_pay.add_argument("--to", required=True)
+    p_pay.add_argument("--amount", required=True)
+    p_pay.add_argument("--token", default="USDT")
+    p_pay.add_argument("--network")
+    p_pay.set_defaults(func=cmd_pay)
+
+    p_link = sub.add_parser("link", help="Link a wallet, mint an api_key.")
+    p_link.add_argument("--pin", required=True)
+    p_link.add_argument("--chain", default="CELO")
+    p_link.add_argument("--token")
+    p_link.add_argument("--label")
+    p_link.set_defaults(func=cmd_link)
+
+    p_bal = sub.add_parser("balance", help="Check a linked wallet's balance.")
+    p_bal.add_argument("--api-key", required=True)
+    p_bal.add_argument("--wallet")
+    p_bal.add_argument("--chain", default="CELO")
+    p_bal.set_defaults(func=cmd_balance)
+
+    p_hist = sub.add_parser("history", help="Recent transactions for a linked wallet.")
+    p_hist.add_argument("--api-key", required=True)
+    p_hist.add_argument("--wallet")
+    p_hist.add_argument("--limit", type=int)
+    p_hist.add_argument("--offset", type=int)
+    p_hist.set_defaults(func=cmd_history)
+
+    args = parser.parse_args()
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

abapay_sdk-0.1.0/src/abapay/types.py

@@ -0,0 +1,80 @@
+"""Shared types for the abapay Python SDK — mirrors sdk/src/types.ts field-for-field so the
+two SDKs can never silently drift on wire shape."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+class AbaPayError(Exception):
+    """Raised for any AbaPay-side failure — a bad request, a rejected signature, or a
+    settlement AbaPay itself reports as unsuccessful. Mirrors sdk/src/types.ts's AbaPayError."""
+
+    def __init__(self, message: str, cause: Optional[Exception] = None, response: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.cause = cause
+        self.response = response
+
+
+@dataclass
+class BillDetails:
+    """The same fields public/openapi.json's /api/pay/x402 requestBody documents.
+    Celo mainnet only — see the SDK's file-level comments in x402.py for why."""
+
+    serviceID: str
+    serviceCategory: str  # AIRTIME | DATA | ELECTRICITY | CABLE | EDUCATION | BANK
+    network: str
+    billersCode: str
+    nairaAmount: float
+    token: str  # "USDC" or "USDT"
+    wallet_address: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        d = {
+            "serviceID": self.serviceID,
+            "serviceCategory": self.serviceCategory,
+            "network": self.network,
+            "billersCode": self.billersCode,
+            "nairaAmount": self.nairaAmount,
+            "token": self.token,
+        }
+        if self.wallet_address:
+            d["wallet_address"] = self.wallet_address
+        return d
+
+
+@dataclass
+class X402PayResult:
+    success: bool
+    status: str  # "SUCCESS" | "FAILED_VENDING" | "TIMEOUT" | "SYSTEM_CRASH" | str
+    purchased_code: Optional[str] = None
+    units: Optional[str] = None
+    request_id: Optional[str] = None
+    tx_hash: Optional[str] = None
+    message: Optional[str] = None
+
+    @staticmethod
+    def from_dict(d: dict) -> "X402PayResult":
+        return X402PayResult(
+            success=bool(d.get("success", False)),
+            status=str(d.get("status", "")),
+            purchased_code=d.get("purchased_code"),
+            units=d.get("units"),
+            request_id=d.get("request_id"),
+            tx_hash=d.get("tx_hash"),
+            message=d.get("message"),
+        )
+
+
+@dataclass
+class LinkParams:
+    """Params for AbaPayAgent.link(). `signer` is any eth_account LocalAccount."""
+
+    signer: Any
+    pin: str
+    approved_chain: str = "CELO"
+    approved_token: Optional[str] = None
+    label: str = "abapay-sdk-py"
+    base_url: str = field(default="https://www.abapays.com")

abapay_sdk-0.1.0/src/abapay/x402.py

@@ -0,0 +1,159 @@
+"""Zero-setup x402 payments — mirrors sdk/src/x402.ts's payBillViaX402 field-for-field. The
+agent's own wallet signs an EIP-3009 transferWithAuthorization for exactly the amount AbaPay's
+server names in its 402 challenge; nothing here ever touches abapays.com, an Agent Hub
+account, or a PIN. Celo mainnet only in this version.
+
+Verify this against the real wire format any time: https://agents.abapays.com/x402
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+from eth_account.messages import encode_typed_data
+
+from .types import AbaPayError, BillDetails, X402PayResult
+
+DEFAULT_BASE_URL = "https://www.abapays.com"
+
+# ⚡ MUST MATCH src/lib/x402Settle.ts's TRANSFER_WITH_AUTHORIZATION_TYPES BYTE-FOR-BYTE (and
+# sdk/src/x402.ts's copy of the same) — that's the code that reconstructs this signature
+# server-side to verify it. Three independent copies now (TypeScript app, TypeScript SDK,
+# this one) because none of them can depend on each other across language/publish boundaries;
+# a drift in any one is a signature that silently fails to verify. Each carries this exact
+# comment as the tripwire.
+TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    "TransferWithAuthorization": [
+        {"name": "from", "type": "address"},
+        {"name": "to", "type": "address"},
+        {"name": "value", "type": "uint256"},
+        {"name": "validAfter", "type": "uint256"},
+        {"name": "validBefore", "type": "uint256"},
+        {"name": "nonce", "type": "bytes32"},
+    ],
+}
+
+
+def _random_nonce() -> str:
+    return "0x" + os.urandom(32).hex()
+
+
+def _caip2_chain_id(network: str) -> int:
+    parts = network.split(":")
+    if len(parts) != 2 or parts[0] != "eip155":
+        raise AbaPayError(
+            f'Unsupported x402 network "{network}" — this SDK version only understands '
+            "eip155:* (EVM) networks, and only Celo (eip155:42220) is currently offered by AbaPay."
+        )
+    try:
+        return int(parts[1])
+    except ValueError:
+        raise AbaPayError(f'Unsupported x402 network "{network}" — non-numeric chain id.')
+
+
+def _post_json(url: str, body: dict, extra_headers: Optional[dict] = None) -> tuple[int, dict]:
+    headers = {"Content-Type": "application/json"}
+    if extra_headers:
+        headers.update(extra_headers)
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req) as res:
+            raw = res.read().decode("utf-8")
+            return res.status, json.loads(raw)
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8")
+        try:
+            return e.code, json.loads(raw)
+        except json.JSONDecodeError:
+            raise AbaPayError(f"AbaPay returned a non-JSON response (HTTP {e.code}): {raw[:300]}")
+
+
+def pay_bill_via_x402(
+    signer: Any,
+    bill: BillDetails,
+    base_url: str = DEFAULT_BASE_URL,
+) -> X402PayResult:
+    """Pay a real-world bill (airtime, data, electricity, cable) via x402 — zero setup.
+
+    `signer` is any eth_account LocalAccount (e.g. from
+    `eth_account.Account.from_key(private_key)`). Its private key never leaves this process —
+    only `sign_message`/typed-data signing is used, matching the SDK's own no-custody design.
+
+    Raises AbaPayError on any HTTP failure, a challenge this version can't act on, or a final
+    response AbaPay itself reports as unsuccessful.
+    """
+    if bill.wallet_address is None:
+        bill = BillDetails(**{**bill.__dict__, "wallet_address": signer.address})
+    endpoint = f"{base_url.rstrip('/')}/api/pay/x402"
+
+    # ── 1. Ask for a price. No X-PAYMENT header yet — this MUST come back 402. ──────────────
+    status, challenge = _post_json(endpoint, bill.to_dict())
+    if status != 402:
+        raise AbaPayError(f"Expected HTTP 402 (payment required), got {status}.", response=challenge)
+
+    accepts = challenge.get("accepts") or []
+    accept = next((a for a in accepts if a.get("scheme") == "exact"), None)
+    if accept is None:
+        raise AbaPayError("402 challenge carried no usable 'exact' payment option.", response=challenge)
+
+    # ── 2. Sign the exact amount the challenge named, with the wallet's OWN key. ─────────────
+    chain_id = _caip2_chain_id(accept["network"])
+    now = int(time.time())
+    authorization = {
+        "from": signer.address,
+        "to": accept["payTo"],
+        "value": int(accept["amount"]),
+        # 60s of slack behind "now" absorbs ordinary clock skew.
+        "validAfter": now - 60,
+        "validBefore": now + int(accept.get("maxTimeoutSeconds") or 3600),
+        "nonce": _random_nonce(),
+    }
+
+    domain = {
+        "name": accept["extra"]["name"],
+        "version": accept["extra"]["version"],
+        "chainId": chain_id,
+        "verifyingContract": accept["asset"],
+    }
+    signable = encode_typed_data(
+        domain_data=domain,
+        message_types=TRANSFER_WITH_AUTHORIZATION_TYPES,
+        message_data=authorization,
+    )
+    signed = signer.sign_message(signable)
+    signature = signed.signature.hex()
+    if not signature.startswith("0x"):
+        signature = "0x" + signature
+
+    # ── 3. Retry with the signed authorization attached. ─────────────────────────────────────
+    payment_header = base64.b64encode(
+        json.dumps(
+            {
+                "x402Version": 1,
+                "scheme": "exact",
+                "network": "celo",
+                "payload": {
+                    "signature": signature,
+                    "authorization": {
+                        **authorization,
+                        "value": str(authorization["value"]),
+                        "validAfter": str(authorization["validAfter"]),
+                        "validBefore": str(authorization["validBefore"]),
+                    },
+                },
+            }
+        ).encode("utf-8")
+    ).decode("ascii")
+
+    settle_status, result = _post_json(endpoint, bill.to_dict(), {"X-PAYMENT": payment_header})
+    parsed = X402PayResult.from_dict(result)
+    if settle_status >= 300 or parsed.success is False:
+        raise AbaPayError(parsed.message or f"Settlement failed (HTTP {settle_status}).", response=result)
+    return parsed

abapay_sdk-0.1.0/tests/test_agent.py

@@ -0,0 +1,79 @@
+import json
+
+from eth_account import Account
+from eth_account.messages import encode_defunct
+
+from abapay.agent import AbaPayAgent
+from abapay.types import AbaPayError, LinkParams
+
+TEST_PRIVATE_KEY = "0x" + "22" * 32
+
+
+def test_link_signs_and_returns_agent(httpserver):
+    account = Account.from_key(TEST_PRIVATE_KEY)
+    captured = {}
+
+    def handler(request):
+        from werkzeug.wrappers import Response
+
+        captured["body"] = json.loads(request.data)
+        captured["headers"] = dict(request.headers)
+        return Response(json.dumps({"success": True, "api_key": "aba_mcp_test123"}), status=200, content_type="application/json")
+
+    httpserver.expect_request("/api/agent/link", method="POST").respond_with_handler(handler)
+
+    agent = AbaPayAgent.link(LinkParams(signer=account, pin="1234", base_url=httpserver.url_for("")))
+
+    assert agent.api_key == "aba_mcp_test123"
+    assert agent.wallet_address == account.address
+    assert captured["body"]["pin"] == "1234"
+    assert captured["body"]["wallet_address"] == account.address
+
+    # The signature really does verify against the message it claims to sign.
+    timestamp = captured["headers"]["X-Wallet-Timestamp"]
+    message = encode_defunct(text=f"AbaPay Agent Action: POST:/api/agent/link: {timestamp}")
+    recovered = Account.recover_message(message, signature=captured["headers"]["X-Wallet-Signature"])
+    assert recovered.lower() == account.address.lower()
+
+
+def test_link_rejects_malformed_pin():
+    account = Account.from_key(TEST_PRIVATE_KEY)
+    try:
+        AbaPayAgent.link(LinkParams(signer=account, pin="12"))
+        assert False, "expected AbaPayError"
+    except AbaPayError as e:
+        assert "4-6 digits" in e.message
+
+
+def test_call_tool_round_trips(httpserver):
+    def handler(request):
+        from werkzeug.wrappers import Response
+
+        body = json.loads(request.data)
+        assert body["method"] == "tools/call"
+        assert body["params"]["name"] == "check_balance"
+        assert body["params"]["arguments"]["api_key"] == "aba_mcp_test123"
+        return Response(
+            json.dumps({"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "USDT 1.88"}]}}),
+            status=200,
+            content_type="application/json",
+        )
+
+    httpserver.expect_request("/api/mcp", method="POST").respond_with_handler(handler)
+
+    agent = AbaPayAgent.from_api_key("aba_mcp_test123", "0xabc", base_url=httpserver.url_for(""))
+    text = agent.check_balance("CELO")
+    assert text == "USDT 1.88"
+
+
+def test_call_tool_raises_on_jsonrpc_error(httpserver):
+    httpserver.expect_request("/api/mcp", method="POST").respond_with_json(
+        {"jsonrpc": "2.0", "id": 1, "error": {"message": "Invalid or revoked API key."}}
+    )
+
+    agent = AbaPayAgent.from_api_key("aba_mcp_bad", "0xabc", base_url=httpserver.url_for(""))
+    try:
+        agent.check_balance()
+        assert False, "expected AbaPayError"
+    except AbaPayError as e:
+        assert "Invalid or revoked" in e.message

abapay_sdk-0.1.0/tests/test_x402.py

@@ -0,0 +1,129 @@
+"""Correctness, not just "it runs": asserts the signed typed-data this SDK produces recovers
+to the signer's own address — the same guarantee sdk/test/x402.test.ts makes for the
+TypeScript SDK ("a test asserts the signed typed-data's domain and message match a real 402
+challenge byte-for-byte"). Runs against a real local HTTP server (pytest-httpserver), not a
+patched urlopen, so the request/response shapes on the wire are exercised for real.
+"""
+
+import json
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+from abapay.types import BillDetails
+from abapay.x402 import TRANSFER_WITH_AUTHORIZATION_TYPES, pay_bill_via_x402
+
+TEST_PRIVATE_KEY = "0x" + "11" * 32  # deterministic, test-only — never a real funded key
+VAULT = "0x5df8aE2B963165b735B18Ca86B1ea448d2AA032C"
+USDT = "0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e"
+
+CHALLENGE = {
+    "x402Version": 1,
+    "error": "Payment required",
+    "accepts": [
+        {
+            "scheme": "exact",
+            "network": "eip155:42220",
+            "amount": "1492500",
+            "maxAmountRequired": "1492500",
+            "payTo": VAULT,
+            "asset": USDT,
+            "maxTimeoutSeconds": 86400,
+            "extra": {"name": "Tether USD", "version": "1", "primaryType": "TransferWithAuthorization"},
+        }
+    ],
+}
+
+
+def test_signature_recovers_to_signer_address(httpserver):
+    account = Account.from_key(TEST_PRIVATE_KEY)
+
+    captured = {}
+
+    def handler(request):
+        from werkzeug.wrappers import Response
+
+        payment_header = request.headers.get("X-PAYMENT")
+        if payment_header is None:
+            return Response(json.dumps(CHALLENGE), status=402, content_type="application/json")
+
+        captured["payment_header"] = payment_header
+        return Response(
+            json.dumps({"success": True, "status": "SUCCESS", "tx_hash": "0xdeadbeef", "request_id": "req_test"}),
+            status=200,
+            content_type="application/json",
+        )
+
+    httpserver.expect_request("/api/pay/x402", method="POST").respond_with_handler(handler)
+
+    bill = BillDetails(
+        serviceID="mtn",
+        serviceCategory="AIRTIME",
+        network="MTN",
+        billersCode="08012345678",
+        nairaAmount=1000,
+        token="USDT",
+    )
+    result = pay_bill_via_x402(account, bill, base_url=httpserver.url_for(""))
+
+    assert result.success is True
+    assert result.status == "SUCCESS"
+    assert result.tx_hash == "0xdeadbeef"
+    assert "payment_header" in captured
+
+    # ── The actual correctness check: recover the signer from the signed typed data and
+    # confirm it's the account that supposedly signed it — exactly the check AbaPay's own
+    # server-side verification (src/lib/x402Settle.ts) performs to accept or reject a payment.
+    import base64
+
+    decoded = json.loads(base64.b64decode(captured["payment_header"]))
+    auth = decoded["payload"]["authorization"]
+    signature = decoded["payload"]["signature"]
+
+    domain = {
+        "name": "Tether USD",
+        "version": "1",
+        "chainId": 42220,
+        "verifyingContract": USDT,
+    }
+    message = {
+        "from": auth["from"],
+        "to": auth["to"],
+        "value": int(auth["value"]),
+        "validAfter": int(auth["validAfter"]),
+        "validBefore": int(auth["validBefore"]),
+        "nonce": auth["nonce"],
+    }
+    signable = encode_typed_data(domain_data=domain, message_types=TRANSFER_WITH_AUTHORIZATION_TYPES, message_data=message)
+    recovered = Account.recover_message(signable, signature=signature)
+
+    assert recovered.lower() == account.address.lower()
+    assert auth["from"].lower() == account.address.lower()
+    assert auth["to"].lower() == VAULT.lower()
+    assert auth["value"] == "1492500"
+
+
+def test_non_402_first_response_raises(httpserver):
+    from abapay.types import AbaPayError
+
+    httpserver.expect_request("/api/pay/x402", method="POST").respond_with_json({"error": "bad request"}, status=400)
+
+    account = Account.from_key(TEST_PRIVATE_KEY)
+    bill = BillDetails(serviceID="mtn", serviceCategory="AIRTIME", network="MTN", billersCode="08012345678", nairaAmount=1000, token="USDT")
+
+    try:
+        pay_bill_via_x402(account, bill, base_url=httpserver.url_for(""))
+        assert False, "expected AbaPayError"
+    except AbaPayError as e:
+        assert "402" in e.message
+
+
+def test_unsupported_network_raises():
+    from abapay.types import AbaPayError
+    from abapay.x402 import _caip2_chain_id
+
+    try:
+        _caip2_chain_id("solana:mainnet")
+        assert False, "expected AbaPayError"
+    except AbaPayError as e:
+        assert "eip155" in e.message