Skip to main content

​
Overview

The AI Trading Assistant provides a conversational interface for interacting with the Joyride exchange. It can look up market data, analyze positions, and execute trades on your behalf through natural language.

​
Authentication

The AI Chat endpoint uses SIWS (Sign In With Solana) authentication with JWT sessions, separate from the main exchange API’s wallet header auth.

​
Auth Flow

  1. Get a nonce: GET /v1/auth/nonce — returns a random nonce valid for 5 minutes
  2. Sign the message: Construct a SIWS message with the nonce and sign it with your Solana wallet
  3. Verify and get JWT: POST /v1/auth/verify with wallet, signature, and nonce — returns a JWT
  4. Use the JWT: Include Authorization: Bearer <jwt> on all /v1/ai/chat requests

​
Sending Messages

Send a POST request to /v1/ai/chat with a JSON body: 
{
  "message": "What's the current price of SOL?",
  "conversation_id": null
}
  • message — your message text (max 10,000 characters)
  • conversation_id — omit or set to null for a new conversation; include a UUID to continue an existing one

​
SSE Response Format

Responses are streamed as Server-Sent Events (text/event-stream). Each event has a type and JSON data: 
event: text
data: {"content":"SOL is currently trading at $200."}

event: done
data: {"conversation_id":"550e8400-...","usage":{"input_tokens":150,"output_tokens":45}}

​
Event Types

EventDescription
textAI-generated text chunk (streamed incrementally)
tool_startTool execution started — use for loading indicators
tool_resultTool execution completed with text summary
strategyTrade recommendation card for user confirmation
tableTabular data (positions, orders, etc.)
options_chainOptions chain display data
price_quoteSingle instrument price quote
account_summaryAccount balance overview
order_statusOrder placement/cancellation result
errorNon-fatal error during processing
doneStream complete — contains conversation ID and token usage

​
Data Conventions

SSE events use human-readable units, unlike the main REST API:
FieldSSE EventsMain REST API
PricesUSD (e.g., 1.50)Micros (e.g., 1500000)
SizesContracts (e.g., 2.0)Millicontracts (e.g., 2000)
BalancesUSD (e.g., 10000.0)Micros (e.g., 10000000000)

​
Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid JWT
RATE_LIMITED429Too many requests — retry after the specified delay
INVALID_REQUEST400Empty message, message too long, or invalid conversation ID
NOT_FOUND404Conversation not found or not owned by this wallet
INTERNAL_ERROR500Server error
LLM_UNAVAILABLESSEClaude API is unreachable (sent as SSE error event)
LLM_ERRORSSEError during LLM streaming
TOOL_ERRORSSETool execution failed

​
Rate Limiting

The AI Chat endpoint is rate-limited to 20 requests per minute per wallet (configurable via AI_RATE_LIMIT_RPM). When rate limited, the API returns HTTP 429 with the number of seconds to wait.

​
Available Tools

The AI assistant has access to 21 tools spanning market data, account management, and trading: Market Data (8): options chain, ticker, orderbook, spot prices, market config, instruments, candles, volatility Account (6): balance, positions, open orders, trade history, profile, social stats Oracle (2): greeks, settlement info Trading (5): place order, cancel order, cancel all orders, deposit, update profile All trading actions include server-side validation (instrument checks, price/size limits) independent of the AI model.