Overview Chat sessions enable persistent conversation history tied to wallet addresses. Each session stores messages with metadata including payment transactions and AI-generated images.
All chat endpoints require Supabase to be configured. If unavailable, endpoints return 503 Service Unavailable.
Get All Sessions curl -X GET "https://api.example.com/chat/sessions?wallet=0x1234..."
Query Parameters Wallet address to fetch sessions for
{ "success" : true , "sessions" : [ { "id" : "550e8400-e29b-41d4-a716-446655440000" , "wallet_address" : "0x1234..." , "title" : "DeFi Yield Analysis" , "created_at" : "2026-03-01T10:00:00.000Z" , "updated_at" : "2026-03-03T10:30:00.000Z" , "message_count" : 24 }, { "id" : "660e8400-e29b-41d4-a716-446655440001" , "wallet_address" : "0x1234..." , "title" : "NFT Floor Prices" , "created_at" : "2026-02-28T15:00:00.000Z" , "updated_at" : "2026-03-02T09:15:00.000Z" , "message_count" : 8 } ] }
Response Fields Whether the request succeeded
Array of chat session objects Session title (can be null)
ISO 8601 timestamp of session creation
ISO 8601 timestamp of last update
Number of messages in this session
Create Session curl -X POST https://api.example.com/chat/sessions \ -H "Content-Type: application/json" \ -d '{ "walletAddress": "0x1234...", "title": "Token Price Analysis" }'
Request Body Wallet address that owns this session
Optional session title (defaults to timestamp-based title)
{ "success" : true , "session" : { "id" : "770e8400-e29b-41d4-a716-446655440002" , "wallet_address" : "0x1234..." , "title" : "Token Price Analysis" , "created_at" : "2026-03-03T10:45:00.000Z" , "updated_at" : "2026-03-03T10:45:00.000Z" } }
Delete Session DELETE /chat/sessions/:sessionId
curl -X DELETE "https://api.example.com/chat/sessions/550e8400-e29b-41d4-a716-446655440000?wallet=0x1234..."
Path Parameters UUID of the session to delete
Query Parameters Wallet address (must match session owner for authorization)
Deleting a session also deletes all messages in that session. This action cannot be undone.
Get Messages GET /chat/sessions/:sessionId/messages
curl -X GET https://api.example.com/chat/sessions/550e8400-e29b-41d4-a716-446655440000/messages
Path Parameters { "success" : true , "messages" : [ { "id" : "msg-1234567890" , "session_id" : "550e8400-e29b-41d4-a716-446655440000" , "content" : "What's the price of BTC?" , "is_user" : true , "escrow_id" : null , "tx_hash" : "0xabc..." , "image_preview" : null , "created_at" : "2026-03-03T10:30:00.000Z" }, { "id" : "msg-1234567891" , "session_id" : "550e8400-e29b-41d4-a716-446655440000" , "content" : "Bitcoin is currently trading at $65,000 USD." , "is_user" : false , "escrow_id" : "123" , "tx_hash" : "0xdef..." , "image_preview" : null , "created_at" : "2026-03-03T10:30:05.000Z" } ] }
Response Fields Whether the request succeeded
Array of message objects, ordered by creation time Unique message identifier
True if sent by user, false if AI response
Associated escrow ID (null for user messages)
Payment transaction hash (null if no payment)
Base64-encoded image data URL for image queries (null if text-only)
Save Message POST /chat/sessions/:sessionId/messages
curl -X POST https://api.example.com/chat/sessions/550e8400-e29b-41d4-a716-446655440000/messages \ -H "Content-Type: application/json" \ -d '{ "id": "msg-1234567892", "content": "Show me yield opportunities on Arbitrum", "is_user": true, "tx_hash": "0xabc123...", "image_preview": null }'
Path Parameters Request Body Unique message ID (client-generated)
True if user message, false if AI response
Associated escrow ID (for AI responses with payments)
Base64-encoded image data URL (for image-based queries)
{ "success" : true , "message" : { "id" : "msg-1234567892" , "session_id" : "550e8400-e29b-41d4-a716-446655440000" , "content" : "Show me yield opportunities on Arbitrum" , "is_user" : true , "escrow_id" : null , "tx_hash" : "0xabc123..." , "image_preview" : null , "created_at" : "2026-03-03T10:50:00.000Z" } }
Clear Messages DELETE /chat/sessions/:sessionId/messages
curl -X DELETE https://api.example.com/chat/sessions/550e8400-e29b-41d4-a716-446655440000/messages
Path Parameters Deletes all messages in the session, but keeps the session itself.
Error Responses { "success" : false , "error" : "Wallet address required" }
500 Internal Server Error
{ "success" : false , "error" : "Failed to create session" }
{ "success" : false , "error" : "Supabase unavailable. Check SUPABASE_URL/SUPABASE_ANON_KEY and restart backend." }
Integration Example // Create a new chat session const createSession = async ( walletAddress : string ) => { const response = await fetch ( 'https://api.example.com/chat/sessions' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ walletAddress , title: 'New Conversation' , }), }); const { session } = await response . json (); return session . id ; }; // Save user message const saveUserMessage = async ( sessionId : string , content : string , txHash : string ) => { await fetch ( `https://api.example.com/chat/sessions/ ${ sessionId } /messages` , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ id: `msg- ${ Date . now () } ` , content , is_user: true , tx_hash: txHash , }), }); }; // Save AI response const saveAIResponse = async ( sessionId : string , content : string , escrowId : string ) => { await fetch ( `https://api.example.com/chat/sessions/ ${ sessionId } /messages` , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ id: `msg- ${ Date . now () } ` , content , is_user: false , escrow_id: escrowId , }), }); }; // Load conversation history const loadHistory = async ( sessionId : string ) => { const response = await fetch ( `https://api.example.com/chat/sessions/ ${ sessionId } /messages` ); const { messages } = await response . json (); return messages ; };
Database Schema Chat sessions are stored in Supabase with the following structure:
chat_sessions table:
id (uuid, primary key)wallet_address (text)title (text, nullable)created_at (timestamp)updated_at (timestamp)
messages table:
id (text, primary key)session_id (uuid, foreign key)content (text)is_user (boolean)escrow_id (text, nullable)tx_hash (text, nullable)image_preview (text, nullable)created_at (timestamp)
Messages are automatically ordered by created_at when fetched.