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

atp_protocol-1.4.0.dist-info/METADATA

@@ -0,0 +1,427 @@
+Metadata-Version: 2.3
+Name: atp-protocol
+Version: 1.4.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
+Author: The Swarm Corporation
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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: cryptography
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: loguru
+Requires-Dist: pydantic
+Requires-Dist: python-dotenv
+Requires-Dist: setuptools
+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
+Description-Content-Type: text/markdown
+
+# ATP: Agent Trade Protocol
+
+> The premier agent-to-agent payment protocol and foundational framework to empower the agent economy.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-swarms.ai-blue)](https://docs.swarms.ai/docs/atp/overview)
+
+## Overview
+
+ATP (Agent Trade Protocol) is the premier agent-to-agent payment protocol that will be the foundational framework to empower the agent economy. Designed to overcome x402's issues and make agent-to-agent payments dynamic and simple, ATP enables automatic payment processing for agent services on the Solana blockchain. The protocol provides a middleware layer that automatically deducts payments from user wallets based on token usage, ensuring secure and transparent transactions.
+
+### Key Features
+
+- **Security**: Response encryption ensures users cannot access output until payment is confirmed on-chain
+- **Automation**: Zero-configuration payment processing through middleware integration
+- **Decentralization**: All payments executed on Solana blockchain with full transaction visibility
+- **Format Flexibility**: Supports multiple usage formats (OpenAI, Anthropic, Google, etc.) automatically
+- **Transparency**: Automatic payment splitting between treasury and recipient wallets
+
+## Architecture
+
+ATP Protocol operates through three main components:
+
+1. **Settlement Service (Facilitator)**: Centralized service handling all settlement logic, usage parsing, payment calculation, and blockchain transaction execution
+2. **Middleware**: FastAPI middleware that intercepts API responses, extracts usage data, encrypts responses, executes payments, and decrypts responses only after payment confirmation
+3. **Client**: User-facing client that simplifies making requests to ATP-protected endpoints and interacting with the settlement service
+
+### Request Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+    participant Middleware
+    participant SettlementService
+    participant Solana
+
+    Client->>Server: POST /v1/chat<br/>(with wallet key)
+    Server->>Server: Process request
+    Server->>Middleware: Response with usage data
+    Middleware->>Middleware: Encrypt response
+    Middleware->>SettlementService: Parse usage & calculate payment
+    SettlementService->>SettlementService: Calculate payment amount
+    SettlementService->>Solana: Create & sign transaction
+    Solana-->>SettlementService: Transaction confirmed
+    SettlementService-->>Middleware: Payment confirmed (tx signature)
+    Middleware->>Middleware: Decrypt response
+    Middleware->>Client: Return decrypted response<br/>(with settlement details)
+```
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install atp-protocol
+```
+
+### Server Setup (5 minutes)
+
+Add ATP middleware to your FastAPI server:
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from atp.middleware import ATPSettlementMiddleware
+from atp.schemas import PaymentToken
+
+app = FastAPI(title="My ATP-Protected API")
+
+# Add ATP Settlement Middleware
+app.add_middleware(
+    ATPSettlementMiddleware,
+    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
+    recipient_pubkey="YourSolanaWalletPublicKeyHere",  # Your wallet
+    payment_token=PaymentToken.SOL,  # SOL or USDC
+    wallet_private_key_header="x-wallet-private-key",
+    require_wallet=True,
+)
+
+@app.post("/v1/chat")
+async def chat(request: dict):
+    """Agent endpoint with automatic payment processing."""
+    message = request.get("message", "")
+    
+    # Agent logic implementation
+    response_text = "Agent response here"
+    
+    # Return response with usage data
+    # Middleware handles payment processing automatically
+    return JSONResponse(content={
+        "response": response_text,
+        "usage": {
+            "input_tokens": 100,
+            "output_tokens": 50,
+            "total_tokens": 150
+        }
+    })
+```
+
+### Client Usage
+
+```python
+from atp.client import ATPClient
+
+# Initialize client with wallet
+client = ATPClient(
+    wallet_private_key="[1,2,3,...]",  # Your wallet private key
+    settlement_service_url="https://facilitator.swarms.world"
+)
+
+# Make request with automatic payment processing
+response = await client.post(
+    url="https://api.example.com/v1/chat",
+    json={"message": "Hello!"}
+)
+
+print(response["response"])  # Agent output
+print(response["atp_settlement"])  # Payment details
+```
+
+## Examples
+
+Below is a comprehensive table of example integrations and usage:
+
+### Framework Integrations
+
+| Category                  | Example Link                                             | Description                            |
+|---------------------------|---------------------------------------------------------|----------------------------------------|
+| **Framework Integration** | [Swarms Framework](./examples/tutorials/swarms/)        | Enterprise multi-agent orchestration   |
+| **Framework Integration** | [LangChain](./examples/tutorials/langchain/)            | Popular Python LLM framework           |
+| **Framework Integration** | [AutoGen](./examples/tutorials/autogen/)                | Microsoft's multi-agent framework      |
+| **Framework Integration** | [CrewAI](./examples/tutorials/crewai/)                  | Multi-agent orchestration              |
+| **Framework Integration** | [Anthropic](./examples/tutorials/anthropic/)            | Claude API integration                 |
+
+### Client & Server Example Scripts
+
+| Category             | Example Link                                                        | Description                                |
+|----------------------|---------------------------------------------------------------------|--------------------------------------------|
+| **Client Example**   | [Health Check](./examples/client/example_health_check.py)           | Check settlement service status            |
+| **Client Example**   | [Parse Usage](./examples/client/example_parse_usage.py)             | Parse usage from various formats           |
+| **Client Example**   | [Calculate Payment](./examples/client/example_calculate_payment.py) | Calculate payment without executing        |
+| **Client Example**   | [Execute Settlement](./examples/client/example_settle.py)           | Direct settlement execution                |
+| **Client Example**   | [Make Request](./examples/client/example_request.py)                | Request ATP-protected endpoints            |
+| **Server Example**   | [Basic Example](./examples/server/example.py)                      | Simple middleware setup                    |
+| **Server Example**   | [Full Flow](./examples/server/full_flow_example.py)                | Complete payment flow                      |
+| **Server Example**   | [Settlement Service](./examples/server/settlement_service_example.py) | Direct service usage                     |
+
+See [examples/README.md](./examples/README.md) for complete documentation.
+
+
+## Security Features
+
+| Feature                | Description                                                                                                                                         |
+|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Response Encryption**    | Agent responses are **encrypted before payment verification**, ensuring users cannot see output until payment is confirmed on-chain.                 |
+| **Payment Verification**   | Responses are only decrypted after successful blockchain transaction confirmation (`status="paid"` with valid transaction signature).                  |
+| **Error Handling**         | Failed payments result in encrypted responses with error details, preventing unauthorized access to agent output.                                   |
+
+
+## Payment Structure
+
+Payments are automatically split between:
+
+- **Treasury**: Receives processing fee (default 5%, configured on settlement service)
+- **Recipient**: Receives remainder (95% by default) - your wallet specified via `recipient_pubkey`
+
+### Supported Payment Tokens
+
+- **SOL** (Solana native token)
+- **USDC** (USD Coin on Solana)
+
+## Usage Data Formats
+
+The middleware automatically supports multiple usage formats:
+
+### OpenAI Format
+
+```json
+{
+  "usage": {
+    "prompt_tokens": 100,
+    "completion_tokens": 50,
+    "total_tokens": 150
+  }
+}
+```
+
+### Anthropic Format
+
+```json
+{
+  "usage": {
+    "input_tokens": 100,
+    "output_tokens": 50
+  }
+}
+```
+
+### Google/Gemini Format
+
+```json
+{
+  "usageMetadata": {
+    "promptTokenCount": 100,
+    "candidatesTokenCount": 50,
+    "totalTokenCount": 150
+  }
+}
+```
+
+The settlement service automatically detects and parses these formats, so you can use any format your agent API returns.
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Settlement Service
+ATP_SETTLEMENT_URL="https://facilitator.swarms.world"  # Default
+ATP_SETTLEMENT_TIMEOUT=300.0  # 5 minutes (default)
+
+# Encryption (optional - generates new key if not set)
+ATP_ENCRYPTION_KEY="base64-encoded-fernet-key"
+```
+
+### Middleware Configuration
+
+```python
+app.add_middleware(
+    ATPSettlementMiddleware,
+    allowed_endpoints=["/v1/chat"],  # Endpoints to protect
+    input_cost_per_million_usd=10.0,  # Pricing
+    output_cost_per_million_usd=30.0,
+    recipient_pubkey="YourWalletPublicKey",  # Required
+    payment_token=PaymentToken.SOL,  # SOL or USDC
+    wallet_private_key_header="x-wallet-private-key",
+    require_wallet=True,  # Require wallet for payment
+    settlement_service_url="https://facilitator.swarms.world",
+    settlement_timeout=300.0,
+    fail_on_settlement_error=False,  # Graceful error handling
+)
+```
+
+## API Reference
+
+### Middleware
+
+The `ATPSettlementMiddleware` class provides automatic payment processing for FastAPI endpoints.
+
+**Key Features:**
+
+- Automatic usage parsing from multiple formats
+- Response encryption before payment
+- Payment execution via settlement service
+- Response decryption after payment confirmation
+
+See [Middleware Documentation](./atp/middleware.py) for complete API reference.
+
+### Client
+
+The `ATPClient` class provides a simple interface for:
+
+- Making requests to ATP-protected endpoints
+- Interacting with the settlement service directly
+- Parsing usage data
+- Calculating payments
+- Executing settlements
+
+See [Client Documentation](./atp/client.py) for complete API reference.
+
+### Settlement Service
+
+The settlement service (facilitator) handles:
+
+- Usage parsing from various formats
+- Payment calculation
+- Blockchain transaction creation and execution
+- Transaction confirmation
+
+See [Settlement Service Documentation](https://docs.swarms.ai/docs/atp/facilitator) for complete API reference.
+
+
+## Development
+
+### Requirements
+
+- Python 3.10+
+- FastAPI (for middleware)
+- Solana wallet (for payments)
+
+### Installation from Source
+
+```bash
+git clone https://github.com/The-Swarm-Corporation/ATP-Protocol.git
+cd ATP-Protocol
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Code Quality
+
+```bash
+# Format code
+black .
+
+# Lint code
+ruff check .
+```
+
+
+## Error Handling
+
+### Missing Wallet Key
+
+If wallet private key is missing and `require_wallet=True`:
+
+```json
+{
+  "detail": "Missing wallet private key in header: x-wallet-private-key"
+}
+```
+
+Status: `401 Unauthorized`
+
+### Payment Failure
+
+If payment fails and `fail_on_settlement_error=False` (default):
+
+```json
+{
+  "response": "encrypted_data_here",
+  "response_encrypted": true,
+  "atp_settlement": {
+    "error": "Settlement failed",
+    "detail": "Insufficient funds",
+    "status_code": 400
+  },
+  "atp_settlement_status": "failed",
+  "atp_message": "Agent response is encrypted. Payment required to decrypt."
+}
+```
+
+The response remains encrypted until payment succeeds.
+
+## Best Practices
+
+1. **Wallet Security**: Never log or persist wallet private keys. Use them only in-memory for transaction signing.
+
+2. **Error Handling**: Use `fail_on_settlement_error=False` for graceful degradation. Check `atp_settlement_status` in responses to handle payment failures appropriately.
+
+3. **Timeout Configuration**: Increase `settlement_timeout` if you experience timeout errors. Blockchain confirmation can take time depending on network conditions.
+
+4. **Usage Data**: Always include accurate token counts in your responses. Middleware skips settlement if usage data cannot be parsed.
+
+5. **Testing**: Use testnet wallets and small amounts for testing. Verify transactions on Solana explorer before production deployment.
+
+6. **Monitoring**: Monitor `atp_settlement_status` in responses to track payment success rates and identify potential issues.
+
+## Resources
+
+| Resource                         | Description                        |
+|-----------------------------------|------------------------------------|
+| [Full Documentation](https://docs.swarms.ai/docs/atp/overview)         | Complete API documentation         |
+| [Settlement Service API](https://docs.swarms.ai/docs/atp/facilitator)  | Facilitator API reference          |
+| [Middleware Reference](https://docs.swarms.ai/docs/atp/middleware)      | Middleware configuration           |
+| [Client Reference](https://docs.swarms.ai/docs/atp/client)             | Client API reference               |
+| [ATP Vision](https://docs.swarms.ai/docs/atp/vision)                   | Protocol vision and roadmap        |
+
+
+## Contributing
+
+Contributions are welcome. Please read our contributing guidelines and submit pull requests for review.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+Built by [The Swarm Corporation](https://swarms.ai) to enable agent-to-agent commerce on the blockchain.
+
+---
+
+For additional information, see the [examples directory](./examples/) or the [complete documentation](https://docs.swarms.ai/docs/atp/overview).
+

atp_protocol-1.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+atp/__init__.py,sha256=xCYA1cb5xw9IxqFsB1fC7jXBE48bHgKBq4ZhyW9AFyY,459
+atp/client.py,sha256=GUZZ81PaJMia7mK_SS3uzU3qCpg0ChoLVYmQIRrfxQ8,24510
+atp/config.py,sha256=tY_S8aXrTbZJ4WIRQIXhIiXiRjeYT6_5Jh47QwZ1gnw,3013
+atp/encryption.py,sha256=kgyhjf8qGq3oZjDIxGHzOlc5KOLPTi7nv0RApPZGk7o,5341
+atp/middleware.py,sha256=d3Sxj66qMr2AX6hxZNFHaiqpdyXafEpf1McWOJVaklo,29546
+atp/schemas.py,sha256=29VtWKxtwlllAUOx2hoSEESpVWoKANdybOoTiTbFhnc,12344
+atp/settlement_client.py,sha256=7e_271Bx1ZT2YzZH0HjAOx1krDXgPhMWVakRKsMMS3k,31395
+atp_protocol-1.4.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+atp_protocol-1.4.0.dist-info/METADATA,sha256=rLnBQhoFlqGx9lxHDJXJm6zDDdIGVlXx0Ds4mpMYX24,15887
+atp_protocol-1.4.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+atp_protocol-1.4.0.dist-info/RECORD,,