Agents

Manage trading agents - create, list, update, delete, and configure.

Endpoints Overview

Method	Endpoint	Description
`POST`	`/api/v1/agents`	Create a new agent
`GET`	`/api/v1/agents`	List all agents
`GET`	`/api/v1/agents/:id`	Get a specific agent
`PUT`	`/api/v1/agents/:id`	Update an agent
`DELETE`	`/api/v1/agents/:id`	Delete an agent
`GET`	`/api/v1/agents/:id/config`	Get trading configuration
`PUT`	`/api/v1/agents/:id/config`	Update trading configuration
`GET`	`/api/v1/agents/:id/positions`	Get agent positions
`GET`	`/api/v1/agents/:id/performance`	Get performance metrics
`GET`	`/api/v1/agents/:id/balance-history`	Get balance history

All agent endpoints require JWT authentication. Include your access token in the Authorization header.

Create Agent

Create a new trading agent.

POST /api/v1/agents

Request

{
  "name": "My Trading Agent",
  "tradingMode": "simulation"
}

Field	Type	Required	Description
`name`	string	Yes	Agent name (max 255 characters)
`tradingMode`	string	No	`simulation` or `live` (default: `simulation`)

Response

Success (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Trading Agent",
  "tradingMode": "simulation",
  "automatedTradingSimulation": false,
  "automatedTradingLive": false,
  "createdAt": "2025-01-20T10:30:00.000Z",
  "updatedAt": "2025-01-20T10:30:00.000Z"
}

Example

curl -X POST https://your-instance.com/api/v1/agents \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Trading Agent",
    "tradingMode": "simulation"
  }'

List Agents

Get all agents for the authenticated user.

GET /api/v1/agents

Response

Success (200)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "My Trading Agent",
    "tradingMode": "simulation",
    "automatedTradingSimulation": true,
    "automatedTradingLive": false,
    "createdAt": "2025-01-20T10:30:00.000Z",
    "updatedAt": "2025-01-20T10:30:00.000Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Production Agent",
    "tradingMode": "live",
    "automatedTradingSimulation": false,
    "automatedTradingLive": true,
    "createdAt": "2025-01-15T08:00:00.000Z",
    "updatedAt": "2025-01-19T14:20:00.000Z"
  }
]

Returns agents ordered by createdAt descending (most recent first).

Example

curl -X GET https://your-instance.com/api/v1/agents \
  -H "Authorization: Bearer <access_token>"

Get Agent

Get a specific agent by ID.

GET /api/v1/agents/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Agent ID

Response

Success (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Trading Agent",
  "tradingMode": "simulation",
  "automatedTradingSimulation": true,
  "automatedTradingLive": false,
  "createdAt": "2025-01-20T10:30:00.000Z",
  "updatedAt": "2025-01-20T10:30:00.000Z"
}

Not Found (404)

{
  "error": "Agent not found"
}

Invalid ID Format (400)

{
  "error": "Invalid agent ID format"
}

Update Agent

Update an existing agent.

PUT /api/v1/agents/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Agent ID

Request

{
  "name": "Updated Agent Name",
  "tradingMode": "live",
  "automatedTradingSimulation": true,
  "automatedTradingLive": false
}

Field	Type	Required	Description
`name`	string	No	New agent name (max 255 characters)
`tradingMode`	string	No	`simulation` or `live`
`automatedTradingSimulation`	boolean	No	Enable automated trading in simulation
`automatedTradingLive`	boolean	No	Enable automated trading in live mode

⚠️

At least one field must be provided. All fields are optional but you cannot send an empty body.

Response

Success (200)

Returns the updated agent object.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Updated Agent Name",
  "tradingMode": "live",
  "automatedTradingSimulation": true,
  "automatedTradingLive": false,
  "createdAt": "2025-01-20T10:30:00.000Z",
  "updatedAt": "2025-01-20T12:45:00.000Z"
}

Delete Agent

Delete an agent and all associated data.

DELETE /api/v1/agents/:id

Path Parameters

Parameter	Type	Description
`id`	UUID	Agent ID

Response

Success (200)

{
  "success": true,
  "message": "Agent deleted successfully"
}

⚠️

This action is irreversible. Deleting an agent removes all associated positions, balance history, and trading configuration.

Get Trading Configuration

Get the complete trading configuration for an agent, merged with defaults.

GET /api/v1/agents/:id/config

Path Parameters

Parameter	Type	Description
`id`	UUID	Agent ID

Response

Success (200)

{
  "config": {
    "positionSizing": {
      "type": "percentage",
      "percentage": 5,
      "fixedAmountSol": null
    },
    "stopLoss": {
      "enabled": true,
      "percentage": 25
    },
    "takeProfit": {
      "enabled": false,
      "percentage": 50
    },
    "dca": {
      "enabled": false,
      "maxOrders": 3,
      "priceDropTriggerPercentage": 10,
      "amountPercentage": 50
    },
    "filters": {
      "minMarketCap": null,
      "maxMarketCap": null,
      "minLiquidity": null,
      "maxPositionAgeDays": null,
      "allowedTokens": [],
      "blockedTokens": []
    },
    "slippage": {
      "defaultBps": 300,
      "maxBps": 1000
    },
    "timing": {
      "minTimeBetweenTradesSeconds": 0
    }
  }
}

The response always contains the complete configuration with all defaults applied. If an agent has custom settings, they are merged with the defaults.

Update Trading Configuration

Update the trading configuration for an agent. Supports partial updates.

PUT /api/v1/agents/:id/config

Path Parameters

Parameter	Type	Description
`id`	UUID	Agent ID

Request

Send only the fields you want to update:

{
  "config": {
    "stopLoss": {
      "enabled": true,
      "percentage": 30
    },
    "positionSizing": {
      "percentage": 10
    }
  }
}

To reset to defaults:

{
  "config": null
}

Response

Success (200)

Returns the complete merged configuration after update.

Validation Error (400)

{
  "error": "Invalid trading configuration",
  "details": [
    "stopLoss.percentage must be between 1 and 100"
  ]
}

Example

curl -X PUT https://your-instance.com/api/v1/agents/:id/config \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "stopLoss": {
        "enabled": true,
        "percentage": 25
      }
    }
  }'

Agent Response Object

All agent endpoints return objects with this structure:

Field	Type	Description
`id`	UUID	Unique agent identifier
`userId`	UUID	Owner's user ID
`name`	string	Agent display name
`tradingMode`	string	Current mode: `simulation` or `live`
`automatedTradingSimulation`	boolean	Auto-trade enabled for simulation signals
`automatedTradingLive`	boolean	Auto-trade enabled for live signals
`createdAt`	ISO 8601	Creation timestamp
`updatedAt`	ISO 8601	Last update timestamp

Related Endpoints

Agent Positions - View and manage positions
Agent Balances - View balance information
Trading Signals - Send signals to agents

Token Refresh Agent Balances