Send message to AI assistant

Send a message to the AI trading assistant and receive a streaming response via Server-Sent Events (SSE).

Authentication: Requires a JWT from /v1/auth/verify as a Bearer token.

Rate limiting: 20 requests per minute per wallet (configurable via AI_RATE_LIMIT_RPM).

Response format: The response is an SSE stream (text/event-stream). Each event has an event type and JSON data field. The stream ends with a done event containing the conversation ID and token usage.

Conversation continuity: Omit conversation_id to start a new conversation. Include it to continue an existing conversation with message history.

SSE event types:

text — AI-generated text chunk (streamed incrementally)
tool_start — Tool execution started (for UX loading indicators)
tool_result — Tool execution completed with summary
strategy — Trade recommendation card for user confirmation
table — Tabular data display
options_chain — Options chain data
price_quote — Single instrument price quote
account_summary — Account balance overview
order_status — Order placement/cancellation result
error — Error during processing (non-fatal, stream may continue)
done — Stream complete with conversation ID and usage stats

Data conventions in SSE events: Unlike the main REST API which uses internal units (micros, millicontracts), AI Chat SSE events use human-readable units:

Prices in USD (e.g., 1.50 not 1500000)
Sizes in contracts (e.g., 2.0 not 2000)
Balances in USD (e.g., 10000.0 not 10000000000)

POST

chat

Send message to AI assistant

curl --request POST \
  --url https://joyride.exchange/api/v1/ai/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "message": "What's the current price of SOL?",
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000"
}
EOF

"event: text\ndata: {\"content\":\"SOL is currently trading at $200.\"}\n\nevent: done\ndata: {\"conversation_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"usage\":{\"input_tokens\":150,\"output_tokens\":45}}\n"

Authorizations

Authorization

string

header

required

JWT obtained from POST /v1/auth/verify after SIWS authentication. Include as: Authorization: Bearer <jwt>

Body

application/json

message

string

required

User message text (max 10,000 characters)

Maximum string length: 10000

Example:

"What's the current price of SOL?"

conversation_id

string<uuid>

Existing conversation ID to continue. Omit to start a new conversation.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

SSE stream of AI response events

Server-Sent Events stream. Each event has format:

event: <type>
data: <json>

Verify SIWS signature and get JWT

List conversations

Send message to AI assistant

curl --request POST \
  --url https://joyride.exchange/api/v1/ai/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "message": "What's the current price of SOL?",
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000"
}
EOF

"event: text\ndata: {\"content\":\"SOL is currently trading at $200.\"}\n\nevent: done\ndata: {\"conversation_id\":\"550e8400-e29b-41d4-a716-446655440000\",\"usage\":{\"input_tokens\":150,\"output_tokens\":45}}\n"

Documentation Index

Authorizations

Body

Response