pay-skill 0.1.2__tar.gz

pay_skill-0.1.2/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+
+# TypeScript
+node_modules/
+typescript/dist/
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

pay_skill-0.1.2/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: pay-skill
+Version: 0.1.2
+Summary: Python SDK for pay — payment infrastructure for AI agents
+Project-URL: Homepage, https://pay-skill.com
+Project-URL: Repository, https://github.com/pay-skill/pay-sdk
+Author-email: "pay-skill.com" <hello@pay-skill.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: ows
+Requires-Dist: open-wallet-standard>=1.2; extra == 'ows'
+Description-Content-Type: text/markdown
+
+# pay-sdk
+
+Python SDK for [pay](https://pay-skill.com) — payment infrastructure for AI agents. USDC on Base.
+
+Three primitives: direct payments, tabs (pre-funded metered accounts), and x402 HTTP paywalls.
+
+## Install
+
+```bash
+pip install pay-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from payskill import PayClient
+
+client = PayClient(signer="cli")  # uses `pay sign` subprocess
+
+# Pay another agent $5
+result = client.pay_direct("0xprovider...", 5_000_000, memo="task-42")
+print(result.tx_hash)
+
+# Open a metered tab
+tab = client.open_tab("0xprovider...", 20_000_000, max_charge_per_call=500_000)
+
+# x402 request (SDK handles payment automatically)
+response = client.request("https://api.example.com/data")
+```
+
+All amounts are in USDC micro-units (6 decimals). `$1.00 = 1_000_000`.
+
+## API Reference
+
+### PayClient
+
+```python
+from payskill import PayClient
+
+client = PayClient(
+    api_url="https://pay-skill.com/api/v1",  # default
+    signer="cli",  # "cli", "raw", "custom", or a Signer instance
+)
+```
+
+### Direct Payment
+
+One-shot USDC transfer. $1.00 minimum.
+
+```python
+result = client.pay_direct(to, amount, memo="")
+# Returns: DirectPaymentResult(tx_hash, status, amount, fee)
+```
+
+### Tab Management
+
+Pre-funded metered account. $5.00 minimum to open.
+
+```python
+# Open
+tab = client.open_tab(provider, amount, max_charge_per_call)
+
+# Query
+tabs = client.list_tabs()
+tab = client.get_tab(tab_id)
+
+# Top up (no extra activation fee)
+tab = client.top_up_tab(tab_id, amount)
+
+# Close (either party, unilateral)
+tab = client.close_tab(tab_id)
+```
+
+Returns `Tab(tab_id, provider, amount, balance_remaining, total_charged, charge_count, max_charge_per_call, status)`.
+
+### x402 Requests
+
+Transparent HTTP 402 handling. The SDK detects `402 Payment Required`, pays (via direct or tab), and retries.
+
+```python
+response = client.request(url, method="GET", body=None, headers=None)
+# Returns: httpx.Response
+```
+
+If the provider requires tab settlement, the SDK auto-opens a tab at 10x the per-call price (minimum $5).
+
+### Wallet
+
+```python
+status = client.get_status()
+# Returns: StatusResponse(address, balance, open_tabs)
+```
+
+### Webhooks
+
+```python
+wh = client.register_webhook(url, events=["tab.opened"], secret="whsec_...")
+webhooks = client.list_webhooks()
+client.delete_webhook(webhook_id)
+```
+
+### Funding
+
+```python
+link = client.create_fund_link(amount=10_000_000)   # Coinbase Onramp
+link = client.create_withdraw_link(amount=5_000_000)
+```
+
+## Signer Modes
+
+| Mode | Usage | When |
+|------|-------|------|
+| `"cli"` | Subprocess call to `pay sign` | Default. Key in OS keychain. |
+| `"raw"` | `PAYSKILL_KEY` env var | Dev/testing only. |
+| `"custom"` | Your own callback | Custom key management. |
+
+```python
+# CLI signer (default)
+client = PayClient(signer="cli")
+
+# Raw key (dev only)
+client = PayClient(signer="raw", key="0xdead...")
+
+# Custom callback
+from payskill.signer import CallbackSigner
+signer = CallbackSigner(callback=lambda hash_bytes: my_sign(hash_bytes))
+client = PayClient(signer=signer)
+```
+
+## Error Handling
+
+```python
+from payskill.errors import (
+    PayError,                  # Base class
+    PayValidationError,        # Bad input (has .field)
+    PayNetworkError,           # Connection failed
+    PayServerError,            # Server returned error (has .status_code)
+    PayInsufficientFundsError, # Not enough USDC
+)
+```
+
+## Configuration
+
+| Env Var | Purpose |
+|---------|---------|
+| `PAYSKILL_KEY` | Private key for raw signer mode |
+
+The API URL is configurable via the `api_url` parameter. Default: `https://pay-skill.com/api/v1`.
+
+## License
+
+MIT

pay_skill-0.1.2/README.md

@@ -0,0 +1,154 @@
+# pay-sdk
+
+Python SDK for [pay](https://pay-skill.com) — payment infrastructure for AI agents. USDC on Base.
+
+Three primitives: direct payments, tabs (pre-funded metered accounts), and x402 HTTP paywalls.
+
+## Install
+
+```bash
+pip install pay-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from payskill import PayClient
+
+client = PayClient(signer="cli")  # uses `pay sign` subprocess
+
+# Pay another agent $5
+result = client.pay_direct("0xprovider...", 5_000_000, memo="task-42")
+print(result.tx_hash)
+
+# Open a metered tab
+tab = client.open_tab("0xprovider...", 20_000_000, max_charge_per_call=500_000)
+
+# x402 request (SDK handles payment automatically)
+response = client.request("https://api.example.com/data")
+```
+
+All amounts are in USDC micro-units (6 decimals). `$1.00 = 1_000_000`.
+
+## API Reference
+
+### PayClient
+
+```python
+from payskill import PayClient
+
+client = PayClient(
+    api_url="https://pay-skill.com/api/v1",  # default
+    signer="cli",  # "cli", "raw", "custom", or a Signer instance
+)
+```
+
+### Direct Payment
+
+One-shot USDC transfer. $1.00 minimum.
+
+```python
+result = client.pay_direct(to, amount, memo="")
+# Returns: DirectPaymentResult(tx_hash, status, amount, fee)
+```
+
+### Tab Management
+
+Pre-funded metered account. $5.00 minimum to open.
+
+```python
+# Open
+tab = client.open_tab(provider, amount, max_charge_per_call)
+
+# Query
+tabs = client.list_tabs()
+tab = client.get_tab(tab_id)
+
+# Top up (no extra activation fee)
+tab = client.top_up_tab(tab_id, amount)
+
+# Close (either party, unilateral)
+tab = client.close_tab(tab_id)
+```
+
+Returns `Tab(tab_id, provider, amount, balance_remaining, total_charged, charge_count, max_charge_per_call, status)`.
+
+### x402 Requests
+
+Transparent HTTP 402 handling. The SDK detects `402 Payment Required`, pays (via direct or tab), and retries.
+
+```python
+response = client.request(url, method="GET", body=None, headers=None)
+# Returns: httpx.Response
+```
+
+If the provider requires tab settlement, the SDK auto-opens a tab at 10x the per-call price (minimum $5).
+
+### Wallet
+
+```python
+status = client.get_status()
+# Returns: StatusResponse(address, balance, open_tabs)
+```
+
+### Webhooks
+
+```python
+wh = client.register_webhook(url, events=["tab.opened"], secret="whsec_...")
+webhooks = client.list_webhooks()
+client.delete_webhook(webhook_id)
+```
+
+### Funding
+
+```python
+link = client.create_fund_link(amount=10_000_000)   # Coinbase Onramp
+link = client.create_withdraw_link(amount=5_000_000)
+```
+
+## Signer Modes
+
+| Mode | Usage | When |
+|------|-------|------|
+| `"cli"` | Subprocess call to `pay sign` | Default. Key in OS keychain. |
+| `"raw"` | `PAYSKILL_KEY` env var | Dev/testing only. |
+| `"custom"` | Your own callback | Custom key management. |
+
+```python
+# CLI signer (default)
+client = PayClient(signer="cli")
+
+# Raw key (dev only)
+client = PayClient(signer="raw", key="0xdead...")
+
+# Custom callback
+from payskill.signer import CallbackSigner
+signer = CallbackSigner(callback=lambda hash_bytes: my_sign(hash_bytes))
+client = PayClient(signer=signer)
+```
+
+## Error Handling
+
+```python
+from payskill.errors import (
+    PayError,                  # Base class
+    PayValidationError,        # Bad input (has .field)
+    PayNetworkError,           # Connection failed
+    PayServerError,            # Server returned error (has .status_code)
+    PayInsufficientFundsError, # Not enough USDC
+)
+```
+
+## Configuration
+
+| Env Var | Purpose |
+|---------|---------|
+| `PAYSKILL_KEY` | Private key for raw signer mode |
+
+The API URL is configurable via the `api_url` parameter. Default: `https://pay-skill.com/api/v1`.
+
+## License
+
+MIT

pay_skill-0.1.2/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pay-skill"
+version = "0.1.2"
+description = "Python SDK for pay — payment infrastructure for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{name = "pay-skill.com", email = "hello@pay-skill.com"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial",
+]
+
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "eth-account>=0.11",
+]
+
+[project.urls]
+Homepage = "https://pay-skill.com"
+Repository = "https://github.com/pay-skill/pay-sdk"
+
+[project.optional-dependencies]
+ows = [
+    "open-wallet-standard>=1.2",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "pytest-timeout>=2.3",
+    "pytest-httpx>=0.30",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/payskill"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "B", "S"]
+ignore = ["S101", "S603"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+warn_unused_ignores = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "e2e: end-to-end tests against live testnet (requires PAYSKILL_TESTNET_KEY)",
+]

pay_skill-0.1.2/src/payskill/__init__.py

@@ -0,0 +1,30 @@
+"""pay SDK — payment infrastructure for AI agents."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from payskill.auth import build_auth_headers, derive_address
+from payskill.client import PayClient
+from payskill.errors import PayError, PayNetworkError, PayValidationError
+from payskill.models import DirectPaymentResult, Tab, TabStatus
+
+# OWS signer is optional — only available if open-wallet-standard is installed.
+OwsSigner: Any
+try:
+    from payskill.ows_signer import OwsSigner
+except ImportError:
+    OwsSigner = None
+
+__all__ = [
+    "PayClient",
+    "PayError",
+    "PayNetworkError",
+    "PayValidationError",
+    "DirectPaymentResult",
+    "Tab",
+    "TabStatus",
+    "build_auth_headers",
+    "derive_address",
+    "OwsSigner",
+]

pay_skill-0.1.2/src/payskill/auth.py

@@ -0,0 +1,101 @@
+"""EIP-712 authentication for pay API requests.
+
+Every authenticated request includes four headers:
+  X-Pay-Agent     — wallet address (0x-prefixed, checksummed)
+  X-Pay-Signature — EIP-712 signature (0x-prefixed hex, 65 bytes)
+  X-Pay-Timestamp — unix timestamp in seconds
+  X-Pay-Nonce     — random 32-byte hex (0x-prefixed)
+
+The EIP-712 domain:
+  name: "pay"
+  version: "0.1"
+  chainId: <from config>
+  verifyingContract: <router address>
+
+The typed data:
+  APIRequest(string method, string path, uint256 timestamp, bytes32 nonce)
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+
+def build_auth_headers(
+    private_key: str,
+    method: str,
+    path: str,
+    chain_id: int,
+    router_address: str,
+) -> dict[str, str]:
+    """Build X-Pay-* auth headers for an API request.
+
+    Args:
+        private_key: Hex-encoded private key (with or without 0x prefix).
+        method: HTTP method (GET, POST, DELETE, etc.).
+        path: Request path (e.g., /api/v1/direct).
+        chain_id: Chain ID for EIP-712 domain.
+        router_address: Router contract address for EIP-712 domain.
+
+    Returns:
+        Dict with X-Pay-Agent, X-Pay-Signature, X-Pay-Timestamp, X-Pay-Nonce.
+    """
+    account = Account.from_key(private_key)
+    timestamp = int(time.time())
+    nonce = "0x" + os.urandom(32).hex()
+
+    domain_data = {
+        "name": "pay",
+        "version": "0.1",
+        "chainId": chain_id,
+        "verifyingContract": router_address,
+    }
+
+    message_types = {
+        "APIRequest": [
+            {"name": "method", "type": "string"},
+            {"name": "path", "type": "string"},
+            {"name": "timestamp", "type": "uint256"},
+            {"name": "nonce", "type": "bytes32"},
+        ],
+    }
+
+    message_data = {
+        "method": method.upper(),
+        "path": path,
+        "timestamp": timestamp,
+        "nonce": bytes.fromhex(nonce[2:]),
+    }
+
+    signable = encode_typed_data(
+        domain_data,
+        message_types,
+        message_data,
+    )
+    signed = account.sign_message(signable)
+
+    return {
+        "X-Pay-Agent": account.address,
+        "X-Pay-Signature": signed.signature.hex()
+        if isinstance(signed.signature, bytes)
+        else hex(signed.signature),
+        "X-Pay-Timestamp": str(timestamp),
+        "X-Pay-Nonce": nonce,
+    }
+
+
+def derive_address(private_key: str) -> str:
+    """Derive an Ethereum address from a private key.
+
+    Args:
+        private_key: Hex-encoded private key (with or without 0x prefix).
+
+    Returns:
+        Checksummed Ethereum address.
+    """
+    account = Account.from_key(private_key)
+    return str(account.address)