Skip to main content
Wraith agents understand natural language. You can ask an agent to send a payment, check a balance, create an invoice, or scan for received payments — all through a conversational interface. Use conversationId to maintain context across multiple messages. All chat endpoints require a Bearer token in the Authorization header.

​
POST /agent/:id/chat

Send a message to an agent and receive its response. The agent interprets your message, executes any required on-chain operations as tool calls, and returns a natural language reply. Pass a conversationId to continue an existing conversation. If you omit it, the server creates a new conversation and returns its ID in the response.

​
Path parameters

​
id
string
required
The agent UUID.

​
Request

​
message
string
required
The natural language message to send to the agent.
​
conversationId
string
An existing conversation ID. Include this to continue a thread with shared context. If omitted, a new conversation is created.

​
Response

​
response
string
required
The agent’s natural language reply.
​
toolCalls
ToolCall[]
The on-chain or off-chain operations the agent executed to fulfill the request. Present only when the agent took action.
​
conversationId
string
required
The conversation ID for this exchange. Pass this in your next request to continue the thread.

​
Example

import { Wraith } from "@wraith-protocol/sdk";

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agent = wraith.agent("550e8400-e29b-41d4-a716-446655440000");

// Start a new conversation
const first = await agent.chat("What's my current balance?");
console.log(first.response);
// → "Your balance is 2.4 ETH on Horizen."

// Continue the conversation — pass conversationId as the second argument
const second = await agent.chat("Send 0.5 ETH to bob.wraith", first.conversationId);

if (second.toolCalls) {
  for (const call of second.toolCalls) {
    console.log(`${call.name}: ${call.status}`);
    // → "send_payment: success"
  }
}

​
GET /agent/:id/conversations

List all conversation threads for an agent.

​
Path parameters

​
id
string
required
The agent UUID.

​
Response

Returns an array of Conversation objects.
​
id
string
required
The conversation ID.
​
title
string
required
Auto-generated title summarizing the conversation topic.
​
createdAt
string
required
ISO 8601 timestamp when the conversation was created.
​
updatedAt
string
required
ISO 8601 timestamp of the last message.

​
Example

import { Wraith } from "@wraith-protocol/sdk";

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agent = wraith.agent("550e8400-e29b-41d4-a716-446655440000");

const conversations = await agent.getConversations();

for (const conv of conversations) {
  console.log(`${conv.id}: ${conv.title} (updated ${conv.updatedAt})`);
}

​
POST /agent/:id/conversations

Create a new, empty conversation thread. Use this to pre-create a conversation ID before your first message, or to reset context without waiting for the agent to respond.

​
Path parameters

​
id
string
required
The agent UUID.

​
Response

Returns a single Conversation object with the new conversation ID.

​
Example

curl -X POST https://api.wraith.dev/agent/550e8400-e29b-41d4-a716-446655440000/conversations \
  -H "Authorization: Bearer wraith_live_abc123"
The SDK does not expose a createConversation method. Conversations are created automatically by agent.chat() when you omit the conversationId argument. Use this HTTP endpoint only when you need to pre-create a conversation ID before the first message.

​
GET /agent/:id/conversations/:convId/messages

Retrieve the full message history for a conversation. Use this to display conversation logs in your UI or to audit what the agent did.

​
Path parameters

​
id
string
required
The agent UUID.
​
convId
string
required
The conversation ID.

​
Response

Returns an array of message objects in chronological order.
​
role
string
required
Who sent this message: "user", "agent", "tool", or "system".
​
text
string
required
The message content. For "tool" messages, this is a JSON-encoded result.
​
createdAt
string
required
ISO 8601 timestamp when the message was created.

​
Example

import { Wraith } from "@wraith-protocol/sdk";

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agent = wraith.agent("550e8400-e29b-41d4-a716-446655440000");

const messages = await agent.getMessages("conv_abc123");

for (const msg of messages) {
  console.log(`[${msg.role}] ${msg.text}`);
}

​
DELETE /agent/:id/conversations/:convId

Delete a conversation and all its messages. This is permanent and cannot be undone.

​
Path parameters

​
id
string
required
The agent UUID.
​
convId
string
required
The conversation ID to delete.

​
Example

import { Wraith } from "@wraith-protocol/sdk";

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agent = wraith.agent("550e8400-e29b-41d4-a716-446655440000");

await agent.deleteConversation("conv_abc123");

​
The ToolCall interface

When an agent executes an action (sending a payment, creating an invoice, scanning for received funds), it returns a ToolCall in the response. Parse detail to get the structured result: 
import type { ToolCall } from "@wraith-protocol/sdk";

function handleToolCalls(toolCalls: ToolCall[]) {
  for (const call of toolCalls) {
    if (call.status === "error") {
      console.error(`Tool ${call.name} failed:`, call.detail);
      continue;
    }

    // detail is a JSON string — parse it for the structured result
    const result = call.detail ? JSON.parse(call.detail) : null;

    switch (call.name) {
      case "send_payment":
        console.log(`Payment sent: ${result?.txHash}`);
        break;
      case "scan_payments":
        console.log(`Found ${result?.count} payments`);
        break;
      case "create_invoice":
        console.log(`Invoice created: ${result?.id}`);
        break;
    }
  }
}