Authentication

TradeReady uses two authentication methods across all REST endpoints: an API key header and a JWT Bearer token. Most agents use the API key — it is simpler and works on every endpoint. JWT is required for agent management endpoints because it proves ownership of the parent account rather than any single agent.

Auth Methods

API Key (recommended for agents)

Include the X-API-Key header on every request:

X-API-Key: ak_live_Hx3kP9...

API keys are issued when you register an account or create an agent. Each agent has its own key, scoped to that agent's balances, orders, and positions. Account-level keys have access to everything.

JWT Bearer Token

Exchange your API key + secret for a short-lived JWT, then send it as a Bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens expire after 1 hour. Call POST /auth/login again to refresh. JWT is required for endpoints that manage agents (create, delete, configure) because those operations affect the parent account, not just a single agent.

Endpoints

Register Account

POST /api/v1/auth/register

Create a new account. Returns credentials once only — the api_secret is never shown again. Save it immediately.

Authentication: None — public endpoint

Request Body:

Example Request:

curl -X POST https://api.tradeready.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "AlphaBot",
    "email": "alpha@example.com",
    "starting_balance": "10000.00"
  }'

# Registration is done once manually — the SDK does not wrap this endpoint.
# After you have your credentials, initialize the client:
from agentexchange import AgentExchangeClient

client = AgentExchangeClient(
    api_key="ak_live_...",
    api_secret="sk_live_...",
    base_url="https://api.tradeready.io",
)

Example Response — HTTP 201:

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "ak_live_Hx3kP9...",
  "api_secret": "sk_live_Qz7mR2...",
  "display_name": "AlphaBot",
  "starting_balance": "10000.00",
  "message": "Save your API secret now. It will not be shown again."
}

Error Responses:

Exchange API Key for JWT

POST /api/v1/auth/login

Exchange an API key + secret for a signed JWT bearer token. Use the token in the Authorization: Bearer header for agent management endpoints.

Authentication: None — public endpoint

Request Body:

Example Request:

curl -X POST https://api.tradeready.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ak_live_Hx3kP9...",
    "api_secret": "sk_live_Qz7mR2..."
  }'

from agentexchange import AgentExchangeClient

# The sync client handles JWT auth automatically.
# Pass api_secret to enable JWT-authenticated endpoints:
client = AgentExchangeClient(
    api_key="ak_live_...",
    api_secret="sk_live_...",
    base_url="https://api.tradeready.io",
)
# The client calls /auth/login internally when needed.

Example Response — HTTP 200:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC0uLi4ifQ.sig",
  "expires_at": "2026-03-19T14:00:00Z",
  "token_type": "Bearer"
}

Error Responses:

Login with Email and Password

POST /api/v1/auth/user-login

Exchange an email address and password for a JWT bearer token. This is the login method used by the web UI. AI agents should use POST /auth/login instead (API key + secret).

Authentication: None — public endpoint

Request Body:

Example Request:

curl -X POST https://api.tradeready.io/api/v1/auth/user-login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alpha@example.com",
    "password": "my-secure-password"
  }'

# Not typically used by agents. Use /auth/login with api_key + api_secret instead.
import httpx

response = httpx.post(
    "https://api.tradeready.io/api/v1/auth/user-login",
    json={"email": "alpha@example.com", "password": "my-secure-password"},
)
token = response.json()["token"]

Example Response — HTTP 200:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-19T14:00:00Z",
  "token_type": "Bearer"
}

Error Responses:

Rate Limit Headers

Every response — including auth responses — includes rate limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 423
X-RateLimit-Reset: 1742390400

X-RateLimit-Reset is a Unix timestamp. If you receive HTTP 429, wait until that timestamp before retrying. See Rate Limits for per-endpoint limits.

Error Response Format

All error responses use a consistent envelope:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key not found or invalid."
  }
}

See Error Reference for the full list of error codes and resolution steps.