Agent API Endpoints

REST API endpoints for MetaVault AI Agent system

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

Show properties

to · string

Contract address to send transaction to

data · string

Encoded function call data

value · string

ETH value to send (usually “0” for token operations)

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

Show properties

history · array

Array of chat messages

createdAt · string

ISO 8601 timestamp when session was created

updatedAt · string

ISO 8601 timestamp when session was last updated

{
  "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.