agent-commerce-framework 0.4.0__tar.gz

agent_commerce_framework-0.4.0/.deliveryignore

@@ -0,0 +1,8 @@
+# Files to exclude from customer delivery packaging
+.internal/
+.deliveryignore
+.git/
+__pycache__/
+*.pyc
+.pytest_cache/
+data/

agent_commerce_framework-0.4.0/.dockerignore

@@ -0,0 +1,11 @@
+.git/
+__pycache__/
+*.pyc
+.pytest_cache/
+data/
+.internal/
+.env
+.gitignore
+.deliveryignore
+.dockerignore
+tests/

agent_commerce_framework-0.4.0/.env.example

@@ -0,0 +1,42 @@
+# Agent Commerce Framework — Environment Variables
+
+# Database (default: SQLite in ./data/)
+# DATABASE_PATH=./data/marketplace.db
+
+# Server
+# HOST=0.0.0.0
+# PORT=8000
+
+# CORS
+# CORS_ORIGINS=*
+
+# Platform Settings
+# PLATFORM_FEE_PCT=0.10
+
+# --- x402 Payment (receive payments from buyers) ---
+# Your wallet address that receives USDC from x402 payments
+# WALLET_ADDRESS=0x...
+
+# Network: Base Sepolia (testnet) or Base Mainnet (production)
+# NETWORK=eip155:84532
+# Production: NETWORK=eip155:8453
+
+# Facilitator URL
+# Testnet: FACILITATOR_URL=https://x402.org/facilitator
+# Production: FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
+
+# --- CDP Wallet (send USDC payouts to providers) ---
+# Get CDP API keys from https://portal.cdp.coinbase.com/
+# CDP_API_KEY_NAME=...
+# CDP_API_KEY_SECRET=...
+# CDP_WALLET_ID=...
+# CDP_NETWORK=base-sepolia
+
+# --- Stripe Agent Checkout Protocol (fiat payments, optional) ---
+# STRIPE_SECRET_KEY=sk_...
+# STRIPE_WEBHOOK_SECRET=whsec_...
+
+# --- NOWPayments (crypto payments via USDT/BTC/etc, optional) ---
+# NOWPAYMENTS_API_KEY=...
+# NOWPAYMENTS_IPN_SECRET=...
+# NOWPAYMENTS_SANDBOX=true

agent_commerce_framework-0.4.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.db
+.env
+.venv/
+data/marketplace.db
+.x402_wallet

agent_commerce_framework-0.4.0/.internal/ARCHITECTURE.md

@@ -0,0 +1,273 @@
+# Agent Commerce Framework — Technical Architecture
+> MIM-299 | v0.1 Draft | 2026-03-18
+
+## System Overview
+
+```
+Client (Agent/Human)
+        │
+        ▼
+┌─────────────────────────┐
+│    API Gateway          │  FastAPI + x402 middleware
+│    /api/v1/*            │  Auth: API Key / Agent Cert
+└─────────┬───────────────┘
+          │
+    ┌─────┴─────┐
+    │           │
+    ▼           ▼
+┌────────┐  ┌────────────┐
+│Registry│  │  Proxy     │  Service discovery + request forwarding
+│Service │  │  + Billing │  x402 payment intercept
+└────┬───┘  └─────┬──────┘
+     │            │
+     ▼            ▼
+┌────────┐  ┌────────────┐
+│ SQLite │  │  Provider  │  Actual service endpoints
+│ /Postgres│ │  Agents   │  (CoinSifter, custom...)
+└────────┘  └────────────┘
+```
+
+## Core Components
+
+### 1. Service Registry
+
+職責：管理服務的註冊、更新、搜尋。
+
+```python
+# Data model (immutable dataclasses)
+
+@dataclass(frozen=True)
+class ServiceListing:
+    id: str                    # UUID
+    provider_id: str           # Agent/Developer ID
+    name: str                  # 服務名稱
+    description: str           # 服務描述
+    endpoint: str              # 實際服務 URL
+    pricing: PricingConfig     # 定價配置
+    status: str                # active / paused / reviewing
+    created_at: datetime
+    updated_at: datetime
+    metadata: dict             # 自由欄位（tags, category 等）
+
+@dataclass(frozen=True)
+class PricingConfig:
+    price_per_call: Decimal    # 每次呼叫價格 (USD)
+    currency: str              # "USDC" | "USD"
+    payment_method: str        # "x402" | "stripe" | "both"
+    free_tier_calls: int       # 免費額度（0 = 無）
+    bulk_discount: dict        # 批量折扣規則
+```
+
+API:
+- `POST /api/v1/services` — 註冊新服務
+- `GET /api/v1/services` — 列出/搜尋服務
+- `GET /api/v1/services/{id}` — 服務詳情
+- `PATCH /api/v1/services/{id}` — 更新服務（owner only）
+- `DELETE /api/v1/services/{id}` — 下架服務
+
+### 2. Payment Proxy (核心創新)
+
+職責：攔截 Agent 對 Agent 的請求，自動處理支付。
+
+流程：
+```
+1. Buyer Agent → 市集 API: GET /api/v1/proxy/{service_id}/endpoint
+2. 市集檢查 Buyer 餘額/授權
+3. 市集用 x402 替 Buyer 付款給 Provider
+4. 市集轉發請求到 Provider endpoint
+5. 收到回應 → 記錄用量 → 回傳給 Buyer
+6. 結算時：Provider 收到 (價格 - 平台費)
+```
+
+為什麼用 proxy 而不是直接 x402：
+- 統一計費和報表
+- 平台可以做品質監控
+- 買方不需要自己處理 x402（降低門檻）
+- 支援非 x402 的 Provider（Stripe 等）
+
+### 3. Metering & Billing
+
+職責：追蹤用量、計費、結算。
+
+```python
+@dataclass(frozen=True)
+class UsageRecord:
+    id: str
+    buyer_id: str
+    service_id: str
+    provider_id: str
+    timestamp: datetime
+    latency_ms: int
+    status_code: int
+    amount_usd: Decimal
+    payment_method: str       # x402 | stripe | free_tier
+    payment_tx: str | None    # x402 tx hash or stripe charge id
+```
+
+結算週期：
+- 即時（x402）：每筆交易即時結算
+- 日結（Stripe）：每日批次結算
+- 平台費：預設 10%，可配置
+
+### 4. Authentication
+
+層級：
+- **Platform API Key**：管理後台、服務註冊
+- **Agent API Key**：Agent 呼叫服務
+- **x402 Wallet**：支付認證（optional，有 API Key 也可以）
+
+```python
+@dataclass(frozen=True)
+class APIKey:
+    key_id: str              # prefix_xxxxx
+    hashed_secret: str       # bcrypt hash
+    owner_id: str
+    role: str                # admin | provider | buyer
+    rate_limit: int          # calls per minute
+    wallet_address: str | None  # 綁定的 x402 錢包
+    created_at: datetime
+    expires_at: datetime | None
+```
+
+## Database Schema (MVP: SQLite → Production: PostgreSQL)
+
+```sql
+-- 服務列表
+CREATE TABLE services (
+    id TEXT PRIMARY KEY,
+    provider_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    description TEXT,
+    endpoint TEXT NOT NULL,
+    price_per_call REAL NOT NULL,
+    currency TEXT DEFAULT 'USDC',
+    payment_method TEXT DEFAULT 'x402',
+    status TEXT DEFAULT 'active',
+    category TEXT,
+    tags TEXT,  -- JSON array
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- API Keys
+CREATE TABLE api_keys (
+    key_id TEXT PRIMARY KEY,
+    hashed_secret TEXT NOT NULL,
+    owner_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    rate_limit INTEGER DEFAULT 60,
+    wallet_address TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    expires_at TIMESTAMP
+);
+
+-- 用量記錄
+CREATE TABLE usage_records (
+    id TEXT PRIMARY KEY,
+    buyer_id TEXT NOT NULL,
+    service_id TEXT NOT NULL,
+    provider_id TEXT NOT NULL,
+    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    latency_ms INTEGER,
+    status_code INTEGER,
+    amount_usd REAL,
+    payment_method TEXT,
+    payment_tx TEXT
+);
+
+-- 結算記錄
+CREATE TABLE settlements (
+    id TEXT PRIMARY KEY,
+    provider_id TEXT NOT NULL,
+    period_start TIMESTAMP,
+    period_end TIMESTAMP,
+    total_amount REAL,
+    platform_fee REAL,
+    net_amount REAL,
+    payment_tx TEXT,
+    status TEXT DEFAULT 'pending'
+);
+
+-- Indexes
+CREATE INDEX idx_usage_buyer ON usage_records(buyer_id, timestamp);
+CREATE INDEX idx_usage_service ON usage_records(service_id, timestamp);
+CREATE INDEX idx_services_status ON services(status, category);
+```
+
+## Tech Stack
+
+| Component | Technology | Rationale |
+|-----------|-----------|-----------|
+| API Server | FastAPI (Python) | x402 SDK 最成熟、生態好 |
+| Database | SQLite (dev) → PostgreSQL (prod) | 零配置開發、生產可擴展 |
+| Payment | x402 SDK + Stripe API | 雙軌支付 |
+| Dashboard | Next.js 14 | 已有 CryptoLog 經驗 |
+| Deployment | Docker Compose | 一鍵部署 |
+| Monitoring | 內建 /health + /metrics | 簡單實用 |
+
+## MVP Scope (Phase 1)
+
+必須有：
+- [x] 服務 Registry CRUD API
+- [x] API Key 認證
+- [x] Payment Proxy（x402）
+- [x] 用量記錄
+- [x] CoinSifter API 種子商品
+- [x] Docker Compose 部署
+- [x] 基本 CLI 管理工具
+
+可以沒有：
+- Dashboard（Phase 3）
+- Stripe 支付（Phase 2）
+- 自動分潤結算（Phase 3）
+- 服務品質監控（Phase 3）
+
+## Security Considerations
+
+- API Key secrets 用 bcrypt hash 存儲
+- x402 支付用 facilitator 驗證（不自建）
+- Rate limit per API key（default 60/min）
+- Provider endpoint URL 只接受 HTTPS
+- 禁止 Provider endpoint 指向 localhost/內網
+- 所有金額計算用 Decimal，不用 float
+- Transaction log 不可修改（append-only）
+
+## File Structure (MVP)
+
+```
+agent-commerce-framework/
+├── marketplace/
+│   ├── __init__.py
+│   ├── models.py          # Data models (frozen dataclasses)
+│   ├── registry.py        # Service CRUD
+│   ├── discovery.py       # Search + filter
+│   ├── proxy.py           # Payment proxy + forwarding
+│   ├── metering.py        # Usage tracking
+│   ├── auth.py            # API Key management
+│   └── db.py              # Database operations
+├── api/
+│   ├── __init__.py
+│   ├── main.py            # FastAPI app
+│   ├── routes/
+│   │   ├── services.py    # /api/v1/services/*
+│   │   ├── proxy.py       # /api/v1/proxy/*
+│   │   ├── keys.py        # /api/v1/keys/*
+│   │   └── health.py      # /health, /metrics
+│   └── middleware.py       # Auth + rate limit
+├── cli/
+│   ├── __init__.py
+│   └── manage.py          # CLI management tool
+├── seed/
+│   └── coinsifter_api.py  # CoinSifter 種子商品
+├── tests/
+│   ├── test_registry.py
+│   ├── test_proxy.py
+│   ├── test_metering.py
+│   └── test_auth.py
+├── docker-compose.yml
+├── Dockerfile
+├── requirements.txt
+├── .env.example
+├── README.md
+└── LICENSE
+```