API Reference

Overview

The Strategy Execution Platform exposes both synchronous (REST) and asynchronous (WebSocket) APIs for interaction. This section provides comprehensive documentation of all available endpoints, request/response formats, and integration examples.

Authentication

JWT Token Authentication

Most API endpoints require authentication using JWT tokens. Include the token in the Authorization header:


Authorization: Bearer <your_jwt_token>

Getting a JWT Token


curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

Response:


{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

REST API

Base URL


http://localhost:8000

Intent Management

Submit New Intent

Endpoint: POST /intents

Description: Submit a new trading intent to the platform.

Request Body:


{
  "strategy_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "intent_type": "acquire",
  "assets": [
    {
      "asset": {
        "symbol": "WETH",
        "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
        "decimals": 18,
        "chain_id": 42161
      },
      "amount": "1.5"
    },
    {
      "asset": {
        "symbol": "USDC",
        "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "decimals": 6,
        "chain_id": 42161
      }
    }
  ],
  "constraints": {
    "max_slippage": "0.005",
    "time_window_ms": 300000,
    "execution_style": "aggressive"
  }
}

Response: 202 Accepted


{
  "intent_id": "01J...X",
  "status": "pending",
  "submitted_at": "2025-08-21T19:26:00.000Z",
  "estimated_completion": "2025-08-21T19:31:00.000Z"
}

Get Intent Status

Endpoint: GET /intents/{intent_id}

Description: Retrieve the current state of a specific intent.

Response: 200 OK


{
  "intent_id": "01J...X",
  "status": "processing",
  "submitted_at": "2025-08-21T19:26:00.000Z",
  "plan_id": "01J...Y",
  "execution_steps": [
    {
      "step_id": "step-1",
      "status": "completed",
      "transaction_hash": "0x123...",
      "completed_at": "2025-08-21T19:28:00.000Z"
    }
  ],
  "current_value": "3000.50",
  "estimated_completion": "2025-08-21T19:31:00.000Z"
}

List Intents

Endpoint: GET /intents

Description: List all intents with optional filtering.

Query Parameters:

status: Filter by status (pending, processing, completed, failed)
strategy_id: Filter by strategy ID
limit: Maximum number of results (default: 50)
offset: Number of results to skip (default: 0)

Response: 200 OK


{
  "intents": [
    {
      "intent_id": "01J...X",
      "status": "completed",
      "strategy_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "submitted_at": "2025-08-21T19:26:00.000Z",
      "completed_at": "2025-08-21T19:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Strategy Management

List Available Strategies

Endpoint: GET /strategies

Description: List all available trading strategies.

Response: 200 OK


{
  "strategies": [
    {
      "name": "SimpleDCA",
      "version": "1.0.0",
      "description": "Performs a daily purchase of a configured asset.",
      "config_schema": {
        "purchase_asset_key": { "type": "string", "required": true },
        "quote_asset_key": { "type": "string", "required": true },
        "purchase_amount_quote": { "type": "number", "required": true }
      }
    }
  ]
}

Activate Strategy

Endpoint: POST /strategies/activate

Description: Activate a strategy with specific configuration.

Request Body:


{
  "strategy_name": "SimpleDCA",
  "config": {
    "purchase_asset_key": "WETH_ETHEREUM",
    "quote_asset_key": "USDC_ETHEREUM",
    "purchase_amount_quote": 100.0
  }
}

Response: 201 Created


{
  "strategy_id": "b2c3d4e5-f6g7-8901-2345-678901bcdefg",
  "name": "SimpleDCA",
  "status": "active",
  "activated_at": "2025-08-21T19:26:00.000Z"
}

Get Strategy Status

Endpoint: GET /strategies/{strategy_id}/status

Description: Get the current status and performance of an active strategy.

Response: 200 OK


{
  "strategy_id": "b2c3d4e5-f6g7-8901-2345-678901bcdefg",
  "name": "SimpleDCA",
  "status": "active",
  "activated_at": "2025-08-21T19:26:00.000Z",
  "total_intents": 15,
  "successful_intents": 14,
  "failed_intents": 1,
  "total_volume": "1500.00",
  "last_intent_at": "2025-08-21T19:00:00.000Z"
}

Deactivate Strategy

Endpoint: POST /strategies/{strategy_id}/deactivate

Description: Deactivate a running strategy.

Response: 200 OK


{
  "strategy_id": "b2c3d4e5-f6g7-8901-2345-678901bcdefg",
  "status": "inactive",
  "deactivated_at": "2025-08-21T19:35:00.000Z"
}

Portfolio and Market Data

Get Portfolio

Endpoint: GET /portfolio

Description: Get the current portfolio state.

Response: 200 OK


{
  "total_value": "15420.75",
  "positions": [
    {
      "asset": {
        "symbol": "WETH",
        "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
        "decimals": 18,
        "chain_id": 42161
      },
      "quantity": "5.0",
      "value": "15000.00",
      "unrealized_pnl": "500.00"
    },
    {
      "asset": {
        "symbol": "USDC",
        "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "decimals": 6,
        "chain_id": 42161
      },
      "quantity": "420.75",
      "value": "420.75",
      "unrealized_pnl": "0.00"
    }
  ],
  "last_updated": "2025-08-21T19:26:00.000Z"
}

Get Market Data

Endpoint: GET /market/{asset_symbol}

Description: Get current market data for a specific asset.

Response: 200 OK


{
  "symbol": "WETH",
  "price": "3000.00",
  "price_change_24h": "2.5",
  "volume_24h": "1500000.00",
  "market_cap": "36000000000.00",
  "last_updated": "2025-08-21T19:26:00.000Z"
}

WebSocket API

Connection

Connect to the WebSocket endpoint:


ws://localhost:8000/ws

Authentication

Send an authentication message after connection:


{
  "action": "authenticate",
  "token": "your_jwt_token"
}

Subscription

Subscribe to specific event topics:


{
  "action": "subscribe",
  "topics": ["intent.*", "exec.*", "market.tick"],
  "correlationId": "sub-01J...X"
}

Event Format

All events follow a standard envelope structure:


{
  "eventId": "01J...Z",
  "timestamp": "2025-08-21T19:26:00.000Z",
  "topic": "intent.accepted",
  "correlationId": "intent-01J...X",
  "payload": {
    "intent_id": "01J...X",
    "status": "accepted",
    "estimated_completion": "2025-08-21T19:31:00.000Z"
  },
  "version": 1
}

Event Topics

Intent Events

intent.submitted: Intent has been submitted to the system
intent.accepted: Intent has passed validation and been accepted
intent.rejected: Intent has been rejected (with reason)
intent.processing: Intent is being processed
intent.completed: Intent has been successfully completed
intent.failed: Intent has failed (with error details)

Execution Events

exec.started: Execution of an intent has begun
exec.step_submitted: A step has been submitted to the blockchain
exec.step_filled: A step has been confirmed on-chain
exec.step_failed: A step has failed
exec.completed: All steps have been completed successfully
exec.failed: Execution has failed

Market Events

market.tick: Price update for an asset
market.trade: New trade executed
market.orderbook: Order book update

Portfolio Events

portfolio.delta: Portfolio value change
portfolio.position_update: Position update

Example WebSocket Client


class TradingWebSocket {
  constructor(url, token) {
    this.url = url;
    this.token = token;
    this.ws = null;
    this.reconnectAttempts = 0;
    this.maxReconnectAttempts = 5;
  }
 
  connect() {
    this.ws = new WebSocket(this.url);
 
    this.ws.onopen = () => {
      console.log("WebSocket connected");
      this.authenticate();
      this.subscribe();
    };
 
    this.ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      this.handleEvent(data);
    };
 
    this.ws.onclose = () => {
      console.log("WebSocket disconnected");
      this.reconnect();
    };
 
    this.ws.onerror = (error) => {
      console.error("WebSocket error:", error);
    };
  }
 
  authenticate() {
    this.ws.send(
      JSON.stringify({
        action: "authenticate",
        token: this.token,
      })
    );
  }
 
  subscribe() {
    this.ws.send(
      JSON.stringify({
        action: "subscribe",
        topics: ["intent.*", "exec.*", "market.tick"],
        correlationId: "sub-" + Date.now(),
      })
    );
  }
 
  handleEvent(event) {
    switch (event.topic) {
      case "intent.submitted":
        console.log("New intent submitted:", event.payload.intent_id);
        break;
      case "exec.completed":
        console.log("Execution completed:", event.payload.intent_id);
        break;
      case "market.tick":
        console.log("Price update:", event.payload.symbol, event.payload.price);
        break;
      default:
        console.log("Unknown event:", event.topic);
    }
  }
 
  reconnect() {
    if (this.reconnectAttempts < this.maxReconnectAttempts) {
      this.reconnectAttempts++;
      const delay = Math.pow(2, this.reconnectAttempts) * 1000;
      console.log(`Reconnecting in ${delay}ms...`);
 
      setTimeout(() => {
        this.connect();
      }, delay);
    } else {
      console.error("Max reconnection attempts reached");
    }
  }
 
  disconnect() {
    if (this.ws) {
      this.ws.close();
    }
  }
}
 
// Usage
const ws = new TradingWebSocket("ws://localhost:8000/ws", "your_jwt_token");
ws.connect();

Error Handling

HTTP Status Codes

200 OK: Request successful
201 Created: Resource created successfully
202 Accepted: Request accepted for processing
400 Bad Request: Invalid request format or parameters
401 Unauthorized: Authentication required or invalid
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
422 Unprocessable Entity: Validation error
500 Internal Server Error: Server error

Error Response Format


{
  "error": "validation_error",
  "message": "Invalid intent parameters",
  "details": {
    "field": "max_slippage",
    "issue": "Value must be between 0.001 and 0.1"
  },
  "timestamp": "2025-08-21T19:26:00.000Z",
  "request_id": "req-01J...X"
}

Rate Limiting

The API implements rate limiting to prevent abuse:

Authentication endpoints: 5 requests per minute
Intent submission: 10 requests per minute
Data retrieval: 100 requests per minute
WebSocket connections: 10 connections per IP per minute

Rate limit headers are included in responses:


X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1640123456

SDKs and Libraries

Python SDK


pip install strategy-execution-platform


from strategy_execution_platform import Client
 
client = Client('http://localhost:8000', 'your_jwt_token')
 
# Submit intent
intent = client.submit_intent(
    strategy_id='your_strategy_id',
    intent_type='acquire',
    assets=[...],
    constraints={...}
)
 
# Get status
status = client.get_intent_status(intent.intent_id)

JavaScript/TypeScript SDK


npm install @strategy-execution-platform/client


import { Client } from '@strategy-execution-platform/client';
 
const client = new Client('http://localhost:8000', 'your_jwt_token');
 
// Submit intent
const intent = await client.submitIntent({
  strategyId: 'your_strategy_id',
  intentType: 'acquire',
  assets: [...],
  constraints: {...}
});
 
// Get status
const status = await client.getIntentStatus(intent.intentId);

Testing

Test Environment

The platform provides a test environment with mock data:


http://localhost:8000/test

Test Endpoints

POST /test/intents - Create test intents
POST /test/market-data - Inject test market data
POST /test/reset - Reset test environment

Example Test Script


#!/bin/bash
 
# Create test intent
curl -X POST http://localhost:8000/test/intents \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_id": "test-strategy",
    "intent_type": "acquire",
    "assets": [
      {
        "asset": {"symbol": "WETH", "chain_id": 1},
        "amount": "1.0"
      }
    ]
  }'
 
# Inject market data
curl -X POST http://localhost:8000/test/market-data \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "WETH",
    "price": "3000.00",
    "timestamp": "2025-08-21T19:26:00.000Z"
  }'

Next Steps

Backend Engineers: Return to Backend Engine to understand how these APIs are implemented
Frontend Developers: Check Frontend Dashboard to see how these APIs are consumed
Integration Developers: Use the examples and SDKs to integrate with your systems
DevOps Engineers: Check Integration & Operations for deployment and monitoring