ATP Settlement Middleware

​

Overview

​

Key Features

• Automatic payment deduction based on token usage
• Response encryption until payment confirmation
• Support for multiple usage data formats (OpenAI, Anthropic, Google, etc.)
• Automatic payment splitting (treasury fee + recipient payment)
• Centralized settlement logic via settlement service
• Configurable error handling modes

​

Installation

from atp.middleware import ATPSettlementMiddleware
from atp.schemas import PaymentToken

​

Basic Usage

from fastapi import FastAPI
from atp.middleware import ATPSettlementMiddleware
from atp.schemas import PaymentToken

app = FastAPI()

app.add_middleware(
    ATPSettlementMiddleware,
    allowed_endpoints=["/v1/chat", "/v1/completions"],
    input_cost_per_million_usd=10.0,
    output_cost_per_million_usd=30.0,
    recipient_pubkey="YourPublicKeyHere",  # Required
    payment_token=PaymentToken.SOL,
    wallet_private_key_header="x-wallet-private-key",
    settlement_service_url="https://facilitator.swarms.world",
    settlement_timeout=300.0,
    fail_on_settlement_error=False,
)

​

Configuration Parameters

​

Required Parameters

​

allowed_endpoints

• Type: List[str]
• Description: List of endpoint paths to apply settlement to (e.g., ["/v1/chat"]). Supports exact path matches only.
• Example: ["/v1/chat", "/v1/completions"]

​

input_cost_per_million_usd

• Type: float
• Description: Cost per million input tokens in USD.
• Example: 10.0 (means $10 per million input tokens)

​

output_cost_per_million_usd

• Type: float
• Description: Cost per million output tokens in USD.
• Example: 30.0 (means $30 per million output tokens)

​

recipient_pubkey

• Type: str
• Description: Solana public key of the recipient wallet (the endpoint host). This wallet receives the main payment (after processing fee). Required.
• Example: "YourSolanaWalletPublicKeyHere"

​

Optional Parameters

​

wallet_private_key_header

• Type: str
• Default: "x-wallet-private-key"
• Description: HTTP header name containing the wallet private key. The private key should be in JSON array format (e.g., "[1,2,3,...]") or base58 string format.

​

payment_token

• Type: PaymentToken
• Default: PaymentToken.SOL
• Description: Token to use for payment (SOL or USDC).
• Options: PaymentToken.SOL, PaymentToken.USDC

​

skip_preflight

• Type: bool
• Default: False
• Description: Whether to skip preflight simulation for Solana transactions. Setting to True can speed up transactions but may result in failed transactions.

​

commitment

• Type: str
• Default: "confirmed"
• Description: Solana commitment level for transaction confirmation.
• Options:
  • "processed": Fastest, but may be rolled back
  • "confirmed": Recommended default, confirmed by cluster
  • "finalized": Slowest, but cannot be rolled back

​

require_wallet

• Type: bool
• Default: True
• Description: Whether to require wallet private key. If False, skips settlement when missing.

​

settlement_service_url

• Type: Optional[str]
• Default: None (uses ATP_SETTLEMENT_URL environment variable or https://facilitator.swarms.world/)
• Description: Base URL of the settlement service. The middleware always uses the settlement service for all settlement operations.

​

fail_on_settlement_error

• Type: bool
• Default: False
• Description: If True, raises HTTPException when settlement fails. If False, returns the response with settlement error info instead of failing the request.

​

settlement_timeout

• Type: Optional[float]
• Default: None (uses ATP_SETTLEMENT_TIMEOUT environment variable or 300.0)
• Description: Timeout in seconds for settlement service requests. Settlement operations may take longer due to blockchain confirmation times. Increase this value if you experience timeout errors even when payments are successfully sent.

​

Request Flow

1. Request Arrives: Request arrives at a configured endpoint
2. Wallet Extraction: Middleware extracts wallet private key from request headers
3. Endpoint Execution: Request is forwarded to the endpoint handler
4. Response Interception: Response is intercepted and parsed for usage data
5. Response Encryption: Response is encrypted to prevent unauthorized access
6. Usage Parsing: Usage data is sent to settlement service for parsing and payment calculation
7. Payment Execution: Payment transaction is executed on Solana blockchain
8. Response Decryption: Response is decrypted only after payment confirmation
9. Response Return: Response is returned to client with settlement details

​

Response Modifications

​

atp_usage

{
  "atp_usage": {
    "input_tokens": 100,
    "output_tokens": 50,
    "total_tokens": 150
  }
}

​

atp_settlement

{
  "atp_settlement": {
    "status": "paid",
    "transaction_signature": "5j7s8K9...",
    "pricing": {
      "usd_cost": 0.025,
      "input_tokens": 100,
      "output_tokens": 50,
      "input_cost_usd": 0.001,
      "output_cost_usd": 0.0015
    },
    "payment": {
      "total_amount_lamports": 1250000,
      "total_amount_sol": 0.00125,
      "total_amount_usd": 0.025,
      "treasury": {
        "amount_lamports": 62500,
        "amount_sol": 0.0000625,
        "amount_usd": 0.00125
      },
      "recipient": {
        "amount_lamports": 1187500,
        "amount_sol": 0.0011875,
        "amount_usd": 0.02375
      }
    }
  }
}

​

atp_settlement_status

• "paid": Payment succeeded and confirmed
• "failed": Payment failed
• "skipped": Payment was skipped (zero cost)

​

atp_message

{
  "atp_message": "Agent response is encrypted. Payment required to decrypt. Please provide a valid wallet private key and ensure payment succeeds."
}

​

Usage Data Parsing

• Multiple API formats (OpenAI, Anthropic, Google/Gemini, Cohere, etc.)
• Nested structures (usage.usage, meta.usage, statistics, etc.)
• Recursive parsing for deeply nested usage objects
• Normalization to standard format (input_tokens, output_tokens, total_tokens)

​

Supported Formats

​

OpenAI Format

{
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 50,
    "total_tokens": 150
  }
}

​

Anthropic Format

{
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

​

Google/Gemini Format

{
  "usageMetadata": {
    "promptTokenCount": 100,
    "candidatesTokenCount": 50,
    "totalTokenCount": 150
  }
}

​

Nested Formats

{
  "response": "...",
  "meta": {
    "usage": {
      "input_tokens": 100,
      "output_tokens": 50
    }
  }
}

​

Security Features

​

Response Encryption

• output
• response
• result
• message

​

Payment Verification

• Status must be "paid"
• Transaction signature must be present
• Transaction must be confirmed on-chain

​

Error Handling

​

Error Handling Modes

​

fail_on_settlement_error=False (Default)

{
  "response": "encrypted_data_here",
  "response_encrypted": true,
  "atp_usage": {
    "input_tokens": 100,
    "output_tokens": 50
  },
  "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."
}

​

fail_on_settlement_error=True

HTTPException(
    status_code=400,
    detail="Settlement failed: Insufficient funds"
)

​

Payment Splitting

• Treasury: Receives the processing fee (configured via SWARMS_TREASURY_PUBKEY on settlement service). Default fee percentage is 5%.
• Recipient: Receives the remainder (95% by default). This is the endpoint host’s wallet specified via recipient_pubkey.

​

Error Scenarios

​

Missing Wallet Key

{
  "detail": "Missing wallet private key in header: x-wallet-private-key"
}

​

No Usage Data

​

Encryption Failure

{
  "error": "Internal server error",
  "message": "Failed to encrypt response. Please contact support.",
  "atp_usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

​

Settlement Failure

​

Timeout Errors

​

Best Practices

1. Endpoint Selection: Only add endpoints that return usage data. Health checks and status endpoints should not use the middleware.
2. Error Handling: Use fail_on_settlement_error=False for graceful degradation. Check atp_settlement_status in responses to handle payment failures.
3. Timeout Configuration: Increase settlement_timeout if you experience timeout errors even when payments succeed. Blockchain confirmation can take 30-60 seconds or more.
4. Usage Data Accuracy: Always include accurate token counts in your responses. The middleware will skip settlement if usage data cannot be parsed.
5. Wallet Security: Never log or persist wallet private keys. They are only used in-memory for transaction signing.
6. Testing: Use testnet wallets and small amounts for testing. Verify payment transactions on Solana explorer.
7. Monitoring: Monitor atp_settlement_status in responses to track payment success rates and identify issues.

​

Advanced Usage

​

Custom Error Handling

response = await client.post(url="https://api.example.com/v1/chat", json={"message": "Hello"})

if response.get("atp_settlement_status") == "paid":
    print("Payment successful!")
    print(response["response"])  # Decrypted response
elif response.get("atp_settlement_status") == "failed":
    print("Payment failed:", response.get("atp_settlement", {}).get("detail"))
    # Response remains encrypted

​

Conditional Settlement

app.add_middleware(
    ATPSettlementMiddleware,
    allowed_endpoints=["/v1/chat"],
    input_cost_per_million_usd=10.0,
    output_cost_per_million_usd=30.0,
    recipient_pubkey="YourPublicKeyHere",
    require_wallet=False,  # Settlement is optional
)

​

Multiple Endpoints with Different Pricing

app.add_middleware(
    ATPSettlementMiddleware,
    allowed_endpoints=[
        "/v1/chat",           # Same pricing
        "/v1/completions",     # Same pricing
        "/v1/embeddings",      # Same pricing
    ],
    input_cost_per_million_usd=10.0,
    output_cost_per_million_usd=30.0,
    recipient_pubkey="YourPublicKeyHere",
)

​

Troubleshooting

​

Payment Timeouts

app.add_middleware(
    ATPSettlementMiddleware,
    # ... other config ...
    settlement_timeout=600.0,  # 10 minutes
)

​

Missing Usage Data

​

Encrypted Responses

​

Transaction Failures

• Insufficient funds in wallet
• Invalid recipient pubkey
• Network congestion
• Invalid private key format

​

API Reference

​

Class: ATPSettlementMiddleware

class ATPSettlementMiddleware(BaseHTTPMiddleware):
    def __init__(
        self,
        app: ASGIApp,
        *,
        allowed_endpoints: List[str],
        input_cost_per_million_usd: float,
        output_cost_per_million_usd: float,
        wallet_private_key_header: str = "x-wallet-private-key",
        payment_token: PaymentToken = PaymentToken.SOL,
        recipient_pubkey: Optional[str] = None,
        skip_preflight: bool = False,
        commitment: str = "confirmed",
        require_wallet: bool = True,
        settlement_service_url: Optional[str] = None,
        fail_on_settlement_error: bool = False,
        settlement_timeout: Optional[float] = None,
    ):
        ...

​

Methods

​

_should_process(path: str) -> bool

​

_extract_wallet_private_key(request: Request) -> Optional[str]

​

_parse_usage_from_response(response_body: bytes) -> Optional[Dict[str, Any]]

​

dispatch(request: Request, call_next: Callable) -> Response

​

See Also

• ATP Protocol Overview
• ATP Client Reference
• Facilitator Reference