WebSocket Events

All WebSocket messages follow a standard structure with a type field identifying the message type.

Message Structure

All messages have this base structure:

interface WSMessage {
  type: string;
  data?: unknown;
  timestamp?: string;
}

Server → Client Events

`connected`

Sent immediately after successful authentication.

{
  "type": "connected",
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-20T10:30:00.000Z"
  }
}

Field	Type	Description
`data.agentId`	UUID	Connected agent ID
`data.timestamp`	ISO 8601	Connection time

`initial_data`

Sent after connected with all current open positions for the agent.

{
  "type": "initial_data",
  "data": {
    "positions": [
      {
        "id": "pos-123",
        "agentId": "550e8400-e29b-41d4-a716-446655440000",
        "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
        "tokenAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
        "tokenSymbol": "BONK",
        "purchasePrice": 0.00000234,
        "purchaseAmount": 1000000,
        "purchasePriceUsd": 0.000234,
        "currentPrice": 0.00000256,
        "currentPriceUsd": 0.000256,
        "positionValueSol": 2.56,
        "positionValueUsd": 256.00,
        "profitLossSol": 0.22,
        "profitLossUsd": 22.00,
        "profitLossPercent": 9.4,
        "priceChangePercent": 9.4,
        "currentStopLossPercentage": 25,
        "peakPrice": 0.00000260,
        "createdAt": "2025-01-20T08:00:00.000Z",
        "updatedAt": "2025-01-20T10:30:00.000Z",
        "purchaseTransactionId": "tx-abc123"
      }
    ],
    "timestamp": "2025-01-20T10:30:00.000Z"
  }
}

Position Fields

Field	Type	Description
`id`	string	Position ID
`agentId`	UUID	Agent ID
`walletAddress`	string	Wallet holding position
`tokenAddress`	string	Token mint address
`tokenSymbol`	string	Token ticker
`purchasePrice`	number	Buy price in SOL
`purchaseAmount`	number	Token amount
`purchasePriceUsd`	number	Buy price in USD
`currentPrice`	number	Current price in SOL
`currentPriceUsd`	number	Current price in USD
`positionValueSol`	number	Current value in SOL
`positionValueUsd`	number	Current value in USD
`profitLossSol`	number	P/L in SOL
`profitLossUsd`	number	P/L in USD
`profitLossPercent`	number	P/L percentage
`priceChangePercent`	number	Price change from entry
`currentStopLossPercentage`	number	Stop loss percentage
`peakPrice`	number	Highest price seen
`totalInvestedSol`	number	Total invested (with DCA)
`dcaCount`	number	Number of DCA orders
`createdAt`	ISO 8601	Position created time
`updatedAt`	ISO 8601	Last update time

Positions in initial_data come pre-enriched with current prices and P/L calculations from the server's price cache.

`position_update`

Sent when a position is created, updated, or closed.

Position Created

{
  "type": "position_update",
  "data": {
    "eventType": "position_created",
    "position": {
      "id": "pos-456",
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "tokenAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
      "tokenSymbol": "BONK",
      "purchasePrice": 0.00000234,
      "purchaseAmount": 500000,
      ...
    }
  }
}

Position Updated

Sent when position data changes (e.g., DCA order executed, stop loss adjusted):

{
  "type": "position_update",
  "data": {
    "eventType": "position_updated",
    "position": {
      "id": "pos-456",
      "dcaCount": 2,
      "totalInvestedSol": 1.5,
      ...
    }
  }
}

Position Closed

{
  "type": "position_update",
  "data": {
    "eventType": "position_closed",
    "positionId": "pos-456"
  }
}

Event Type	Fields	Description
`position_created`	`position`	Full position object
`position_updated`	`position`	Updated position object
`position_closed`	`positionId`	ID of closed position

`price_update`

Sent when a single token price changes (legacy, prefer price_update_batch).

{
  "type": "price_update",
  "data": {
    "tokenAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "price": 0.00000260,
    "priceUsd": 0.000260,
    "timestamp": "2025-01-20T10:30:05.000Z"
  }
}

Field	Type	Description
`tokenAddress`	string	Token mint address
`price`	number	Price in SOL
`priceUsd`	number	Price in USD

`price_update_batch`

Sent with multiple price updates at once (more efficient).

{
  "type": "price_update_batch",
  "data": {
    "updates": [
      {
        "tokenAddress": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
        "price": 0.00000260,
        "priceUsd": 0.000260
      },
      {
        "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "price": 0.0067,
        "priceUsd": 1.00
      }
    ],
    "timestamp": "2025-01-20T10:30:05.000Z"
  }
}

Price updates are only sent for tokens where the agent has open positions. This reduces unnecessary network traffic.

`ping`

Server heartbeat to check connection health. Client must respond with pong.

{
  "type": "ping",
  "timestamp": "2025-01-20T10:30:00.000Z"
}

`error`

Sent when an error occurs.

{
  "type": "error",
  "data": {
    "message": "Failed to load initial data: Database connection error"
  }
}

Client → Server Events

`pong`

Response to server ping. Required to keep connection alive.

{
  "type": "pong",
  "timestamp": "2025-01-20T10:30:00.000Z"
}

`ping`

Client can also send pings (optional). Server will respond with pong.

{
  "type": "ping",
  "timestamp": "2025-01-20T10:30:00.000Z"
}

`subscribe`

Acknowledge subscription (optional, subscription happens on connection).

{
  "type": "subscribe"
}

Server responds with:

{
  "type": "subscribed",
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

TypeScript Types

// Base message
interface WSMessage {
  type: string;
  data?: unknown;
  timestamp?: string;
}
 
// Server messages
interface ConnectedMessage extends WSMessage {
  type: 'connected';
  data: {
    agentId: string;
    timestamp: string;
  };
}
 
interface InitialDataMessage extends WSMessage {
  type: 'initial_data';
  data: {
    positions: EnrichedPosition[];
    timestamp: string;
  };
}
 
interface PositionUpdateMessage extends WSMessage {
  type: 'position_update';
  data: {
    eventType: 'position_created' | 'position_updated' | 'position_closed';
    position?: OpenPosition;
    positionId?: string;
  };
}
 
interface PriceUpdateMessage extends WSMessage {
  type: 'price_update';
  data: {
    tokenAddress: string;
    price: number;
    priceUsd: number;
    timestamp: string;
  };
}
 
interface PriceUpdateBatchMessage extends WSMessage {
  type: 'price_update_batch';
  data: {
    updates: Array<{
      tokenAddress: string;
      price: number;
      priceUsd: number;
    }>;
    timestamp: string;
  };
}
 
interface ErrorMessage extends WSMessage {
  type: 'error';
  data: {
    message: string;
  };
}
 
// Union type
type WebSocketMessage =
  | ConnectedMessage
  | InitialDataMessage
  | PositionUpdateMessage
  | PriceUpdateMessage
  | PriceUpdateBatchMessage
  | ErrorMessage;

Connection Example Implementations