agentclear 0.1.0

Official SDK for Agent Clear — the AI agent service marketplace

agentclear

Official SDK for Agent Clear — the AI agent service marketplace.

Agent Clear lets AI agents discover and pay for API services. This SDK provides:

• Provider middleware — protect your API with the 402 viral loop so agents can discover and pay for your service
• Consumer client — discover and call services through the Agent Clear metered proxy

Installation

pip install agentclear

Quick Start: Consumer (AI Agent)

Async

from agentclear import AgentClearClient

client = AgentClearClient(api_key="axk_your_key_here")

# Discover services by natural language query
result = await client.discover("sentiment analysis")
for svc in result.services:
    print(f"{svc.name} — ${svc.price_per_call}/call")

# Call a service through the metered proxy
response = await client.call(
    result.services[0].id,
    {"text": "I love this product!"},
)
print(response.data)

Sync

from agentclear import AgentClearClient

client = AgentClearClient(api_key="axk_your_key_here")

result = client.discover_sync("sentiment analysis")
response = client.call_sync(result.services[0].id, {"text": "I love this product!"})
print(response.data)

Quick Start: Provider (402 Middleware)

FastAPI Decorator

from fastapi import FastAPI, Request
from agentclear import require_payment

app = FastAPI()

@app.post("/analyze")
@require_payment(service_id="my-sentiment-api", price=0.005)
async def analyze(request: Request):
    body = await request.json()
    return {"sentiment": "positive", "score": 0.95}

ASGI Middleware (all routes)

from fastapi import FastAPI
from agentclear import AgentClearMiddleware

app = FastAPI()
app.add_middleware(
    AgentClearMiddleware,
    service_id="my-sentiment-api",
    price=0.005,
)

@app.post("/analyze")
async def analyze(request: Request):
    body = await request.json()
    return {"sentiment": "positive", "score": 0.95}

When an agent calls your API without a valid key, they receive:

{
  "error": "Payment Required",
  "message": "This API requires $0.005/call via Agent Clear.",
  "signup_url": "https://agentclear.dev/signup",
  "docs_url": "https://agentclear.dev/docs",
  "service_id": "my-sentiment-api",
  "price_per_call": 0.005,
  "platform": "agentclear"
}

API Reference

AgentClearClient

AgentClearClient(
    api_key: str,              # Required — your axk_ API key
    base_url: str = "https://agentclear.dev",
    framework_ref: str | None = None,  # Optional rev-share tracking
)

await client.discover(query, limit=10) / client.discover_sync(...)

Search for services by natural language.

Parameter	Type	Default	Description
query	str	—	Semantic search query
limit	int	10	Max results

Returns DiscoverResponse.

await client.call(service_id, payload, timeout=30.0) / client.call_sync(...)

Call a service through the metered proxy.

Parameter	Type	Default	Description
service_id	str	—	Service to call
payload	dict	—	JSON body to forward
timeout	float	30.0	Timeout in seconds

Returns ServiceResponse.

await client.services(...) / client.services_sync(...)

List available services with optional filtering.

Parameter	Type	Default	Description
limit	int | None	None	Max results
offset	int | None	None	Pagination offset
protocol	str | None	None	Filter by protocol

Returns ServicesResponse.

require_payment(service_id, price, platform_url=...)

Decorator for FastAPI/Starlette endpoints. Returns 402 for unauthenticated requests.

AgentClearMiddleware

ASGI middleware class. Protects all routes with 402 payment required.

Documentation

Full documentation at https://agentclear.dev/docs.

License

MIT — see LICENSE.