API Endpoints¶

The QuantFin Bot provides a comprehensive REST API with 27 endpoints for managing trading operations, configurations, and monitoring. All endpoints are built using FastAPI and support async operations.

Base URL¶

https://quantfin.dexalgo.org/api

Configuration Management¶

Get User Configuration¶

GET /config/{user_id}

Retrieves the current trading configuration for a specific user.

Parameters: - user_id (string): Unique identifier for the user

Response:

{
  "mode": "xgridt_mm_both",
  "dynamic_distribution": {
    "enabled": true,
    "wallet_exposure_limit_long": 0.01,
    "wallet_exposure_limit_short": 0.01,
    "strength": 1,
    "levels": 3,
    "qty_precision": 1
  },
  "tp_distance": 0.0009,
  "grid_levels": 3,
  "order_qty": 10,
  "xgrid_spacing": 0.0024,
  "xgrid_levels": 3,
  "xgrid_max_open": 3
}

Update User Configuration¶

POST /config/{user_id}

Updates the trading configuration for a specific user.

Parameters: - user_id (string): Unique identifier for the user

Request Body:

{
  "mode": "market_making_long",
  "order_qty": 15,
  "tp_distance": 0.0012,
  "grid_levels": 5
}

Get Available Presets¶

GET /presets

Returns all available strategy presets (Safu, Moderate, Aggressive, YachtToday).

Response:

{
  "presets": [
    {
      "name": "Safu",
      "description": "Conservative trading with low risk",
      "config": {...}
    },
    {
      "name": "Moderate", 
      "description": "Balanced risk/reward approach",
      "config": {...}
    }
  ]
}

Export Configuration¶

POST /export_config/{user_id}

Exports the user's current configuration as a downloadable file.

Trading Control¶

Start Trading Bot¶

POST /start/{user_id}

Initiates the trading bot for a specific user.

Parameters: - user_id (string): Unique identifier for the user

Response:

{
  "status": "started",
  "message": "Trading bot started successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

Stop Trading Bot¶

POST /stop/{user_id}

Stops the trading bot for a specific user.

Get Bot Status¶

GET /status/{user_id}

Returns the current status of the trading bot.

Response:

{
  "status": "running",
  "uptime": "2h 45m",
  "last_trade": "2024-01-15T10:25:00Z",
  "active_orders": 3,
  "current_position": 150.5
}

Emergency Stop¶

POST /emergency_stop/{user_id}

Immediately stops all trading activities and cancels open orders.

Data & Analytics¶

Get Equity History¶

GET /equity_history/{user_id}

Retrieves historical equity data for analysis and charting.

Query Parameters: - start_date (optional): Start date for data range - end_date (optional): End date for data range - symbol (optional): Filter by specific trading symbol

Response:

{
  "data": [
    {
      "timestamp": "2024-01-15T10:00:00Z",
      "userId": "user123",
      "symbol": "SUI-USDC",
      "equity": 1250.75,
      "unrealized_pnl": 15.25,
      "realized_pnl": 235.50,
      "position_size": 150.0,
      "mark_price": 1.8345
    }
  ]
}

Get Trading Statistics¶

GET /trading_stats/{user_id}

Returns comprehensive trading performance statistics.

Response:

{
  "total_trades": 1247,
  "win_rate": 0.67,
  "total_pnl": 2845.32,
  "max_drawdown": -156.78,
  "sharpe_ratio": 1.34,
  "profit_factor": 1.89
}

Get Current Positions¶

GET /positions/{user_id}

Returns all current trading positions.

Get Order History¶

GET /orders/{user_id}

Retrieves order history with filtering options.

Query Parameters: - limit (optional): Number of orders to return (default: 100) - offset (optional): Pagination offset - status (optional): Filter by order status (filled, cancelled, pending)

User Management¶

Get User Info¶

GET /user/{user_id}

Retrieves user account information and settings.

Update User Settings¶

POST /user/{user_id}/settings

Updates user preferences and notification settings.

Wallet & Exchange Integration¶

Get Wallet Info¶

GET /wallet/{user_id}

Returns wallet connection status and balance information.

Connect Wallet¶

POST /wallet/connect

Initiates wallet connection process for Sui blockchain.

Get Exchange Status¶

GET /exchange/status

Returns the current status of exchange connections (Bluefin).

Monitoring & Health¶

Health Check¶

GET /health

Returns the overall system health status.

Get System Metrics¶

GET /metrics

Returns system performance metrics for monitoring.

Error Handling¶

All endpoints return standard HTTP status codes:

200 OK: Request successful
400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication required
404 Not Found: Resource not found
500 Internal Server Error: Server error

Error responses follow this format:

{
  "error": "error_code",
  "message": "Human readable error message",
  "details": "Additional error details"
}

Rate Limiting¶

API endpoints are rate-limited to prevent abuse: - Configuration endpoints: 10 requests per minute - Trading control endpoints: 5 requests per minute - Data endpoints: 100 requests per minute - Health/monitoring: 1000 requests per minute

Authentication¶

All API endpoints require authentication using API keys or JWT tokens. Include authentication headers in your requests:

Authorization: Bearer YOUR_API_TOKEN

For more details on authentication setup, see the Security documentation.