TradingAgents/docs/api/rest-api.md

REST API Reference

TradingAgents provides a FastAPI backend for programmatic access to trading functionality.

Overview

The REST API is built on FastAPI with:

• Async/await support for high performance
• JWT authentication for secure access
• SQLAlchemy 2.0 async ORM
• Pydantic validation for requests/responses
• OpenAPI documentation at /docs

Running the API

# Start development server
uvicorn tradingagents.api.main:app --reload --port 8000

# Production (with gunicorn)
gunicorn tradingagents.api.main:app -w 4 -k uvicorn.workers.UvicornWorker

Authentication

Login

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=user@example.com&password=SecurePassword123

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer"
}

Using the Token

Include the token in subsequent requests:

GET /api/v1/strategies
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Token Expiration

Tokens expire after 30 minutes by default. Configure via JWT_EXPIRATION_MINUTES environment variable.

Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Strategies

List Strategies

GET /api/v1/strategies
Authorization: Bearer <token>

Query parameters:

• skip (int): Pagination offset (default: 0)
• limit (int): Page size (default: 100, max: 1000)
• active_only (bool): Filter to active strategies only

Response:

{
  "items": [
    {
      "id": 1,
      "name": "Moving Average Crossover",
      "description": "Simple MA crossover strategy",
      "parameters": {"fast_period": 10, "slow_period": 20},
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 100
}

Create Strategy

POST /api/v1/strategies
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "RSI Mean Reversion",
  "description": "Buy oversold, sell overbought",
  "parameters": {
    "rsi_period": 14,
    "oversold": 30,
    "overbought": 70
  },
  "is_active": true
}

Response (201 Created):

{
  "id": 2,
  "name": "RSI Mean Reversion",
  "description": "Buy oversold, sell overbought",
  "parameters": {
    "rsi_period": 14,
    "oversold": 30,
    "overbought": 70
  },
  "is_active": true,
  "created_at": "2024-01-15T11:00:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Get Strategy

GET /api/v1/strategies/{id}
Authorization: Bearer <token>

Update Strategy

PUT /api/v1/strategies/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Strategy Name",
  "parameters": {"new_param": 42}
}

Delete Strategy

DELETE /api/v1/strategies/{id}
Authorization: Bearer <token>

Response (204 No Content)

Error Responses

All errors return JSON with consistent structure:

{
  "detail": "Error message here"
}

Common Status Codes

Code	Description
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Duplicate resource
422	Validation Error - Failed Pydantic validation
500	Internal Server Error

Validation Errors

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Configuration

Environment variables:

Variable	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./tradingagents.db	Database connection string
JWT_SECRET_KEY	Required	Secret key for JWT signing
JWT_ALGORITHM	HS256	JWT signing algorithm
JWT_EXPIRATION_MINUTES	30	Token expiration time
CORS_ORIGINS	["*"]	Allowed CORS origins
SQLALCHEMY_ECHO	false	Log SQL queries

Database Migrations

The API uses Alembic for database migrations:

# Create new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

# Rollback one migration
alembic downgrade -1

OpenAPI Documentation

Interactive API documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

Python Client Example

import httpx

async def main():
    async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
        # Login
        response = await client.post("/api/v1/auth/login", data={
            "username": "user@example.com",
            "password": "password123"
        })
        token = response.json()["access_token"]

        headers = {"Authorization": f"Bearer {token}"}

        # List strategies
        response = await client.get("/api/v1/strategies", headers=headers)
        strategies = response.json()["items"]

        # Create strategy
        response = await client.post("/api/v1/strategies", headers=headers, json={
            "name": "New Strategy",
            "description": "Test",
            "parameters": {},
        })
        new_strategy = response.json()

        print(f"Created strategy: {new_strategy['id']}")

import asyncio
asyncio.run(main())

See Also

• Authentication Guide
• Database Models
• FastAPI Documentation