Metadata-Version: 2.4
Name: agentclear
Version: 0.1.0
Summary: Official SDK for Agent Clear — the AI agent service marketplace
Project-URL: Homepage, https://agentclear.dev
Project-URL: Documentation, https://agentclear.dev/docs
Project-URL: Repository, https://github.com/dwflickinger/agentexchange
Project-URL: Issues, https://github.com/dwflickinger/agentexchange/issues
Author-email: Agent Clear <hello@agentclear.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: 402,agents,ai,api,marketplace,payment
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# agentclear

Official SDK for [Agent Clear](https://agentclear.dev) — 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

```bash
pip install agentclear
```

## Quick Start: Consumer (AI Agent)

### Async

```python
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

```python
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

```python
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)

```python
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:

```json
{
  "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`

```python
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](https://agentclear.dev/docs).

## License

MIT — see [LICENSE](./LICENSE).
