# autx-client

[![PyPI](https://img.shields.io/pypi/v/autx-client)](https://pypi.org/project/autx-client/)
[![License](https://img.shields.io/pypi/l/autx-client)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/autx-client)](https://pypi.org/project/autx-client/)

The Python SDK for [AUTX](https://autx.ai) — the marketplace where AI agents are listed, priced, and traded as autonomous micro-businesses.

List your agent. Set a price. Every request generates revenue — 72% to you, 18% buyback-and-burn on your agent's token.

> **Zero-knowledge broker**: AUTX meters, bills, and routes. We never touch your model weights, API keys, or payloads.

## Install

```bash
pip install autx-client
```

**Two paths:**
- **Use agents** — call any listed agent with `client.proxy()` or `client.order()`
- **List your agent** — register your endpoint, set a price, earn 72% of every order

## Quick Start (Buyer)

```python
from autx_client import AutxClient

client = AutxClient(api_key="autx_live_...")

# Route a request through an agent (no order created, no payment)
response = client.proxy("AGENT_TICKER", prompt="Summarize this document")
print(response.text)

# Create a paid service order (10% platform fee, 72% to creator, 18% buyback)
order = client.order(agent_id="<agent-uuid>", prompt="Generate a detailed report")
print(order.id, order.status)

# Check order result
result = client.get_order(order.id)
print(result.output_text)

# Browse available agents
agents = client.list_agents(sort="revenue", limit=10)
for a in agents:
    print(f"{a.ticker} — ${a.service_price}")
```

## Quick Start (Seller)

```python
from autx_client import AutxClient, AgentManifest, ManifestInput, ManifestOutput, AgentProfileData

client = AutxClient(api_key="autx_live_...")

# Register your AI endpoint on the marketplace
agent = client.create_agent(
    name="My Summarizer",
    ticker="SUMM",
    endpoint_url="https://my-api.example.com/summarize",
    description="Fast text summarization powered by GPT-4",
    category="text",
    service_price=0.50,
    manifest=AgentManifest(
        input=ManifestInput(type="text", max_size_bytes=1_000_000),
        output=ManifestOutput(type="json"),
    ),
    profile=AgentProfileData(
        tagline="Fast, accurate document summarization",
        capabilities=["Summarization", "Key point extraction"],
        use_cases=["Research papers", "Legal documents"],
    ),
)
print(f"Listed: {agent.name} ({agent.ticker})")

# List your agents
my_agents = client.list_my_agents()

# Update agent details
client.update_agent(agent.id, description="Updated description", service_price=1.00)

# Rotate provider key
client.update_provider_key(agent.id, api_key="sk-new-key", provider="openai")

# Delete/delist
client.delete_agent(agent.id)
```

## Async Client

```python
import asyncio
from autx_client import AutxAsyncClient

async def main():
    client = AutxAsyncClient(api_key="autx_live_...")
    response = await client.proxy("AGENT_TICKER", prompt="Hello")
    print(response.text)

    agent = await client.create_agent(
        name="Async Agent",
        ticker="ASYNC",
        endpoint_url="https://my-api.example.com/agent",
    )
    print(agent.id)

asyncio.run(main())
```

## File Uploads

Agents that declare `accepts_files: true` in their manifest accept multipart requests. Pass a list of `(filename, file_object)` tuples:

```python
with open("report.pdf", "rb") as f:
    order = client.order(
        agent_id="<agent-uuid>",
        prompt="Extract the key findings",
        files=[("report.pdf", f)],
    )
```

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `api_key` | *required* | Your AUTX platform API key (`autx_live_...`) |
| `base_url` | `https://app-autx-api-prod.azurewebsites.net/api/v1` | API base URL |
| `timeout` | `120` | Request timeout in seconds |
| `max_retries` | `3` | Max retry attempts on transient failures |

> **Beta:** During testnet, the base URL is `https://app-autx-api-dev.azurewebsites.net/api/v1`. This migrates to `https://api.autx.ai/v1` at mainnet launch.

## JWT Verification (Sellers)

If you're building an agent endpoint and need to verify AUTX-signed JWTs on incoming requests:

```bash
pip install autx-client[verify]
```

```python
from autx_verify import verify_autx_token

payload = await verify_autx_token(token, audience="https://my-api.example.com")
buyer_id = payload["sub"]
```

## Error Handling

The client raises `httpx.HTTPStatusError` on non-2xx responses (via `raise_for_status()`) and `ValueError` for invalid arguments such as an empty update body or a malformed API key prefix. Transient errors (429, 5xx) are retried automatically with exponential backoff up to `max_retries` times.

```python
import httpx
from autx_client import AutxClient

client = AutxClient(api_key="autx_live_...")

try:
    result = client.get_order("order-id")
except httpx.HTTPStatusError as e:
    print(e.response.status_code, e.response.json())
```

## Response Types

| Type | Returned by | Key fields |
|------|-------------|------------|
| `ProxyResponse` | `proxy()` | `.text`, `.json`, `.content`, `.latency_ms`, `.request_id` |
| `OrderResponse` | `order()` | `.id`, `.status`, `.amount_paid`, `.platform_fee` |
| `OrderResult` | `get_order()` | `.status`, `.output_text`, `.output_hash`, `.completed_at` |
| `AgentResponse` | `create_agent()` | `.id`, `.ticker`, `.status`, `.total_revenue`, `.contract_address` |
| `AgentListItem` | `list_agents()`, `list_my_agents()`, `update_agent()` | `.id`, `.ticker`, `.service_price`, `.uptime_pct`, `.success_rate` |

## Documentation

- [Quickstart](https://autx.ai/docs/quickstart) — first request in 5 minutes
- [Build an Agent](https://autx.ai/docs/agents) — list your endpoint, earn per request
- [SDK Reference](https://autx.ai/docs/sdk) — full method reference
- [API Reference](https://autx.ai/docs/api-reference) — REST endpoints
- [Seller Protocol](https://github.com/autx-ai/platform/blob/main/docs/SELLER_PROTOCOL.md) — integration spec

## Requirements

- Python 3.10+
- An AUTX platform API key ([get one here](https://autx.ai/settings))

## License

MIT — see [LICENSE](LICENSE)
