Documentation Index
Fetch the complete documentation index at: https://docs.joyride.exchange/llms.txt
Use this file to discover all available pages before exploring further.
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
- Get a nonce:
GET /v1/auth/nonce — returns a random nonce valid for 5 minutes
- Sign the message: Construct a SIWS message with the nonce and sign it with your Solana wallet
- Verify and get JWT:
POST /v1/auth/verify with wallet, signature, and nonce — returns a JWT
- 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
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
| Event | Description |
|---|
text | AI-generated text chunk (streamed incrementally) |
tool_start | Tool execution started — use for loading indicators |
tool_result | Tool execution completed with text summary |
strategy | Trade recommendation card for user confirmation |
table | Tabular data (positions, orders, etc.) |
options_chain | Options chain display data |
price_quote | Single instrument price quote |
account_summary | Account balance overview |
order_status | Order placement/cancellation result |
error | Non-fatal error during processing |
done | Stream complete — contains conversation ID and token usage |
Data Conventions
SSE events use human-readable units, unlike the main REST API:
| Field | SSE Events | Main REST API |
|---|
| Prices | USD (e.g., 1.50) | Micros (e.g., 1500000) |
| Sizes | Contracts (e.g., 2.0) | Millicontracts (e.g., 2000) |
| Balances | USD (e.g., 10000.0) | Micros (e.g., 10000000000) |
Error Codes
| Code | HTTP Status | Description |
|---|
UNAUTHORIZED | 401 | Missing or invalid JWT |
RATE_LIMITED | 429 | Too many requests — retry after the specified delay |
INVALID_REQUEST | 400 | Empty message, message too long, or invalid conversation ID |
NOT_FOUND | 404 | Conversation not found or not owned by this wallet |
INTERNAL_ERROR | 500 | Server error |
LLM_UNAVAILABLE | SSE | Claude API is unreachable (sent as SSE error event) |
LLM_ERROR | SSE | Error during LLM streaming |
TOOL_ERROR | SSE | Tool 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.
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.
