ATP Protocol skill – servers and clients

Use this skill when you need to create or modify ATP (Agent Trade Protocol) servers or clients. ATP enables agent-to-agent payments on Solana: middleware on the server charges by token usage; the client pays and receives decrypted responses after settlement.

Documentation index: For full Claude Code docs (skills, agents, etc.), fetch: https://code.claude.com/docs/llms.txt

---

1. Creating an ATP server

1.1 Minimal FastAPI server with ATP middleware

• Use FastAPI and add ATPSettlementMiddleware so selected endpoints are paid per use.
• Endpoints must return usage data (input/output token counts) in a supported format so the middleware can compute and execute payment.

Imports and app:

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 middleware (required args):

app.add_middleware(
    ATPSettlementMiddleware,
    allowed_endpoints=["/v1/chat", "/v1/completions"],  # exact path list
    input_cost_per_million_usd=10.0,   # USD per million input tokens
    output_cost_per_million_usd=30.0,  # USD per million output tokens
    recipient_pubkey="YourSolanaWalletPublicKeyHere",  # required; receives payment
    payment_token=PaymentToken.SOL,    # SOL or PaymentToken.USDC
)

Optional middleware args:

• wallet_private_key_header: Header name for wallet key (default "x-wallet-private-key").
• skip_preflight: Skip Solana preflight (default False).
• commitment: Solana commitment (default "confirmed").
• settlement_service_url: Facilitator URL (default from ATP_SETTLEMENT_URL or https://facilitator.swarms.world).
• fail_on_settlement_error: If True, raise on settlement failure (default False).
• settlement_timeout: Timeout in seconds (default from env or 300.0).

Protected endpoint example (return usage):

@app.post("/v1/chat")
async def chat(request: dict):
    message = request.get("message", "")
    # Your agent logic
    response_text = "Agent response here"
    return JSONResponse(content={
        "response": response_text,
        "usage": {
            "input_tokens": 100,
            "output_tokens": 50,
            "total_tokens": 150
        }
    })

Supported usage formats (middleware/settlement parses these):

• OpenAI: usage.prompt_tokens, usage.completion_tokens, usage.total_tokens
• Anthropic: usage.input_tokens, usage.output_tokens
• Google/Gemini: usageMetadata.promptTokenCount, candidatesTokenCount, totalTokenCount

Paths not in allowed_endpoints are not charged (e.g. /v1/health).

Run server:

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

1.2 Server checklist

• Set recipient_pubkey to the Solana wallet that should receive payments.
• Ensure every protected handler returns a body that includes one of the supported usage structures.
• Optional: set ATP_ENCRYPTION_KEY (base64 Fernet) for consistent response encryption across restarts; otherwise a key is generated per process.
• For production: use fail_on_settlement_error=False and check atp_settlement_status on the client; never log or persist wallet private keys.

---

2. Creating an ATP client

2.1 Client for ATP-protected endpoints

Use ATPClient to call ATP-protected APIs: it adds the wallet header and can decrypt responses after payment.

Imports and constructor:

from atp.client import ATPClient

client = ATPClient(
    wallet_private_key="[1,2,3,...]",  # or base58 string; required for payment
    settlement_service_url="https://facilitator.swarms.world",  # optional
    settlement_timeout=300.0,           # optional
    wallet_private_key_header="x-wallet-private-key",  # optional
    verbose=False,                     # optional, for debugging
)

Making a paid request (POST):

import asyncio

response = asyncio.run(client.post(
    url="https://api.example.com/v1/chat",
    json={"message": "Hello!"},
    # wallet_private_key=...,  # optional override per request
    # auto_decrypt=True,       # default True
))
print(response["response"])        # agent output
print(response.get("atp_settlement"))   # payment details
print(response.get("atp_settlement_status"))  # e.g. "paid" or "failed"

GET and other methods:

response = await client.get(url="https://api.example.com/v1/status")
response = await client.request("PUT", url=some_url, json=payload)

If auto_decrypt=True (default), the client decrypts encrypted response bodies when payment has succeeded.

2.2 Client for settlement service (facilitator) only

Use the same ATPClient for facilitator operations without calling an ATP-protected API.

Health check (no wallet needed):

client = ATPClient()
health = asyncio.run(client.health_check())

Parse usage (no wallet needed):

from atp.client import ATPClient
import asyncio

client = ATPClient()
usage = asyncio.run(client.parse_usage({"usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150}}))
# usage -> e.g. {"input_tokens": 100, "output_tokens": 50, "total_tokens": 150}

Calculate payment (no blockchain call):

from atp.schemas import PaymentToken

payment = await client.calculate_payment(
    usage={"input_tokens": 1000, "output_tokens": 500},
    input_cost_per_million_usd=10.0,
    output_cost_per_million_usd=30.0,
    recipient_pubkey="RecipientPublicKeyHere",
    payment_token=PaymentToken.SOL,
)

Execute settlement (spends SOL/USDC):

result = await client.settle(
    usage={"input_tokens": 1000, "output_tokens": 500},
    input_cost_per_million_usd=10.0,
    output_cost_per_million_usd=30.0,
    recipient_pubkey="RecipientPublicKeyHere",
    payment_token=PaymentToken.SOL,
)
# result includes tx_signature, status, etc.

2.3 Client checklist

• For paid endpoint calls or settle(), provide wallet_private_key (constructor or per call).
• Wallet key format: JSON array string "[1,2,3,...]" or base58 keypair string.
• Check atp_settlement_status in responses to handle failures; never log or store private keys.
• Env vars (optional): ATP_SETTLEMENT_URL, ATP_SETTLEMENT_TIMEOUT, ATP_WALLET_PRIVATE_KEY, ATP_ENDPOINT_URL.

---

3. Project layout and references

• Server examples: examples/server/example.py, examples/server/full_flow_example.py
• Client examples: examples/client/example_request.py, examples/client/example_settle.py, examples/client/example_health_check.py
• API reference: atp/middleware.py (middleware), atp/client.py (client), atp/schemas.py (PaymentToken, config models)
• Docs: README.md in repo; full docs at https://docs.swarms.ai/docs/atp/overview

When creating or editing ATP servers or clients, follow the patterns above and use the existing examples and atp package as the source of truth.