traia-iatp 0.1.2__py3-none-any.whl → 0.1.67__py3-none-any.whl

traia_iatp/core/models.py

@@ -21,7 +21,7 @@ class MCPServer(BaseModel):
     capabilities: List[str] = Field(default_factory=list, description="List of capabilities/APIs")
     metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
     
-    class Config:
+    class ConfigDict:
         json_encoders = {HttpUrl: str}
 
 
@@ -105,6 +105,12 @@ class UtilityAgent(BaseModel):
     github_repo: Optional[str] = Field(None, description="GitHub repository URL")
     cloud_run_url: Optional[str] = Field(None, description="Cloud Run deployment URL")
     
+    # X402 payment configuration
+    contract_address: Optional[str] = Field(None, description="On-chain utility agent contract address")
+    operator_address: Optional[str] = Field(None, description="Operator address for signing attestations")
+    d402_enabled: bool = Field(default=False, description="Whether d402 payments are enabled")
+    d402_config: Optional[Dict[str, Any]] = Field(None, description="X402 payment configuration")
+    
     # Search and discovery
     search_text: Optional[str] = Field(None, description="Concatenated searchable text")
     tags: List[str] = Field(default_factory=list, description="Tags for search and categorization")
@@ -113,7 +119,7 @@ class UtilityAgent(BaseModel):
     updated_at: datetime = Field(default_factory=datetime.utcnow)
     metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
     
-    class Config:
+    class ConfigDict:
         json_encoders = {HttpUrl: str, datetime: lambda v: v.isoformat()}
 
 
@@ -124,6 +130,9 @@ class UtilityAgentRegistryEntry(BaseModel):
     name: str = Field(..., description="Name for discovery")
     description: str = Field(..., description="Description for search")
     
+    # MCP server reference
+    mcp_server_id: Optional[str] = Field(None, description="ID of the MCP server this agent wraps")
+    
     # Base URL for the agent - all endpoints are derived from this
     base_url: Optional[str] = Field(None, description="Base URL of the deployed agent")
     
@@ -135,6 +144,11 @@ class UtilityAgentRegistryEntry(BaseModel):
     skills: List[AgentSkill] = Field(default_factory=list, description="Detailed skills from agent card")
     tags: List[str] = Field(default_factory=list, description="Tags for search")
     
+    # X402 payment information
+    contract_address: Optional[str] = Field(None, description="On-chain utility agent contract address")
+    d402_enabled: bool = Field(default=False, description="Whether d402 payments are enabled")
+    d402_payment_info: Optional[Dict[str, Any]] = Field(None, description="X402 payment information")
+    
     # Search optimization
     search_text: Optional[str] = Field(None, description="Full text for search")
     
@@ -143,7 +157,7 @@ class UtilityAgentRegistryEntry(BaseModel):
     last_health_check: Optional[datetime] = Field(None, description="Last successful health check")
     is_active: bool = Field(default=True, description="Whether the agent is active")
     
-    class Config:
+    class ConfigDict:
         json_encoders = {HttpUrl: str, datetime: lambda v: v.isoformat()}
 
 

traia_iatp/d402/MIDDLEWARE_ARCHITECTURE.md

@@ -0,0 +1,205 @@
+# D402 Payment Middleware Architecture
+
+## Overview
+
+The D402 payment protocol provides two middleware implementations to support different server types:
+
+1. **`d402/starlette_middleware.py`** - MCP-specific (legacy, backwards compatible)
+2. **`d402/servers/starlette.py`** - Generalized (recommended for new code)
+
+## Middleware Comparison
+
+| Feature | `starlette_middleware.py` | `servers/starlette.py` |
+|---------|--------------------------|------------------------|
+| **Use Case** | MCP servers only | Any Starlette server |
+| **Endpoint Patterns** | `/mcp` only | `/mcp`, `/`, `*`, custom |
+| **Configuration** | `tool_payment_configs` only | `tool_payment_configs` OR `price`+`endpoint_patterns` |
+| **Type Safety** | Dict-based configs | Supports `TokenAmount`/`TokenAsset` objects |
+| **Status** | Maintained for compatibility | Recommended for new code |
+
+## Usage Patterns
+
+### Pattern 1: MCP Servers (with decorators)
+
+MCP servers use decorators like `@require_payment_for_tool()` which auto-generate payment configs.
+
+```python
+from traia_iatp.d402.starlette_middleware import D402PaymentMiddleware
+from traia_iatp.d402.payment_introspection import extract_payment_configs_from_mcp
+
+# Extract configs from decorators
+tool_payment_configs = extract_payment_configs_from_mcp(mcp, SERVER_ADDRESS)
+
+# Add middleware
+app.add_middleware(
+    D402PaymentMiddleware,
+    tool_payment_configs=tool_payment_configs,
+    server_address=SERVER_ADDRESS,
+    requires_auth=True,
+    internal_api_key=API_KEY
+)
+```
+
+**Files using this pattern:**
+- `mcp/templates/server.py.j2` (MCP server template)
+- Generated MCP servers (e.g., `coingecko-api-mcp-server`)
+
+### Pattern 2: A2A Servers (with price + patterns)
+
+A2A servers don't use decorators - they specify price and endpoint patterns directly.
+
+```python
+from traia_iatp.d402.servers import D402PaymentMiddleware
+from traia_iatp.d402.types import TokenAmount, TokenAsset, EIP712Domain
+
+# Create price with proper types
+price = TokenAmount(
+    amount="10000",  # 0.01 USDC
+    asset=TokenAsset(
+        address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+        decimals=6,
+        network="sepolia",
+        eip712=EIP712Domain(
+            name="IATPWallet",
+            version="1"
+        )
+    )
+)
+
+# Add middleware with price + patterns
+app.add_middleware(
+    D402PaymentMiddleware,
+    price=price,
+    endpoint_patterns=["/"],  # Protect root endpoint
+    server_address=CONTRACT_ADDRESS,
+    description="A2A request",
+    requires_auth=False  # Payment-only (no API keys)
+)
+```
+
+**Files using this pattern:**
+- `server/templates/__main__.py.j2` (A2A utility agent template)
+- Generated utility agents
+
+### Pattern 3: General Servers (with tool configs)
+
+General servers can also use the generalized middleware with pre-built configs.
+
+```python
+from traia_iatp.d402.servers import D402PaymentMiddleware
+
+# Build configs manually
+tool_payment_configs = {
+    "/api/analyze": {
+        "price_wei": "10000",
+        "token_address": "0x...",
+        # ... full config
+    }
+}
+
+# Add middleware
+app.add_middleware(
+    D402PaymentMiddleware,
+    tool_payment_configs=tool_payment_configs,
+    server_address=SERVER_ADDRESS
+)
+```
+
+## Endpoint Pattern Matching
+
+The generalized middleware supports multiple endpoint patterns:
+
+| Pattern | Example | Matches |
+|---------|---------|---------|
+| **MCP** | `/mcp` with `tools/call` | MCP tool calls: `/mcp/tools/{tool_name}` |
+| **A2A** | `/` | A2A JSON-RPC at root path |
+| **Exact Match** | `/api/analyze` | Only `/api/analyze` |
+| **Wildcard** | `*` | All POST endpoints |
+
+## Migration Guide
+
+### Existing MCP Servers
+**No action needed** - continue using `starlette_middleware.py`
+
+### New MCP Servers
+Can use either middleware (both work the same for MCP)
+
+### New A2A/Utility Servers
+**Must use** `servers/starlette.py` with `price` + `endpoint_patterns`
+
+### Custom Servers
+**Recommended** to use `servers/starlette.py` for flexibility
+
+## Code Organization
+
+```
+traia_iatp/
+├── d402/
+│   ├── starlette_middleware.py   # MCP-specific (legacy)
+│   ├── servers/
+│   │   ├── __init__.py
+│   │   └── starlette.py          # Generalized (recommended)
+│   ├── types.py                  # TokenAmount, TokenAsset, etc.
+│   └── ...
+├── mcp/
+│   └── templates/
+│       └── server.py.j2          # Uses starlette_middleware.py
+└── server/
+    └── templates/
+        └── __main__.py.j2        # Uses servers/starlette.py
+```
+
+## Key Differences
+
+### Configuration Building
+
+**MCP (decorator-based):**
+```python
+# Configs extracted from @require_payment_for_tool decorators
+tool_payment_configs = extract_payment_configs_from_mcp(mcp, SERVER_ADDRESS)
+# Result: {"tool_name": {"price_wei": "...", "token_address": "...", ...}}
+```
+
+**A2A (price-based):**
+```python
+# Price defined with type-safe objects
+price = TokenAmount(amount="10000", asset=TokenAsset(...))
+# Middleware builds configs internally: {"/": {"price_wei": "10000", ...}}
+```
+
+### Endpoint Protection
+
+**MCP:**
+- Protects individual tools within `/mcp` endpoint
+- Each tool can have different prices
+- Example: `/mcp/tools/get_price` costs 0.001 USDC
+
+**A2A:**
+- Protects entire endpoint (usually `/`)
+- Single price for all methods on that endpoint
+- Example: All JSON-RPC methods to `/` cost 0.01 USDC
+
+## Testing
+
+Both middlewares are tested through their respective server types:
+
+**MCP Servers:**
+```bash
+# Test MCP server with D402
+uv run pytest automated-tests/mcp/coingecko-api-mcp-server/ -v
+```
+
+**A2A Servers:**
+```bash
+# Test utility agent with D402
+uv run pytest automated-tests/agents/coingecko-utility-agent/ -v
+```
+
+## Summary
+
+- **Use `starlette_middleware.py`** for MCP servers (backwards compatible)
+- **Use `servers/starlette.py`** for A2A servers and new code (flexible, type-safe)
+- Both middlewares share the same core payment validation logic
+- Both support facilitator integration for settlement
+- The generalized version is recommended for all new development
+

traia_iatp/d402/PRICE_BUILDER_USAGE.md

@@ -0,0 +1,249 @@
+# D402PriceBuilder - Simple Price Creation
+
+## Overview
+
+`D402PriceBuilder` is a helper class that simplifies creating `TokenAmount` objects for D402 payment configuration. It works with **any token** - just initialize it with your token configuration.
+
+## Basic Usage
+
+```python
+from traia_iatp.d402 import D402PriceBuilder
+
+# Initialize with YOUR token configuration (any token!)
+builder = D402PriceBuilder(
+    token_address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",  # Your token address
+    token_decimals=6,                                              # Your token decimals
+    network="sepolia",                                             # Your network
+    token_symbol="USDC"                                            # Your token symbol
+)
+
+# Create prices easily
+price_001 = builder.create_price(0.001)  # $0.001
+price_01 = builder.create_price(0.01)    # $0.01
+price_05 = builder.create_price(0.05)    # $0.05
+```
+
+## Examples with Different Tokens
+
+### USDC (6 decimals)
+```python
+usdc_builder = D402PriceBuilder(
+    token_address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    token_decimals=6,
+    network="sepolia",
+    token_symbol="USDC"
+)
+
+price = usdc_builder.create_price(0.01)
+# Result: TokenAmount(amount="10000", ...) → 0.01 * 10^6 = 10000
+```
+
+### TRAIA (18 decimals)
+```python
+traia_builder = D402PriceBuilder(
+    token_address="0xYourTraiaTokenAddress...",
+    token_decimals=18,  # Standard ERC20
+    network="base-mainnet",
+    token_symbol="TRAIA"
+)
+
+price = traia_builder.create_price(0.01)
+# Result: TokenAmount(amount="10000000000000000", ...) → 0.01 * 10^18
+```
+
+### Any Custom Token
+```python
+custom_builder = D402PriceBuilder(
+    token_address="0xYourCustomToken...",
+    token_decimals=8,  # Your token's decimals
+    network="arbitrum-mainnet",
+    token_symbol="CUSTOM"
+)
+
+price = custom_builder.create_price(0.05)
+# Result: TokenAmount(amount="5000000", ...) → 0.05 * 10^8 = 5000000
+```
+
+## Usage in Servers
+
+### MCP Servers
+```python
+from traia_iatp.d402 import D402PriceBuilder
+from traia_iatp.d402.servers.mcp import require_payment_for_tool
+
+# Initialize builder from environment
+builder = D402PriceBuilder(
+    token_address=os.getenv("TOKEN_ADDRESS"),
+    token_decimals=int(os.getenv("TOKEN_DECIMALS", "6")),
+    network=os.getenv("NETWORK", "sepolia"),
+    token_symbol=os.getenv("TOKEN_SYMBOL", "USDC")
+)
+
+# Use in decorators - clean and simple!
+@mcp.tool()
+@require_payment_for_tool(
+    price=builder.create_price(0.001),  # $0.001
+    description="Quick check"
+)
+async def quick_check(context):
+    pass
+
+@mcp.tool()
+@require_payment_for_tool(
+    price=builder.create_price(0.05),  # $0.05 - different price!
+    description="Deep analysis"
+)
+async def deep_analysis(context):
+    pass
+```
+
+### A2A Servers
+```python
+from traia_iatp.d402 import D402PriceBuilder
+from traia_iatp.d402.servers.starlette import _build_payment_config
+
+# Initialize builder from environment
+builder = D402PriceBuilder(
+    token_address=os.getenv("D402_TOKEN_ADDRESS"),
+    token_decimals=int(os.getenv("D402_TOKEN_DECIMALS", "6")),
+    network=os.getenv("D402_NETWORK", "sepolia"),
+    token_symbol=os.getenv("D402_TOKEN_SYMBOL", "USDC")
+)
+
+# Create price
+d402_token_amount = builder.create_price(float(os.getenv("D402_PRICE_USD", "0.01")))
+
+# Build endpoint config
+endpoint_payment_configs = {
+    "/": _build_payment_config(
+        price=d402_token_amount,
+        server_address=contract_address,
+        description="A2A request"
+    )
+}
+```
+
+### General FastAPI Servers
+```python
+from fastapi import FastAPI
+from traia_iatp.d402 import D402PriceBuilder
+from traia_iatp.d402.servers import require_payment, extract_payment_configs
+
+app = FastAPI()
+
+# Initialize builder from environment
+builder = D402PriceBuilder(
+    token_address=os.getenv("TOKEN_ADDRESS"),
+    token_decimals=int(os.getenv("TOKEN_DECIMALS")),
+    network=os.getenv("NETWORK"),
+    token_symbol=os.getenv("TOKEN_SYMBOL")
+)
+
+# Use in decorators
+@app.post("/analyze")
+@require_payment(
+    price=builder.create_price(0.01),
+    endpoint_path="/analyze",
+    description="Analysis"
+)
+async def analyze():
+    pass
+
+@app.post("/premium")
+@require_payment(
+    price=builder.create_price(0.10),  # Different price!
+    endpoint_path="/premium",
+    description="Premium analysis"
+)
+async def premium():
+    pass
+```
+
+## Benefits
+
+### Before (Manual TokenAmount creation)
+```python
+# Repetitive, error-prone
+price1 = TokenAmount(
+    amount="10000",
+    asset=TokenAsset(
+        address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+        decimals=6,
+        network="sepolia",
+        symbol="USDC",
+        eip712=EIP712Domain(name="IATPWallet", version="1")
+    )
+)
+
+price2 = TokenAmount(
+    amount="50000",  # Have to calculate: 0.05 * 10^6
+    asset=TokenAsset(
+        address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",  # Same config repeated!
+        decimals=6,
+        network="sepolia",
+        symbol="USDC",
+        eip712=EIP712Domain(name="IATPWallet", version="1")
+    )
+)
+```
+
+### After (With D402PriceBuilder)
+```python
+# Clean, simple, reusable
+builder = D402PriceBuilder(
+    token_address="0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
+    token_decimals=6,
+    network="sepolia",
+    token_symbol="USDC"
+)
+
+price1 = builder.create_price(0.01)   # Simple!
+price2 = builder.create_price(0.05)   # No calculation needed!
+```
+
+## Methods
+
+### `create_price(amount_usd: float) -> TokenAmount`
+
+Create price from USD amount. Automatically converts to atomic units.
+
+```python
+builder = D402PriceBuilder(token_decimals=6, ...)
+
+builder.create_price(0.01)   # → "10000" wei (0.01 * 10^6)
+builder.create_price(0.001)  # → "1000" wei
+builder.create_price(1.00)   # → "1000000" wei
+```
+
+### `create_price_wei(amount_wei: str) -> TokenAmount`
+
+Create price from exact atomic units (when you don't want USD conversion).
+
+```python
+builder = D402PriceBuilder(token_decimals=6, ...)
+
+builder.create_price_wei("10000")  # Exactly 10000 atomic units
+builder.create_price_wei("1234")   # Exactly 1234 atomic units
+```
+
+## Token Decimals Reference
+
+| Token | Decimals | Example: $0.01 |
+|-------|----------|----------------|
+| USDC | 6 | 10,000 |
+| DAI | 18 | 10,000,000,000,000,000 |
+| TRAIA | 18 | 10,000,000,000,000,000 |
+| WBTC | 8 | 1,000,000 |
+
+The builder handles the conversion automatically - you just specify the USD amount!
+
+## Summary
+
+✅ **Generic** - Works with any token  
+✅ **Simple** - Initialize once, create many prices  
+✅ **Type-safe** - Returns proper `TokenAmount` objects  
+✅ **No calculation** - Automatically converts USD to atomic units  
+✅ **Reusable** - One builder for all your endpoints  
+
+**No more manual TokenAmount creation!**
+