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

atp/__init__.py

@@ -1,11 +1,8 @@
-"""ATP Protocol package."""
-
-from atp.middleware import (
-    ATPSettlementMiddleware,
-    create_settlement_middleware,
-)
+from atp.middleware import ATPSettlementMiddleware, create_settlement_middleware
+from atp.settlement_client import SettlementServiceClient
 
 __all__ = [
     "ATPSettlementMiddleware",
     "create_settlement_middleware",
-]
+    "SettlementServiceClient",
+]

atp/config.py

@@ -73,5 +73,5 @@ ATP_SOLANA_DEBUG = _bool_env("ATP_SOLANA_DEBUG", default=False)
 
 # Settlement Service URL
 ATP_SETTLEMENT_URL = os.getenv(
-    "ATP_SETTLEMENT_URL", "http://localhost:8001"
+    "ATP_SETTLEMENT_URL", "https://facilitator.swarms.world"
 )

atp/middleware.py

@@ -67,8 +67,6 @@ class ATPSettlementMiddleware(BaseHTTPMiddleware):
         recipient_pubkey: Optional[str] = None,
         skip_preflight: bool = False,
         commitment: str = "confirmed",
-        usage_response_key: str = "usage",
-        include_usage_in_response: bool = True,
         require_wallet: bool = True,
         settlement_service_url: Optional[str] = None,
     ):
@@ -92,8 +90,6 @@ class ATPSettlementMiddleware(BaseHTTPMiddleware):
                 This wallet receives the main payment (after processing fee). Required.
             skip_preflight: Whether to skip preflight simulation for Solana transactions.
             commitment: Solana commitment level (processed|confirmed|finalized).
-            usage_response_key: Key in response JSON where usage data is located (default: "usage").
-            include_usage_in_response: Whether to add usage/cost info to the response.
             require_wallet: Whether to require wallet private key (if False, skips settlement when missing).
             settlement_service_url: Base URL of the settlement service. If not provided, uses
                 ATP_SETTLEMENT_URL environment variable (default: http://localhost:8001).
@@ -119,8 +115,6 @@ class ATPSettlementMiddleware(BaseHTTPMiddleware):
             )
         self.skip_preflight = skip_preflight
         self.commitment = commitment
-        self.usage_response_key = usage_response_key
-        self.include_usage_in_response = include_usage_in_response
         self.require_wallet = require_wallet
         # Always use settlement service - initialize client with config value or provided URL
         service_url = (
@@ -146,10 +140,9 @@ class ATPSettlementMiddleware(BaseHTTPMiddleware):
         """
         Extract usage information from response body.
 
-        Tries multiple strategies:
-        1. Look for usage data at the configured usage_response_key
-        2. Check if the entire response contains usage-like keys
-        3. Try nested structures (usage.usage, meta.usage, etc.)
+        Automatically detects usage data using multiple strategies:
+        1. Check if the entire response contains usage-like keys
+        2. Try nested structures with common usage key names (usage, token_usage, etc.)
 
         The usage data is then sent to the settlement service for parsing,
         so we just need to extract the raw usage object.
@@ -160,12 +153,7 @@ class ATPSettlementMiddleware(BaseHTTPMiddleware):
                 return None
             data = json.loads(body_str)
 
-            # Strategy 1: Try the configured usage key first
-            usage = data.get(self.usage_response_key)
-            if usage and isinstance(usage, dict):
-                return usage
-
-            # Strategy 2: Check if the entire response is usage-like
+            # Strategy 1: Check if the entire response is usage-like
             if isinstance(data, dict):
                 # Check for common usage keys at top level
                 usage_keys = [
@@ -182,7 +170,7 @@ class ATPSettlementMiddleware(BaseHTTPMiddleware):
                 if any(key in data for key in usage_keys):
                     return data
 
-            # Strategy 3: Try nested structures
+            # Strategy 2: Try nested structures
             # Check for usage nested in common locations
             for nested_key in [
                 "usage",
@@ -284,21 +272,20 @@ class ATPSettlementMiddleware(BaseHTTPMiddleware):
                 detail=f"Settlement failed: {str(e)}",
             )
 
-        # Modify response to include usage/payment info if requested
-        if self.include_usage_in_response:
-            try:
-                response_data = json.loads(
-                    response_body.decode("utf-8")
-                )
-                response_data["atp_settlement"] = payment_result
-                response_data["atp_usage"] = usage
-                response_body = json.dumps(response_data).encode(
-                    "utf-8"
-                )
-            except Exception as e:
-                logger.warning(
-                    f"Failed to add settlement info to response: {e}"
-                )
+        # Always include settlement information in the response
+        try:
+            response_data = json.loads(
+                response_body.decode("utf-8")
+            )
+            response_data["atp_settlement"] = payment_result
+            response_data["atp_usage"] = usage
+            response_body = json.dumps(response_data).encode(
+                "utf-8"
+            )
+        except Exception as e:
+            logger.warning(
+                f"Failed to add settlement info to response: {e}"
+            )
 
         return Response(
             content=response_body,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: atp-protocol
-Version: 1.0.0
+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
@@ -17,13 +17,14 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
 Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: fastapi
 Requires-Dist: httpx
 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
 Project-URL: Homepage, https://github.com/The-Swarm-Corporation/ATP-Protocol
 Project-URL: Repository, https://github.com/The-Swarm-Corporation/ATP-Protocol
@@ -254,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
@@ -291,202 +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
-    usage_response_key="usage",  # Key in response where usage data is located
-    include_usage_in_response=True,  # Add usage/cost info to response
-    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`)
-- **`usage_response_key`** (default: `"usage"`): Key in response JSON where usage data is located
-- **`include_usage_in_response`** (default: `True`): Whether to add usage/cost info to the response
-- **`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 searches for usage data in this order:
-1. The configured `usage_response_key` (default: `"usage"`)
-2. Top-level keys in the response
-3. Nested structures (`usage`, `meta.usage`, `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.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+atp/__init__.py,sha256=fpKQQCi9HQEj4t2Rs5ng5qmp0KwGV6bZIl1tnS-3HQ8,251
+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.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,,