Skip to main content

​
Overview

The MetaVault AI Agent system exposes a REST API for interacting with the Chat Agent and Strategy Sentinel Agent. The API provides endpoints for chat interactions, session management, and health monitoring. Base URL: http://localhost:8080 (configurable via CHAT_PORT environment variable)

​
Authentication

No authentication is currently required. Wallet addresses are passed in request bodies to identify users.

​
Endpoints

​
Health Check

curl http://localhost:8080/health
​
status
string
Server status (“ok” when running)
​
agent
string
Agent initialization status (“ready” or “initializing”)
​
timestamp
string
ISO 8601 timestamp of the response
​
sessions
number
Number of active chat sessions
{
  "status": "ok",
  "agent": "ready",
  "timestamp": "2026-03-02T10:30:00.000Z",
  "sessions": 3
}

​
Chat with Agent

Send a message to the Chat Agent and receive a response with optional unsigned transactions. 
curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is my vault balance?",
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "sessionId": "1234567890"
  }'
​
message
string
required
User message to send to the agent
​
wallet
string
required
User’s wallet address (required for all operations)
​
sessionId
string
Session ID to maintain conversation history. If not provided, a new session is created.
​
success
boolean
Whether the request was successful
​
sessionId
string
Session ID for this conversation
​
reply
string
Agent’s text response to the user
​
history
array
Full conversation history for this session
​
unsignedTx
object
default:"null"
Unsigned transaction for the user to sign, if applicable
​
step
string
Current transaction step (“approval”, “deposit”, “withdrawal”, “info”)
{
  "success": true,
  "sessionId": "1234567890",
  "reply": "Your vault balance is 100.50 LINK (equivalent to 95.23 shares).",
  "history": [
    {
      "role": "user",
      "content": "What is my vault balance?"
    },
    {
      "role": "assistant",
      "content": "Your vault balance is 100.50 LINK (equivalent to 95.23 shares)."
    }
  ],
  "unsignedTx": null,
  "step": "info"
}

​
Get Session History

Retrieve the full conversation history for a specific session. 
curl http://localhost:8080/session/1234567890
​
success
boolean
Whether the request was successful
​
sessionId
string
Session ID
​
data
object
Session data
{
  "success": true,
  "sessionId": "1234567890",
  "data": {
    "history": [
      {
        "role": "user",
        "content": "What is my balance?"
      },
      {
        "role": "assistant",
        "content": "Your vault balance is 100.50 LINK."
      }
    ],
    "createdAt": "2026-03-02T10:00:00.000Z",
    "updatedAt": "2026-03-02T10:15:00.000Z"
  }
}

​
Reset Session

Clear the conversation history for a specific session. 
curl -X POST http://localhost:8080/session/reset/1234567890
​
success
boolean
Whether the request was successful
​
sessionId
string
Session ID that was reset
​
message
string
Confirmation message
{
  "success": true,
  "sessionId": "1234567890",
  "message": "Session reset"
}

​
Error Responses

All endpoints return error responses in the following format:
​
error
string
Error message describing what went wrong
{
  "error": "Wallet address is required"
}
Common error status codes:
  • 400 - Bad request (missing required parameters)
  • 404 - Session not found
  • 500 - Internal server error (agent failure)

​
Session Management

  • Sessions are stored in-memory and will be lost on server restart
  • Each session maintains its own conversation history
  • Session IDs can be any string (typically timestamps or UUIDs)
  • Sessions are created automatically when a new session ID is used

​
Rate Limiting

No rate limiting is currently enforced. Implement your own rate limiting in production environments.

Build docs developers (and LLMs) love

Get started for freeTalk to us