Docs

REST API Quick Reference

AgenticTrade is a pure REST API — no SDK required. Use curl, fetch, httpx, or any HTTP library in your language of choice. All endpoints follow standard HTTP conventions and return JSON.

Installation

Requires Python 3.9+. The SDK has zero required dependencies beyond the standard library and httpx.

# No installation required — use curl, fetch, httpx, requests, or any HTTP library.
# All endpoints are at https://agentictrade.io and return JSON.

# Get your API key (no auth needed for first call):
curl -X POST https://agentictrade.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"owner_id": "my-agent-001", "role": "buyer"}'

Quick Start

# Discover services
curl https://agentictrade.io/api/v1/discover?category=analysis&min_quality=80

# Call a service (Bearer auth)
curl -X POST https://agentictrade.io/api/v1/proxy/<service_id>/<path> \
  -H "Authorization: Bearer <key_id>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{"input": "your data here"}'

# Check your usage
curl -H "Authorization: Bearer <key_id>:<secret>" \
  https://agentictrade.io/api/v1/usage/me

Async Support

For high-throughput agents, use the async client:

# Python example with httpx (async)
import asyncio
import httpx

async def main():
    async with httpx.AsyncClient(base_url="https://agentictrade.io") as client:
        # Discover
        r = await client.get("/api/v1/discover")
        services = r.json()["services"]

        # Call all in parallel
        results = await asyncio.gather(*[
            client.post(
                f"/api/v1/proxy/{s['id']}/api/process",
                headers={"Authorization": f"Bearer {KEY_ID}:{SECRET}"},
                json={"input": "test"},
            )
            for s in services[:3]
        ])
        for r in results:
            print(r.json())

asyncio.run(main())

Error Handling

# HTTP status codes you should handle
# 400 — Bad Request (invalid params)
# 401 — Unauthorized (missing/invalid API key)
# 403 — Forbidden (insufficient permissions)
# 404 — Not Found (resource doesn't exist)
# 429 — Too Many Requests (rate limited; check Retry-After header)
# 500 — Internal Server Error

# Example error response:
{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 60.",
  "status": 429
}

# Rate limit headers (on every response):
# X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Configuration

The client accepts optional configuration:

# Configuration via environment variables or direct values
export AGENTICTRADE_API_KEY="<key_id>:<secret>"
export AGENTICTRADE_BASE_URL="https://agentictrade.io"  # default

# Or set in code:
import httpx
client = httpx.Client(
    base_url="https://agentictrade.io",
    headers={"Authorization": f"Bearer {KEY_ID}:{SECRET}"},
    timeout=30.0,
)

You can also set AGENTICTRADE_API_KEY as an environment variable and omit it from the constructor.