apay 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- apay-0.1.0/.gitignore +28 -0
- apay-0.1.0/ARCHITECTURE.md +95 -0
- apay-0.1.0/PKG-INFO +119 -0
- apay-0.1.0/README.md +89 -0
- apay-0.1.0/pyproject.toml +90 -0
- apay-0.1.0/spec/HTTP_402_SPEC.md +67 -0
- apay-0.1.0/spec/SECURITY_MODEL.md +35 -0
- apay-0.1.0/src/apay/__init__.py +44 -0
- apay-0.1.0/src/apay/cli.py +216 -0
- apay-0.1.0/src/apay/client.py +146 -0
- apay-0.1.0/src/apay/integrations/__init__.py +15 -0
- apay-0.1.0/src/apay/integrations/crewai.py +92 -0
- apay-0.1.0/src/apay/integrations/langchain.py +137 -0
- apay-0.1.0/src/apay/proxy.py +258 -0
- apay-0.1.0/src/apay/relayer.py +215 -0
- apay-0.1.0/src/apay/wallet.py +136 -0
apay-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Virtual Environment
|
|
2
|
+
.venv/
|
|
3
|
+
env/
|
|
4
|
+
venv/
|
|
5
|
+
|
|
6
|
+
# Python cache & artifacts
|
|
7
|
+
__pycache__/
|
|
8
|
+
*.pyc
|
|
9
|
+
*.pyo
|
|
10
|
+
*.pyd
|
|
11
|
+
.pytest_cache/
|
|
12
|
+
.coverage
|
|
13
|
+
htmlcov/
|
|
14
|
+
dist/
|
|
15
|
+
build/
|
|
16
|
+
*.egg-info/
|
|
17
|
+
|
|
18
|
+
# Node & Next.js
|
|
19
|
+
node_modules/
|
|
20
|
+
.next/
|
|
21
|
+
out/
|
|
22
|
+
|
|
23
|
+
# IDE & OS
|
|
24
|
+
.DS_Store
|
|
25
|
+
*.swp
|
|
26
|
+
*.swo
|
|
27
|
+
.vscode/
|
|
28
|
+
.idea/
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# 🏛️ A-Pay Architecture Deep-Dive
|
|
2
|
+
|
|
3
|
+
## 1. System Philosophy: "Ultra-Light & Zero Friction"
|
|
4
|
+
For an autonomous AI agent running inside an ephemeral docker container or serverless environment, standard Web3 dependencies (like heavy `ethers.js` bundles or 500MB node_modules) are non-starters.
|
|
5
|
+
|
|
6
|
+
A-Pay enforces:
|
|
7
|
+
1. **Zero Bloat**:
|
|
8
|
+
- Gateway middleware footprint < 20KB.
|
|
9
|
+
- Python client runtime footprint < 5MB (using Rust-based `pydantic-core` & `httpx`).
|
|
10
|
+
2. **Deterministic Latency**:
|
|
11
|
+
- Verification of payment authorization within **< 25ms**.
|
|
12
|
+
- No waiting for block confirmations during the live HTTP request/response cycle.
|
|
13
|
+
3. **Decentralized Custody**:
|
|
14
|
+
- Agents never hand over private keys to a third-party server. Keys remain in memory / hardware enclave with pre-signed spending limits (Session Keys).
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 2. Component Breakdown
|
|
19
|
+
|
|
20
|
+
### A. Client SDK (`src/apay` - PyPI: `apay`)
|
|
21
|
+
- **Wallet Abstraction**: Generates or imports an EVM/Solana keypair into an ephemeral session.
|
|
22
|
+
- **Budget Guardrails**: Enforces client-side invariants (e.g. `max_total_spend`, `max_spend_per_hour`, `allowed_domains`).
|
|
23
|
+
- **402 Interceptor**: Intercepts `402 Payment Required` responses, inspects price and payment terms, automatically signs the EIP-712 payment authorization, attaches the `Authorization: APay <signature>` header, and retries the request transparently.
|
|
24
|
+
|
|
25
|
+
### B. Gateway Middleware (`gateway-ts` / `gateway-py`)
|
|
26
|
+
- Sits in front of any standard API route (Hono, Express, FastAPI, Next.js).
|
|
27
|
+
- Intercepts incoming requests:
|
|
28
|
+
- If valid `APay` signature is present: Verifies signature off-chain in <10ms, checks nonce to prevent replay attacks, decrements the agent's available credit, and forwards the request to the upstream API handler.
|
|
29
|
+
- If missing/invalid: Emits HTTP 402 with structured payment metadata.
|
|
30
|
+
|
|
31
|
+
### C. Smart Contract Settlement Layer (`contracts/`)
|
|
32
|
+
- **`APayRouter.sol`**:
|
|
33
|
+
- Accepts batches of signed payment claims from API Providers.
|
|
34
|
+
- Executes atomical transfer of USDC:
|
|
35
|
+
- 99.0% -> Service Provider Wallet.
|
|
36
|
+
- 1.0% -> A-Pay Protocol Treasury Wallet.
|
|
37
|
+
- Emits `SettlementEvent` for indexing.
|
|
38
|
+
- **`EscrowVault.sol`**:
|
|
39
|
+
- Allows AI operators to deposit a master balance and delegate limited "Session Keys" to their agents without risking the master funds.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 3. The HTTP 402 Protocol Flow
|
|
44
|
+
|
|
45
|
+
```http
|
|
46
|
+
[1. AI Agent -> Server]
|
|
47
|
+
GET /v1/data/extract?url=https://example.com
|
|
48
|
+
Host: api.dataprovider.com
|
|
49
|
+
User-Agent: APay-Agent/1.0.0
|
|
50
|
+
|
|
51
|
+
[2. Server -> AI Agent]
|
|
52
|
+
HTTP/1.1 402 Payment Required
|
|
53
|
+
Content-Type: application/json
|
|
54
|
+
X-APay-Version: 1.0
|
|
55
|
+
X-APay-Receiver: 0x9876...CDEF
|
|
56
|
+
X-APay-Amount: 1000 (0.001 USDC - 6 decimals)
|
|
57
|
+
X-APay-Currency: USDC
|
|
58
|
+
X-APay-Network: base
|
|
59
|
+
X-APay-Nonce: f89a421b-4158-4bc2
|
|
60
|
+
|
|
61
|
+
{
|
|
62
|
+
"status": 402,
|
|
63
|
+
"message": "Micropayment required to access this endpoint",
|
|
64
|
+
"pricing": {
|
|
65
|
+
"amount": "0.001",
|
|
66
|
+
"currency": "USDC",
|
|
67
|
+
"network": "base",
|
|
68
|
+
"receiver": "0x9876...CDEF"
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
[3. AI Agent -> Server (Re-request with signed cryptographic authorization)]
|
|
73
|
+
GET /v1/data/extract?url=https://example.com
|
|
74
|
+
Host: api.dataprovider.com
|
|
75
|
+
User-Agent: APay-Agent/1.0.0
|
|
76
|
+
Authorization: APay eip712:<signature>:<payer_address>:<nonce>:<amount>
|
|
77
|
+
|
|
78
|
+
[4. Server -> AI Agent]
|
|
79
|
+
HTTP/1.1 200 OK
|
|
80
|
+
Content-Type: application/json
|
|
81
|
+
X-APay-Settled: true
|
|
82
|
+
|
|
83
|
+
{
|
|
84
|
+
"success": true,
|
|
85
|
+
"data": { ... }
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 4. Why Base (EVM L2) as the Primary Rail?
|
|
92
|
+
- **Cost**: < $0.0005 average gas fee per transfer.
|
|
93
|
+
- **Finality**: 200ms block intervals (OP Stack).
|
|
94
|
+
- **USDC Liquidity**: Native Circle deployment (not bridged).
|
|
95
|
+
- **Coinbase Ecosystem Alignment**: Ready interoperability with existing developer tools and agentic wallets.
|
apay-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: apay
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Universal HTTP 402 Micropayment Protocol & CLI for Autonomous AI Agents
|
|
5
|
+
Project-URL: Homepage, https://apay-network.vercel.app
|
|
6
|
+
Project-URL: Documentation, https://apay-network.vercel.app
|
|
7
|
+
Project-URL: Repository, https://github.com/a-pay/apay
|
|
8
|
+
Author-email: A-Pay Protocol Core Swarm <core@apay.network>
|
|
9
|
+
License: MIT
|
|
10
|
+
Keywords: ai-agents,autonomous-agents,base-l2,http-402,m2m-economy,micropayments,paywall,usdc
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
20
|
+
Classifier: Topic :: Security :: Cryptography
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: click>=8.1.0
|
|
24
|
+
Requires-Dist: eth-account>=0.11.0
|
|
25
|
+
Requires-Dist: httpx>=0.27.0
|
|
26
|
+
Requires-Dist: pydantic>=2.7.0
|
|
27
|
+
Requires-Dist: starlette>=0.38.0
|
|
28
|
+
Requires-Dist: uvicorn>=0.30.0
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# ⚡ A-Pay Protocol (AgentPay)
|
|
32
|
+
> **The Universal Micropayment & Economic Layer for Autonomous AI Agents**
|
|
33
|
+
|
|
34
|
+
[](https://www.python.org/)
|
|
35
|
+
[]()
|
|
36
|
+
[]()
|
|
37
|
+
[](https://apay-network.vercel.app)
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 🎯 Vision & Identity
|
|
42
|
+
**A-Pay** is an ultra-lightweight, zero-latency, open economic rail designed for the machine-to-machine (M2M) economy. Just as UPI revolutionized human digital payments in India, A-Pay enables autonomous AI software agents to discover, consume, and pay for data, compute, APIs, and micro-services on the fly—without credit cards, human KYC, or seed phrase friction.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 🚀 1-Command Experience
|
|
47
|
+
|
|
48
|
+
### 1. Website / API Owners (The Sellers)
|
|
49
|
+
Protect ANY existing website or API with an instant HTTP 402 crypto paywall—**zero code modifications required**:
|
|
50
|
+
```bash
|
|
51
|
+
apay protect --target http://localhost:8000 --price 0.001 --wallet 0xYourWalletAddress
|
|
52
|
+
```
|
|
53
|
+
* Incoming requests from AI bots will automatically receive an **HTTP 402 Payment Required** challenge.
|
|
54
|
+
* Once the AI agent's cryptographic micropayment is verified (<15ms), the request is forwarded to your server and data is unlocked!
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
### 2. AI Agent Developers (The Buyers)
|
|
59
|
+
Give your AI agent an in-memory wallet and strict spending guardrails with **2 lines of code**:
|
|
60
|
+
```python
|
|
61
|
+
from apay import APaySession, AgentWallet
|
|
62
|
+
|
|
63
|
+
# Generate or load wallet with daily safety limit
|
|
64
|
+
wallet = AgentWallet(private_key="0x...", max_per_call_usdc=0.01, daily_budget_usdc=5.0)
|
|
65
|
+
session = APaySession(wallet)
|
|
66
|
+
|
|
67
|
+
# Automatically handles HTTP 402 challenges & settles on the fly
|
|
68
|
+
response = session.get("https://protected-api.com/market-data")
|
|
69
|
+
print(response.json())
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 📦 Directory Structure
|
|
75
|
+
|
|
76
|
+
```text
|
|
77
|
+
/home/sagar/a_pay/
|
|
78
|
+
├── .aum_identity.md # AUM Project Core Identity binding
|
|
79
|
+
├── RULEBOOK.md # 📜 Master Rulebook: M2M Core, H2B Checkout & $APAY Token
|
|
80
|
+
├── neural_ais/ # Symlink to /home/sagar/neural_core
|
|
81
|
+
├── pyproject.toml # Hatchling & uv build system (CLI entrypoint: `apay`)
|
|
82
|
+
├── src/
|
|
83
|
+
│ └── apay/
|
|
84
|
+
│ ├── __init__.py # Package exports
|
|
85
|
+
│ ├── cli.py # ⚡ 1-Command CLI (`apay protect`, `apay wallet new`, `apay pay`)
|
|
86
|
+
│ ├── client.py # 🤖 Auto-settling HTTP client (sync & async)
|
|
87
|
+
│ ├── wallet.py # 🔐 In-memory wallet + local spending limits
|
|
88
|
+
│ └── proxy.py # 🛡️ Ultra-light reverse proxy paywall (Starlette + viem/eth)
|
|
89
|
+
├── contracts/
|
|
90
|
+
│ └── src/
|
|
91
|
+
│ └── APayRouter.sol# Solidity ^0.8.28 Smart Contract Router (1% protocol fee)
|
|
92
|
+
├── tests/
|
|
93
|
+
│ └── test_flow.py # Automated integration & guardrail test suite
|
|
94
|
+
├── spec/
|
|
95
|
+
│ ├── HTTP_402_SPEC.md # Official RFC wire format
|
|
96
|
+
│ └── SECURITY_MODEL.md # Anti-replay & infinite-loop drain mitigations
|
|
97
|
+
└── ARCHITECTURE.md # Technical deep-dive
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 🛠️ Quickstart & Local Testing
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# 1. Activate virtual environment
|
|
106
|
+
source .venv/bin/activate
|
|
107
|
+
|
|
108
|
+
# 2. Run automated test suite
|
|
109
|
+
pytest tests/
|
|
110
|
+
|
|
111
|
+
# 3. Generate a new Agent Wallet
|
|
112
|
+
apay wallet new
|
|
113
|
+
|
|
114
|
+
# 4. Protect a local service
|
|
115
|
+
apay protect --target http://localhost:8000 --price 0.001 --wallet 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
*Standalone root project under `/home/sagar/a_pay`, connected to AUM / system_core.*
|
apay-0.1.0/README.md
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# ⚡ A-Pay Protocol (AgentPay)
|
|
2
|
+
> **The Universal Micropayment & Economic Layer for Autonomous AI Agents**
|
|
3
|
+
|
|
4
|
+
[](https://www.python.org/)
|
|
5
|
+
[]()
|
|
6
|
+
[]()
|
|
7
|
+
[](https://apay-network.vercel.app)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 🎯 Vision & Identity
|
|
12
|
+
**A-Pay** is an ultra-lightweight, zero-latency, open economic rail designed for the machine-to-machine (M2M) economy. Just as UPI revolutionized human digital payments in India, A-Pay enables autonomous AI software agents to discover, consume, and pay for data, compute, APIs, and micro-services on the fly—without credit cards, human KYC, or seed phrase friction.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 🚀 1-Command Experience
|
|
17
|
+
|
|
18
|
+
### 1. Website / API Owners (The Sellers)
|
|
19
|
+
Protect ANY existing website or API with an instant HTTP 402 crypto paywall—**zero code modifications required**:
|
|
20
|
+
```bash
|
|
21
|
+
apay protect --target http://localhost:8000 --price 0.001 --wallet 0xYourWalletAddress
|
|
22
|
+
```
|
|
23
|
+
* Incoming requests from AI bots will automatically receive an **HTTP 402 Payment Required** challenge.
|
|
24
|
+
* Once the AI agent's cryptographic micropayment is verified (<15ms), the request is forwarded to your server and data is unlocked!
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
### 2. AI Agent Developers (The Buyers)
|
|
29
|
+
Give your AI agent an in-memory wallet and strict spending guardrails with **2 lines of code**:
|
|
30
|
+
```python
|
|
31
|
+
from apay import APaySession, AgentWallet
|
|
32
|
+
|
|
33
|
+
# Generate or load wallet with daily safety limit
|
|
34
|
+
wallet = AgentWallet(private_key="0x...", max_per_call_usdc=0.01, daily_budget_usdc=5.0)
|
|
35
|
+
session = APaySession(wallet)
|
|
36
|
+
|
|
37
|
+
# Automatically handles HTTP 402 challenges & settles on the fly
|
|
38
|
+
response = session.get("https://protected-api.com/market-data")
|
|
39
|
+
print(response.json())
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 📦 Directory Structure
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
/home/sagar/a_pay/
|
|
48
|
+
├── .aum_identity.md # AUM Project Core Identity binding
|
|
49
|
+
├── RULEBOOK.md # 📜 Master Rulebook: M2M Core, H2B Checkout & $APAY Token
|
|
50
|
+
├── neural_ais/ # Symlink to /home/sagar/neural_core
|
|
51
|
+
├── pyproject.toml # Hatchling & uv build system (CLI entrypoint: `apay`)
|
|
52
|
+
├── src/
|
|
53
|
+
│ └── apay/
|
|
54
|
+
│ ├── __init__.py # Package exports
|
|
55
|
+
│ ├── cli.py # ⚡ 1-Command CLI (`apay protect`, `apay wallet new`, `apay pay`)
|
|
56
|
+
│ ├── client.py # 🤖 Auto-settling HTTP client (sync & async)
|
|
57
|
+
│ ├── wallet.py # 🔐 In-memory wallet + local spending limits
|
|
58
|
+
│ └── proxy.py # 🛡️ Ultra-light reverse proxy paywall (Starlette + viem/eth)
|
|
59
|
+
├── contracts/
|
|
60
|
+
│ └── src/
|
|
61
|
+
│ └── APayRouter.sol# Solidity ^0.8.28 Smart Contract Router (1% protocol fee)
|
|
62
|
+
├── tests/
|
|
63
|
+
│ └── test_flow.py # Automated integration & guardrail test suite
|
|
64
|
+
├── spec/
|
|
65
|
+
│ ├── HTTP_402_SPEC.md # Official RFC wire format
|
|
66
|
+
│ └── SECURITY_MODEL.md # Anti-replay & infinite-loop drain mitigations
|
|
67
|
+
└── ARCHITECTURE.md # Technical deep-dive
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 🛠️ Quickstart & Local Testing
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# 1. Activate virtual environment
|
|
76
|
+
source .venv/bin/activate
|
|
77
|
+
|
|
78
|
+
# 2. Run automated test suite
|
|
79
|
+
pytest tests/
|
|
80
|
+
|
|
81
|
+
# 3. Generate a new Agent Wallet
|
|
82
|
+
apay wallet new
|
|
83
|
+
|
|
84
|
+
# 4. Protect a local service
|
|
85
|
+
apay protect --target http://localhost:8000 --price 0.001 --wallet 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
*Standalone root project under `/home/sagar/a_pay`, connected to AUM / system_core.*
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "apay"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Universal HTTP 402 Micropayment Protocol & CLI for Autonomous AI Agents"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = { text = "MIT" }
|
|
7
|
+
requires-python = ">=3.11"
|
|
8
|
+
authors = [
|
|
9
|
+
{ name = "A-Pay Protocol Core Swarm", email = "core@apay.network" }
|
|
10
|
+
]
|
|
11
|
+
keywords = [
|
|
12
|
+
"http-402",
|
|
13
|
+
"micropayments",
|
|
14
|
+
"ai-agents",
|
|
15
|
+
"autonomous-agents",
|
|
16
|
+
"base-l2",
|
|
17
|
+
"usdc",
|
|
18
|
+
"paywall",
|
|
19
|
+
"m2m-economy"
|
|
20
|
+
]
|
|
21
|
+
classifiers = [
|
|
22
|
+
"Development Status :: 4 - Beta",
|
|
23
|
+
"Intended Audience :: Developers",
|
|
24
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
25
|
+
"Topic :: Security :: Cryptography",
|
|
26
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
27
|
+
"Programming Language :: Python :: 3",
|
|
28
|
+
"Programming Language :: Python :: 3.11",
|
|
29
|
+
"Programming Language :: Python :: 3.12",
|
|
30
|
+
"Programming Language :: Python :: 3.13",
|
|
31
|
+
"License :: OSI Approved :: MIT License",
|
|
32
|
+
"Operating System :: OS Independent",
|
|
33
|
+
]
|
|
34
|
+
dependencies = [
|
|
35
|
+
"httpx>=0.27.0",
|
|
36
|
+
"pydantic>=2.7.0",
|
|
37
|
+
"eth-account>=0.11.0",
|
|
38
|
+
"click>=8.1.0",
|
|
39
|
+
"uvicorn>=0.30.0",
|
|
40
|
+
"starlette>=0.38.0",
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[project.urls]
|
|
44
|
+
Homepage = "https://apay-network.vercel.app"
|
|
45
|
+
Documentation = "https://apay-network.vercel.app"
|
|
46
|
+
Repository = "https://github.com/a-pay/apay"
|
|
47
|
+
|
|
48
|
+
[project.scripts]
|
|
49
|
+
apay = "apay.cli:main"
|
|
50
|
+
|
|
51
|
+
[build-system]
|
|
52
|
+
requires = ["hatchling"]
|
|
53
|
+
build-backend = "hatchling.build"
|
|
54
|
+
|
|
55
|
+
[tool.hatch.build.targets.sdist]
|
|
56
|
+
only-include = [
|
|
57
|
+
"src/apay",
|
|
58
|
+
"README.md",
|
|
59
|
+
"pyproject.toml",
|
|
60
|
+
"ARCHITECTURE.md",
|
|
61
|
+
"spec",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[tool.hatch.build.targets.wheel]
|
|
65
|
+
packages = ["src/apay"]
|
|
66
|
+
|
|
67
|
+
[tool.pytest.ini_options]
|
|
68
|
+
testpaths = ["tests"]
|
|
69
|
+
|
|
70
|
+
[dependency-groups]
|
|
71
|
+
dev = [
|
|
72
|
+
"mypy>=2.3.1",
|
|
73
|
+
"pytest-asyncio>=1.4.0",
|
|
74
|
+
"ruff>=0.16.8",
|
|
75
|
+
]
|
|
76
|
+
|
|
77
|
+
[tool.ruff]
|
|
78
|
+
line-length = 110
|
|
79
|
+
target-version = "py311"
|
|
80
|
+
|
|
81
|
+
[tool.ruff.lint]
|
|
82
|
+
select = ["E", "F", "I", "UP", "B"]
|
|
83
|
+
ignore = ["BLE001", "B008", "E501"]
|
|
84
|
+
|
|
85
|
+
[tool.mypy]
|
|
86
|
+
python_version = "3.11"
|
|
87
|
+
warn_return_any = false
|
|
88
|
+
warn_unused_configs = true
|
|
89
|
+
ignore_missing_imports = true
|
|
90
|
+
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# 📜 A-Pay RFC 001: HTTP 402 Micropayment Specification
|
|
2
|
+
|
|
3
|
+
## Status: Draft / Standard v1.0
|
|
4
|
+
|
|
5
|
+
### Abstract
|
|
6
|
+
This document formalizes the HTTP 402 (Payment Required) wire format for Autonomous AI Agent machine-to-machine micropayments.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Request & Response Headers
|
|
11
|
+
|
|
12
|
+
### Challenge Headers (Server -> Agent upon 402)
|
|
13
|
+
- `X-APay-Version`: Version of the protocol (e.g. `1.0.0`).
|
|
14
|
+
- `X-APay-Receiver`: EVM/Solana address of the merchant/provider.
|
|
15
|
+
- `X-APay-Amount`: Price in base units (e.g. `1000` = 0.001 USDC for 6-decimal tokens).
|
|
16
|
+
- `X-APay-Currency`: Symbol of the currency (`USDC`).
|
|
17
|
+
- `X-APay-Network`: Blockchain network identifier (`base`, `arbitrum`, `solana`).
|
|
18
|
+
- `X-APay-Nonce`: Unique UUID v4 or cryptographic nonce generated by server for replay prevention.
|
|
19
|
+
- `X-APay-Expires-At`: Unix timestamp after which this quote expires (default: 60 seconds).
|
|
20
|
+
|
|
21
|
+
### Authorization Header (Agent -> Server)
|
|
22
|
+
Format:
|
|
23
|
+
```
|
|
24
|
+
Authorization: APay <SignatureScheme>:<Signature>:<PayerAddress>:<Nonce>:<Amount>
|
|
25
|
+
```
|
|
26
|
+
Example:
|
|
27
|
+
```
|
|
28
|
+
Authorization: APay eip712:0x3f4a...:0x1234...:f89a421b:1000
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 2. EIP-712 Typed Data Structure
|
|
34
|
+
For EVM settlements (Base, Arbitrum), payment authorizations MUST be signed using EIP-712 structured data:
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"types": {
|
|
39
|
+
"EIP712Domain": [
|
|
40
|
+
{ "name": "name", "type": "string" },
|
|
41
|
+
{ "name": "version", "type": "string" },
|
|
42
|
+
{ "name": "chainId", "type": "uint256" },
|
|
43
|
+
{ "name": "verifyingContract", "type": "address" }
|
|
44
|
+
],
|
|
45
|
+
"PaymentAuthorization": [
|
|
46
|
+
{ "name": "payer", "type": "address" },
|
|
47
|
+
{ "name": "receiver", "type": "address" },
|
|
48
|
+
{ "name": "amount", "type": "uint256" },
|
|
49
|
+
{ "name": "nonce", "type": "string" },
|
|
50
|
+
{ "name": "validUntil", "type": "uint256" }
|
|
51
|
+
]
|
|
52
|
+
},
|
|
53
|
+
"primaryType": "PaymentAuthorization",
|
|
54
|
+
"domain": {
|
|
55
|
+
"name": "APayProtocol",
|
|
56
|
+
"version": "1.0",
|
|
57
|
+
"chainId": 8453,
|
|
58
|
+
"verifyingContract": "0xAPayRouterAddress..."
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## 3. Replay Prevention
|
|
66
|
+
1. The server stores recent nonces in a fast in-memory key-value cache (e.g. Redis / LRU cache) with a TTL matching `validUntil`.
|
|
67
|
+
2. Once a nonce is used to claim an API response, it is permanently consumed. Any subsequent request with the same nonce is rejected with `401 Unauthorized` or `400 Bad Request`.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# 🛡️ A-Pay Security & Economic Model
|
|
2
|
+
|
|
3
|
+
## 1. Threat Vectors & Mitigations
|
|
4
|
+
|
|
5
|
+
### A. Rogue Agent Drain (Infinite Loops)
|
|
6
|
+
- **Threat**: An AI agent gets trapped in a reasoning or execution loop, triggering 50,000 API calls per minute and draining the operator's entire crypto balance.
|
|
7
|
+
- **Mitigation**:
|
|
8
|
+
1. **Strict Client-Side Budgets**: The `AgentWallet` class enforces local hard rate-limits (`max_per_call`, `max_per_minute`, `daily_cap`).
|
|
9
|
+
2. **Smart Contract Session Keys**: The on-chain `EscrowVault` can only release funds up to a programmatic allowance per epoch. Even if the local private key is compromised, funds beyond the allowance are mathematically inaccessible.
|
|
10
|
+
|
|
11
|
+
### B. Man-in-the-Middle (MITM) & Replay Attacks
|
|
12
|
+
- **Threat**: An attacker snoops on the HTTP traffic and re-submits the agent's signature to drain funds or steal data.
|
|
13
|
+
- **Mitigation**:
|
|
14
|
+
1. Mandatory TLS (`https://` required).
|
|
15
|
+
2. Server-generated cryptographic nonces with short 60s expirations.
|
|
16
|
+
3. EIP-712 domain binding (`chainId`, `verifyingContract`, `receiver`).
|
|
17
|
+
|
|
18
|
+
### C. Merchant Non-Delivery (Sybil / Scam APIs)
|
|
19
|
+
- **Threat**: A malicious API returns an HTTP 402, takes the payment signature, but fails to deliver the promised data.
|
|
20
|
+
- **Mitigation**:
|
|
21
|
+
- **Reputation Registry**: Verified providers on A-Pay receive trust badges.
|
|
22
|
+
- **Optimistic State Channels**: For high-volume streaming data (e.g. LLM tokens), payments are streamed continuously per 100 tokens, bounding any non-delivery loss to < $0.0001.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 2. Protocol Fee Invariance
|
|
27
|
+
- The protocol fee (0.5% - 1.0%) is enforced inside the smart contract `APayRouter.sol`:
|
|
28
|
+
```solidity
|
|
29
|
+
uint256 protocolFee = (amount * feeBps) / 10000;
|
|
30
|
+
uint256 merchantAmount = amount - protocolFee;
|
|
31
|
+
|
|
32
|
+
usdc.transferFrom(payer, treasury, protocolFee);
|
|
33
|
+
usdc.transferFrom(payer, receiver, merchantAmount);
|
|
34
|
+
```
|
|
35
|
+
- No party can bypass this fee when settling through the official decentralized router.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""
|
|
2
|
+
A-Pay (AgentPay) Protocol
|
|
3
|
+
Universal Micropayment & Economic Layer for Autonomous AI Agents.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from .client import APayClient, APaySession
|
|
7
|
+
from .integrations import (
|
|
8
|
+
APayCrewTool,
|
|
9
|
+
APayRequestsWrapper,
|
|
10
|
+
APayTool,
|
|
11
|
+
create_apay_tool,
|
|
12
|
+
create_crew_tool,
|
|
13
|
+
)
|
|
14
|
+
from .proxy import create_proxy_app
|
|
15
|
+
from .relayer import ClaimJournal, ClaimRecord, SettlementRelayer
|
|
16
|
+
from .wallet import (
|
|
17
|
+
DEFAULT_CHAIN_ID,
|
|
18
|
+
DEFAULT_EIP712_NAME,
|
|
19
|
+
DEFAULT_EIP712_VERSION,
|
|
20
|
+
DEFAULT_ROUTER_ADDRESS,
|
|
21
|
+
AgentWallet,
|
|
22
|
+
get_eip712_domain,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
__all__ = [
|
|
26
|
+
"APayClient",
|
|
27
|
+
"APayCrewTool",
|
|
28
|
+
"APayRequestsWrapper",
|
|
29
|
+
"APaySession",
|
|
30
|
+
"APayTool",
|
|
31
|
+
"AgentWallet",
|
|
32
|
+
"ClaimJournal",
|
|
33
|
+
"ClaimRecord",
|
|
34
|
+
"DEFAULT_CHAIN_ID",
|
|
35
|
+
"DEFAULT_EIP712_NAME",
|
|
36
|
+
"DEFAULT_EIP712_VERSION",
|
|
37
|
+
"DEFAULT_ROUTER_ADDRESS",
|
|
38
|
+
"SettlementRelayer",
|
|
39
|
+
"create_apay_tool",
|
|
40
|
+
"create_crew_tool",
|
|
41
|
+
"create_proxy_app",
|
|
42
|
+
"get_eip712_domain",
|
|
43
|
+
]
|
|
44
|
+
__version__ = "0.1.0"
|