API Endpoints

Authorization: Bearer wraith_live_abc123

X-AI-Provider: openai
X-AI-Key: sk-...

POST /agent/create

{
  name: string;          // "alice" (becomes alice.wraith)
  chain: string;         // "horizen" | "stellar" | "ethereum" | ...
  wallet: string;        // owner wallet address
  signature: string;     // EIP-191 or ed25519 signature
  message?: string;      // signed message (for verification)
}

{
  id: string;            // UUID
  name: string;          // "alice"
  chain: string;         // "horizen"
  address: string;       // agent's on-chain address
  metaAddress: string;   // stealth meta-address
}

GET /agents

GET /agent/:id

GET /agent/info/:name

GET /agent/wallet/:address

GET /agent/:id/status

{
  balance: string;
  tokens: Record<string, string>;
  pendingInvoices: number;
  address: string;
  metaAddress: string;
  chain: string;
}

POST /agent/:id/export

{
  signature: string;     // fresh signature from owner wallet
  message: string;       // signed message
}

{
  secret: string;        // "0x..." — the agent's private key
}

POST /agent/:id/chat

{
  message: string;
  conversationId?: string;  // continue existing conversation
}

{
  response: string;          // agent's text reply
  toolCalls?: ToolCall[];    // tools the agent executed
  conversationId: string;    // conversation ID for continuity
}

interface ToolCall {
  name: string;              // "send_payment", "scan_payments", etc.
  status: string;            // "success" or "error"
  detail?: string;           // JSON string with tool result
}

GET /agent/:id/conversations

interface Conversation {
  id: string;
  title: string;
  createdAt: string;
  updatedAt: string;
}

POST /agent/:id/conversations

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

Array<{
  role: "user" | "agent" | "tool" | "system";
  text: string;
  createdAt: string;
}>

DELETE /agent/:id/conversations/:convId

GET /invoice/:id

{
  id: string;
  agentName: string;
  amount: string;
  asset: string;
  memo: string;
  status: "pending" | "paid";
  txHash: string | null;
  paymentLink: string;
  createdAt: string;
}

POST /invoice/:id/paid

GET /agent/:id/notifications

{
  notifications: Notification[];
  unreadCount: number;
}

interface Notification {
  id: number;
  type: string;
  title: string;
  body: string;
  read: boolean;
  createdAt: string;
}

POST /agent/:id/notifications/read

DELETE /agent/:id/notifications

GET /health

{
  status: "ok";
}

GET /tee/info

GET /tee/attest/:agentId

{
  message: string;
  statusCode: number;
}

// 400 Bad Request
{
  "message": "Name must be 3-32 characters, lowercase alphanumeric and hyphens only",
  "statusCode": 400
}

// 401 Unauthorized
{
  "message": "Invalid API key",
  "statusCode": 401
}

// 409 Conflict
{
  "message": "Name 'alice' is already registered",
  "statusCode": 409
}