atp-protocol 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

{atp_protocol-1.0.1.dist-info → atp_protocol-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: atp-protocol
-Version: 1.0.1
+Version: 1.2.0
 Summary: ATP Protocol - Agentic Trade Protocol. The easiest way to enable agent-to-agent payments powered by Solana.
 License: MIT
 Keywords: atp,atp-protocol,solana,blockchain,cryptocurrency,payment-gated,agent-to-agent,agent payments,agent execution,payment settlement,solana payments,usdc,sol,fastapi,agent api,payment gateway,settlement service,agent marketplace,decentralized payments,web3,crypto payments,agent infrastructure,payment middleware,automated settlement
@@ -23,8 +23,6 @@ Requires-Dist: loguru
 Requires-Dist: pydantic
 Requires-Dist: python-dotenv
 Requires-Dist: setuptools
-Requires-Dist: solana
-Requires-Dist: solders
 Requires-Dist: starlette
 Requires-Dist: swarms
 Project-URL: Documentation, https://github.com/The-Swarm-Corporation/ATP-Protocol
@@ -257,33 +255,46 @@ stateDiagram-v2
 
 ## ATP Settlement Middleware
 
-The ATP Protocol also provides a **FastAPI middleware** that enables **automatic payment deduction** for any configured endpoint. Unlike the main ATP Gateway (which uses a 402 challenge pattern), the middleware automatically deducts payment **after** the endpoint executes successfully, making it ideal for APIs that want seamless, automatic settlement.
+The ATP Settlement Middleware enables **automatic payment processing** for any FastAPI endpoint. Unlike the main ATP Gateway (which uses a 402 challenge), the middleware handles payment **automatically after** your endpoint executes—perfect for APIs that want seamless billing.
 
-### How the Middleware Works
+### How It Works
 
-The `ATPSettlementMiddleware` intercepts requests to configured endpoints and:
+The middleware intercepts requests, executes your endpoint, then automatically processes payment:
 
-1. **Extracts wallet private key** from request headers (default: `x-wallet-private-key`)
-2. **Executes the endpoint** normally (passes request through)
-3. **Extracts usage data** from the response (token counts from various API formats)
-4. **Calculates cost** based on configured rates (`input_cost_per_million_usd`, `output_cost_per_million_usd`)
-5. **Automatically deducts payment** from the provided wallet via Solana transaction
-6. **Splits payment** between recipient (endpoint host) and Swarms Treasury (5% fee)
-7. **Adds settlement info** to the response (optional)
+```mermaid
+sequenceDiagram
+  autonumber
+  participant C as Client
+  participant M as Middleware
+  participant E as Endpoint
+  participant SS as Settlement Service
+  participant S as Solana
 
-### Key Differences from Main ATP Protocol
+  C->>M: POST /v1/chat<br/>(x-wallet-private-key header)
+  M->>E: Forward request
+  E-->>M: Response + usage data
+  M->>M: Extract token usage<br/>(auto-detects format)
+  M->>SS: Calculate payment<br/>(usage → USD → SOL/USDC)
+  SS->>SS: Split payment<br/>(95% recipient, 5% treasury)
+  SS->>S: Send payment transaction
+  S-->>SS: Transaction signature
+  SS-->>M: Settlement details
+  M->>M: Add settlement info<br/>to response
+  M-->>C: Response + atp_settlement
+```
 
-| Feature | Main ATP Gateway | Middleware |
-|---------|-----------------|------------|
-| **Payment Flow** | Two-step: 402 challenge → settle | Automatic: single request |
-| **Response** | Returns 402 with payment challenge | Returns normal response + settlement info |
-| **Integration** | Requires two API calls | Single API call with wallet header |
-| **Use Case** | Pay-to-unlock results | Automatic per-request billing |
-| **Wallet Key** | Provided during settlement | Provided in request header |
+**Step-by-step:**
 
-### Middleware Configuration
+1. **Client sends request** with wallet private key in header (`x-wallet-private-key`)
+2. **Middleware forwards** request to your endpoint
+3. **Endpoint executes** and returns response with usage data
+4. **Middleware extracts** token counts (supports OpenAI, Anthropic, Google, etc.)
+5. **Settlement service calculates** cost: `(input_tokens × input_rate + output_tokens × output_rate) / 1M`
+6. **Settlement service splits** payment: 95% to recipient, 5% to Swarms Treasury
+7. **Settlement service sends** Solana transaction
+8. **Middleware adds** settlement info to response and returns to client
 
-Add the middleware to your FastAPI app:
+### Quick Start
 
 ```python
 from fastapi import FastAPI
@@ -294,197 +305,97 @@ app = FastAPI()
 
 app.add_middleware(
     ATPSettlementMiddleware,
-    allowed_endpoints=[
-        "/v1/chat",
-        "/v1/completions",
-        "/v1/agent/execute",
-    ],
-    input_cost_per_million_usd=10.0,  # $10 per million input tokens
+    allowed_endpoints=["/v1/chat", "/v1/completions"],
+    input_cost_per_million_usd=10.0,   # $10 per million input tokens
     output_cost_per_million_usd=30.0,  # $30 per million output tokens
-    wallet_private_key_header="x-wallet-private-key",  # Header name for wallet key
-    payment_token=PaymentToken.SOL,  # SOL or USDC
-    recipient_pubkey="YourPublicKeyHere",  # Required: endpoint host receives payment
-    skip_preflight=False,  # Skip Solana transaction preflight simulation
-    commitment="confirmed",  # Solana commitment level
-    require_wallet=True,  # Require wallet key (if False, skips settlement when missing)
+    recipient_pubkey="YourPublicKeyHere",  # Your wallet receives 95%
+    payment_token=PaymentToken.SOL,
 )
 ```
 
-### Configuration Parameters
-
-- **`allowed_endpoints`** (required): List of endpoint paths to apply settlement to (exact matches only)
-- **`input_cost_per_million_usd`** (required): Cost per million input tokens in USD
-- **`output_cost_per_million_usd`** (required): Cost per million output tokens in USD
-- **`wallet_private_key_header`** (default: `"x-wallet-private-key"`): HTTP header name containing the wallet private key
-- **`payment_token`** (default: `PaymentToken.SOL`): Token to use for payment (SOL or USDC)
-- **`recipient_pubkey`** (required): Solana public key of the recipient wallet (endpoint host receives main payment)
-- **`skip_preflight`** (default: `False`): Whether to skip preflight simulation for Solana transactions
-- **`commitment`** (default: `"confirmed"`): Solana commitment level (`processed`|`confirmed`|`finalized`)
-- **`require_wallet`** (default: `True`): Whether to require wallet private key (if False, skips settlement when missing)
-
-### Usage Example
-
-**Client Request:**
+**Client request:**
 ```bash
 curl -X POST http://localhost:8000/v1/chat \
-  -H "Content-Type: application/json" \
   -H "x-wallet-private-key: [1,2,3,...]" \
-  -d '{"message": "Hello, world!"}'
+  -d '{"message": "Hello!"}'
 ```
 
-**Endpoint Implementation:**
+**Your endpoint:**
 ```python
 @app.post("/v1/chat")
-async def chat_endpoint(request: dict):
-    # Your endpoint logic here
-    response_data = {
-        "output": "Hello! This is a response from the chat endpoint.",
+async def chat(request: dict):
+    return {
+        "output": "Response here",
         "usage": {
-            "input_tokens": 150,  # Tokens in the request
-            "output_tokens": 50,  # Tokens in the response
-            "total_tokens": 200,
-        },
+            "input_tokens": 150,
+            "output_tokens": 50,
+        }
     }
-    return JSONResponse(content=response_data)
 ```
 
-**Response (with settlement info):**
+**Response includes settlement:**
 ```json
 {
-  "output": "Hello! This is a response from the chat endpoint.",
-  "usage": {
-    "input_tokens": 150,
-    "output_tokens": 50,
-    "total_tokens": 200
-  },
-  "atp_usage": {
-    "input_tokens": 150,
-    "output_tokens": 50,
-    "total_tokens": 200
-  },
+  "output": "Response here",
+  "usage": {"input_tokens": 150, "output_tokens": 50},
   "atp_settlement": {
     "status": "paid",
     "transaction_signature": "5j7s8K9...",
-    "pricing": {
-      "usd_cost": 0.003,
-      "source": "middleware_rates",
-      "input_tokens": 150,
-      "output_tokens": 50,
-      "total_tokens": 200,
-      "input_cost_per_million_usd": 10.0,
-      "output_cost_per_million_usd": 30.0,
-      "input_cost_usd": 0.0015,
-      "output_cost_usd": 0.0015
-    },
     "payment": {
-      "total_amount_lamports": 300000,
       "total_amount_sol": 0.0003,
-      "total_amount_usd": 0.003,
-      "treasury": {
-        "pubkey": "7MaX4muAn8ZQREJxnupm8sgokwFHujgrGfH9Qn81BuEV",
-        "amount_lamports": 15000,
-        "amount_sol": 0.000015,
-        "amount_usd": 0.00015
-      },
-      "recipient": {
-        "pubkey": "YourPublicKeyHere",
-        "amount_lamports": 285000,
-        "amount_sol": 0.000285,
-        "amount_usd": 0.00285
-      }
+      "recipient": {"amount_sol": 0.000285},
+      "treasury": {"amount_sol": 0.000015}
     }
   }
 }
 ```
 
-### Supported Usage Formats
+### Configuration
 
-The middleware automatically detects and parses usage data from multiple API formats:
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `allowed_endpoints` | ✅ | List of paths to apply settlement (e.g., `["/v1/chat"]`) |
+| `input_cost_per_million_usd` | ✅ | Cost per million input tokens |
+| `output_cost_per_million_usd` | ✅ | Cost per million output tokens |
+| `recipient_pubkey` | ✅ | Your Solana wallet (receives 95% of payment) |
+| `wallet_private_key_header` | ❌ | Header name for wallet key (default: `x-wallet-private-key`) |
+| `payment_token` | ❌ | `PaymentToken.SOL` or `PaymentToken.USDC` (default: SOL) |
+| `require_wallet` | ❌ | Require wallet key or skip settlement (default: `True`) |
+| `settlement_service_url` | ❌ | Settlement service URL (default: from `ATP_SETTLEMENT_URL` env) |
 
-- **OpenAI**: `prompt_tokens`, `completion_tokens`, `total_tokens`
-- **Anthropic**: `input_tokens`, `output_tokens`, `total_tokens`
-- **Google/Gemini**: `promptTokenCount`, `candidatesTokenCount`, `totalTokenCount`
-- **Cohere**: `tokens` (total), or `input_tokens`/`output_tokens` separately
-- **Generic**: `input_tokens`, `output_tokens`, `total_tokens`
-- **Nested**: `usage.prompt_tokens`, `meta.usage`, `statistics`, etc.
+### Payment Calculation
 
-The middleware automatically detects usage data by:
-1. Checking if the entire response contains usage-like keys at the top level
-2. Searching nested structures with common usage key names (`usage`, `token_usage`, `meta`, `statistics`, etc.)
+The middleware uses your configured rates to calculate cost:
 
-### Payment Flow
-
-```mermaid
-sequenceDiagram
-  autonumber
-  participant C as Client
-  participant M as Middleware
-  participant E as Endpoint
-  participant S as Solana
-
-  C->>M: POST /v1/chat<br/>(x-wallet-private-key header)
-  M->>E: Forward request
-  E-->>M: Response + usage data
-  M->>M: Extract usage tokens<br/>(normalize format)
-  M->>M: Calculate USD cost<br/>(from token counts)
-  M->>M: Fetch token price<br/>(SOL/USDC)
-  M->>M: Calculate payment amounts<br/>(with 5% fee split)
-  M->>S: Send split payment tx<br/>(recipient + treasury)
-  S-->>M: Transaction signature
-  M->>M: Add settlement info<br/>to response
-  M-->>C: Response + atp_settlement
+```
+usd_cost = (input_tokens / 1,000,000 × input_rate) + (output_tokens / 1,000,000 × output_rate)
+token_amount = usd_cost / token_price_usd
 ```
 
-### Payment Split Logic
-
-The middleware automatically splits payments:
-
-- **Total Payment**: `usd_cost / token_price_usd`
-- **Swarms Treasury Fee**: `5%` of total (from `config.SETTLEMENT_FEE_PERCENT`)
-- **Recipient Amount**: `95%` of total (endpoint host receives this)
-
-The fee is **taken from the total** (not added on top), so the recipient receives the net amount after fees.
-
-### Error Handling
-
-- **Missing wallet key**: Returns `401 Unauthorized` if `require_wallet=True` (default)
-- **Missing usage data**: Logs warning and returns original response (no settlement)
-- **Payment failure**: Returns `500 Internal Server Error` with error details
-- **Invalid private key**: Returns `500 Internal Server Error` with parsing error
-
-### Custom API Key Integration
+Payment is split automatically:
+- **95%** → `recipient_pubkey` (your wallet)
+- **5%** → Swarms Treasury (processing fee)
 
-You can layer your own API key handling on top of the middleware:
+The fee is **deducted from the total** (not added on top).
 
-```python
-# Simple in-memory mapping (replace with database in production)
-API_KEY_TO_WALLET = {
-    "user_api_key_123": "[1,2,3,...]",  # Solana private key
-}
+### Supported Usage Formats
 
-def get_wallet_from_api_key(api_key: str = Header(..., alias="x-api-key")) -> str:
-    """Custom dependency to map API keys to wallet private keys."""
-    if api_key not in API_KEY_TO_WALLET:
-        raise HTTPException(status_code=401, detail="Invalid API key")
-    return API_KEY_TO_WALLET[api_key]
+The middleware auto-detects usage from common API formats:
 
-# Use a custom middleware to inject wallet key from API key
-# before the ATP middleware processes the request
-```
-
-### When to Use Middleware vs. Main Protocol
+- **OpenAI**: `prompt_tokens`, `completion_tokens`
+- **Anthropic**: `input_tokens`, `output_tokens`
+- **Google/Gemini**: `promptTokenCount`, `candidatesTokenCount`
+- **Generic**: `input_tokens`, `output_tokens`, `total_tokens`
+- **Nested**: `usage.*`, `meta.usage`, `statistics.*`
 
-**Use the Middleware when:**
-- You want automatic, per-request billing
-- Your API already returns usage data
-- You want a single-request flow (no 402 challenge)
-- You're building a service that charges per API call
+### Middleware vs. Main Protocol
 
-**Use the Main Protocol when:**
-- You want explicit payment approval (402 challenge)
-- You need to hold results until payment is confirmed
-- You want a two-step verification process
-- You're building a pay-to-unlock system
+| Feature | Main Gateway | Middleware |
+|---------|--------------|------------|
+| **Flow** | Two-step: 402 challenge → settle | Automatic: single request |
+| **Use Case** | Pay-to-unlock results | Per-request billing |
+| **Integration** | Two API calls | One API call |
 
-See `examples/middleware_usage_example.py` for a complete working example.
+**Use middleware for:** Automatic billing on every request  
+**Use main protocol for:** Explicit payment approval before results
 

{atp_protocol-1.0.1.dist-info → atp_protocol-1.2.0.dist-info}/RECORD

@@ -3,7 +3,7 @@ atp/config.py,sha256=lYERbrySRTuyS_jeaAnLHYuBEQNLqaKLQTy_nEFP7lY,2041
 atp/middleware.py,sha256=GlRBXEba_hlGMPi69LAGUJSQsKfmwSnAENKZQ9QcXhU,13185
 atp/schemas.py,sha256=iASVBPpAhrO-LDXs2UC9ABtfV1oDYsu4kZcz3dVeJNA,6220
 atp/settlement_client.py,sha256=jfvhxDqp2kDISWG7tjX5s88goAPxp-lMXvuJtpMyOys,6742
-atp_protocol-1.0.1.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-atp_protocol-1.0.1.dist-info/METADATA,sha256=BdbWCKlFe31u-00ijy9aKpoIcSIpEwHvjJVS5n3GumA,18192
-atp_protocol-1.0.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-atp_protocol-1.0.1.dist-info/RECORD,,
+atp_protocol-1.2.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+atp_protocol-1.2.0.dist-info/METADATA,sha256=r-Q1CFshMWPS-jftoGwI7OuPcj8B609IRGcBe00VX0E,14295
+atp_protocol-1.2.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+atp_protocol-1.2.0.dist-info/RECORD,,