AgentX API Documentation

Comprehensive guide to the AgentX API for programmatic access and integration

Table of Contents

Overview

The AgentX API provides programmatic access to the AgentX trading system, enabling integration with external systems and custom applications. This document provides detailed information about endpoints, request/response formats, and authentication requirements.

Base URL

All API endpoints are relative to the base URL:

http://localhost:5000/api

Authentication

API requests require authentication using an API key. Include the API key in the request header:

X-API-Key: your_api_key_here

API keys can be generated in the dashboard under Settings > API Access.

Keep your API keys secure. Do not share them or expose them in client-side code.

Response Format

All API responses are in JSON format with the following structure:

{
  "success": true,
  "data": {
    // Response data specific to the endpoint
  },
  "error": null
}

In case of an error:

{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error message description"
  }
}

System Endpoints

GET /system/status

Get current system status.

Response

{
  "success": true,
  "data": {
    "status": "running",
    "uptime_seconds": 3600,
    "start_time": "2025-03-19T10:00:00Z",
    "current_time": "2025-03-19T11:00:00Z",
    "active_agents": 11,
    "total_agents": 11,
    "metrics": {
      "messages_processed": 1500,
      "errors": 0,
      "warnings": 2
    }
  },
  "error": null
}

POST /system/control

Control system operation.

Request

{
  "action": "start" // Possible values: "start", "stop", "restart"
}

Response

{
  "success": true,
  "data": {
    "message": "System started successfully",
    "status": "running"
  },
  "error": null
}

Agents Endpoints

GET /agents/status

Get status of all agents.

Response

{
  "success": true,
  "data": {
    "chief_coordinator": {
      "type": "CHIEF_COORDINATOR",
      "layer": "EXECUTIVE",
      "status": "running"
    },
    "risk_manager": {
      "type": "RISK_MANAGER",
      "layer": "EXECUTIVE",
      "status": "running"
    },
    // Additional agents...
  },
  "error": null
}

POST /agents/control

Control agent operation.

Request

{
  "agent_id": "chief_coordinator",
  "action": "restart"
}

Response

{
  "success": true,
  "data": {
    "message": "Agent chief_coordinator restarted successfully",
    "status": "running"
  },
  "error": null
}

Performance Endpoints

GET /performance

Get performance metrics.

Query Parameters

Parameter Type Required Description
period string No Time period for metrics (default: "all", options: "day", "week", "month", "year", "all")

Response

{
  "success": true,
  "data": {
    "returns": [
      {
        "date": "2025-03-18T00:00:00Z",
        "daily_return": 0.0125,
        "cumulative_return": 0.0125
      },
      {
        "date": "2025-03-19T00:00:00Z",
        "daily_return": 0.0075,
        "cumulative_return": 0.0201
      }
      // Additional return data...
    ],
    "drawdowns": [
      {
        "date": "2025-03-18T00:00:00Z",
        "drawdown": 0.0
      },
      {
        "date": "2025-03-19T00:00:00Z",
        "drawdown": 0.0025
      }
      // Additional drawdown data...
    ],
    "sharpe_ratio": 2.1,
    "win_rate": 0.65,
    "trade_count": 42,
    "max_drawdown": 0.05,
    "volatility": 0.12
  },
  "error": null
}

Trades Endpoints

GET /trades

Get trade history.

Query Parameters

Parameter Type Required Description
limit integer No Maximum number of trades to return (default: 100)
offset integer No Offset for pagination (default: 0)
asset string No Filter by asset (e.g., "BTC/USDT")
action string No Filter by action (e.g., "buy", "sell")
status string No Filter by status (e.g., "completed", "executing", "failed")

Response

{
  "success": true,
  "data": {
    "trades": [
      {
        "order_id": "order_12345",
        "trade_instruction": {
          "asset": "BTC/USDT",
          "action": "buy",
          "quantity": 0.5,
          "exchange": "binance",
          "execution_strategy": "market"
        },
        "status": "completed",
        "execution_price": 50000.0,
        "created_at": "2025-03-19T10:30:00Z",
        "completed_at": "2025-03-19T10:30:05Z"
      },
      // Additional trades...
    ],
    "total": 42,
    "limit": 100,
    "offset": 0
  },
  "error": null
}

GET /trades/active

Get active trades.

Response

{
  "success": true,
  "data": {
    "active_trades": [
      {
        "order_id": "order_12346",
        "trade_instruction": {
          "asset": "ETH/USDT",
          "action": "buy",
          "quantity": 2.0,
          "exchange": "binance",
          "execution_strategy": "twap"
        },
        "status": "executing",
        "progress": 0.5,
        "created_at": "2025-03-19T11:00:00Z",
        "estimated_completion": "2025-03-19T11:30:00Z"
      },
      // Additional active trades...
    ]
  },
  "error": null
}

Websocket API

In addition to the REST API, AgentX provides a Websocket API for real-time updates.

Connection

Connect to the Websocket endpoint:

ws://localhost:5000/ws

Include your API key in the connection query parameter:

ws://localhost:5000/ws?api_key=your_api_key_here

Subscription

After connecting, subscribe to specific channels:

{
  "action": "subscribe",
  "channels": ["system", "trades", "alerts"]
}

Available channels:

  • system: System status updates
  • trades: Trade execution updates
  • alerts: New alerts
  • performance: Performance metric updates
  • portfolio: Portfolio allocation updates
  • market_data: Market data updates (requires asset parameter)

For market data, specify the asset:

{
  "action": "subscribe",
  "channels": ["market_data"],
  "parameters": {
    "market_data": {
      "assets": ["BTC/USDT", "ETH/USDT"],
      "interval": "1m"
    }
  }
}

Messages

Messages received from the server follow this format:

{
  "channel": "trades",
  "event": "trade_executed",
  "timestamp": "2025-03-19T11:15:00Z",
  "data": {
    // Event-specific data
  }
}

Example trade execution event:

{
  "channel": "trades",
  "event": "trade_executed",
  "timestamp": "2025-03-19T11:15:00Z",
  "data": {
    "order_id": "order_12347",
    "asset": "BTC/USDT",
    "action": "buy",
    "quantity": 0.1,
    "price": 51000.0,
    "exchange": "binance"
  }
}

Error Codes

Code Description
AUTH_FAILED Authentication failed
INVALID_REQUEST Invalid request format
MISSING_PARAMETER Required parameter missing
INVALID_PARAMETER Parameter value invalid
RESOURCE_NOT_FOUND Requested resource not found
SYSTEM_ERROR Internal system error
AGENT_ERROR Agent-specific error
RATE_LIMIT_EXCEEDED API rate limit exceeded

Rate Limits

API requests are subject to rate limiting:

  • 60 requests per minute per API key
  • Websocket connections limited to 5 per API key

When rate limit is exceeded, the API returns a 429 status code with the RATE_LIMIT_EXCEEDED error.

Versioning

The current API version is v1. Include the version in the URL:

http://localhost:5000/api/v1/system/status

Future API versions will be announced with appropriate migration guides.