Wraith and WraithAgent SDK reference

Complete reference for the Wraith and WraithAgent classes — create agents, send payments, scan for transfers, manage conversations, and handle notifications.

The agent client is the primary way to build with Wraith Protocol. You instantiate a Wraith client with your API key, then use it to create or retrieve WraithAgent instances. Every agent operation — sending payments, scanning for incoming transfers, invoicing, scheduled payments, and privacy analysis — is available through the agent or through natural language via agent.chat().

Wraith class

Constructor

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

const wraith = new Wraith({
  apiKey: "wraith_live_abc123",
});

WraithConfig

apiKey · string · required

Your Wraith platform API key. Keys start with wraith_live_ for production and wraith_test_ for testnet.

baseUrl · string

Override the API base URL. Defaults to https://api.wraith.dev. Useful for self-hosted or local development setups.

ai · object

Bring-your-own-model configuration. Omit this to use Wraith’s default Gemini-powered AI.

Show ai properties

ai.provider · "gemini" | "openai" | "claude"

The AI provider to use for the agent’s language model.

ai.apiKey · string

Your API key for the chosen AI provider.

wraith.createAgent(config)

Create a new agent with a .wraith name, stealth keys, and an on-chain identity. Returns a WraithAgent instance.

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

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });

const agent = await wraith.createAgent({
  name: "alice",
  chain: Chain.Horizen,
  wallet: "0xYourWallet",
  signature: "0xSignatureFromWallet",
});

AgentConfig

name · string · required

The agent’s name. Becomes name.wraith on-chain. Must be unique across the platform.

chain · Chain | Chain[] · required

The chain or chains the agent operates on. Pass a single Chain value, an array of Chain values, or Chain.All to cover all supported chains.

wallet · string · required

The owner wallet address. This wallet controls the agent and is required for key export.

signature · string · required

An EIP-191 signature proving ownership of the wallet address.

message · string

The message that was signed. Provided for signature verification. Optional if the platform uses a fixed message.

Returns: Promise<WraithAgent>

wraith.agent(agentId)

Connect to an existing agent by its UUID. This method does not make a network call — it returns a WraithAgent instance bound to the given ID. Any subsequent operation on the instance will make the appropriate API request.

const agent = wraith.agent("agent-uuid-here");

Returns: WraithAgent

wraith.getAgentByWallet(walletAddress)

Look up an agent by its owner wallet address.

const agent = await wraith.getAgentByWallet("0xYourWallet");

Returns: Promise<WraithAgent>

wraith.getAgentByName(name)

Look up an agent by its .wraith name.

const agent = await wraith.getAgentByName("alice");

Returns: Promise<WraithAgent>

wraith.listAgents()

List all agents associated with your API key.

const agents = await wraith.listAgents();
// AgentInfo[]

Returns: Promise<AgentInfo[]>

AgentInfo · object

Show properties

id · string

UUID of the agent.

name · string

The agent’s .wraith name (without the .wraith suffix).

chains · Chain[]

The chains this agent is active on.

addresses · Record<Chain, string>

The agent’s wallet address on each chain.

metaAddresses · Record<Chain, string>

The agent’s stealth meta-address on each chain, e.g. "st:eth:0x...".

---

WraithAgent class

WraithAgent is returned by wraith.createAgent(), wraith.getAgentByWallet(), and wraith.getAgentByName(). It provides all agent operations.

agent.info

The agent’s identity, available synchronously after the agent is resolved.

console.log(agent.info.id);                           // "uuid-..."
console.log(agent.info.name);                         // "alice"
console.log(agent.info.chains);                       // [Chain.Horizen]
console.log(agent.info.addresses[Chain.Horizen]);      // "0x..."
console.log(agent.info.metaAddresses[Chain.Horizen]);  // "st:eth:0x..."

Type: AgentInfo

agent.chat(message, conversationId?)

Send a natural language message to the AI agent and receive a response. The agent has access to 17 tools (see AI tools below) and can execute on-chain operations autonomously.

const response = await agent.chat("send 0.1 ETH to bob.wraith");
console.log(response.response);       // "Payment sent — 0.1 ETH to bob.wraith..."
console.log(response.toolCalls);      // [{ name: "send_payment", status: "success" }]
console.log(response.conversationId); // "conv-uuid"

To continue a conversation across multiple turns, pass the conversationId from the previous response:

const first = await agent.chat("create an invoice for 50 USDC");
const followUp = await agent.chat("what's the payment link?", first.conversationId);

Parameters

message · string · required

The natural language message to send to the agent.

conversationId · string

The ID of an existing conversation to continue. Omit to start a new conversation.

Returns: Promise<ChatResponse>

ChatResponse · object

Show properties

response · string

The agent’s natural language reply.

toolCalls · ToolCall[]

List of tools the agent invoked during this turn.

Show ToolCall properties

name · string

Tool name, e.g. "send_payment".

status · string

Outcome status, e.g. "success" or "error".

detail · string

Optional additional detail about the tool execution.

conversationId · string

ID of the conversation. Use this to continue the conversation in a future call.

agent.getStatus()

Get the agent’s current operational status, including balance and activity statistics.

const status = await agent.getStatus();

Returns: Promise<object>

agent.getBalance()

Get the agent’s balance across all assets on its active chains.

const balance = await agent.getBalance();
console.log(balance.native);  // "1.5"
console.log(balance.tokens);  // { ZEN: "100.0", USDC: "50.0" }

Returns: Promise<Balance>

Balance · object

Show properties

native · string

Native asset balance as a decimal string.

tokens · Record<string, string>

Token balances keyed by token symbol.

agent.scanPayments()

Scan on-chain announcements for incoming stealth payments addressed to this agent. Returns all detected unspent payments.

const payments = await agent.scanPayments();
// Payment[]

Returns: Promise<Payment[]>

Payment · object

Show properties

stealthAddress · string

The one-time stealth address that received the payment.

balance · string

Detected balance at this stealth address.

ephemeralPubKey · string

Ephemeral public key from the announcement, used to derive the stealth private key.

agent.exportKey(signature, message)

Export the agent’s private key from the TEE. Requires a fresh wallet signature from the agent’s owner wallet as proof of authorization. The private key never leaves the TEE except through this authenticated export.

const msgToSign = "Export private key for agent " + agent.info.id;
const sig = await wallet.signMessage(msgToSign);
const { secret } = await agent.exportKey(sig, msgToSign);
console.log(secret); // "0x..."

signature · string · required

A fresh EIP-191 signature from the agent’s owner wallet.

message · string · required

The exact message that was signed.

Returns: Promise<{ secret: string }>

Store the exported key securely. Once exported, treat it with the same care as any private key. The TEE retains its copy — exporting does not revoke the agent.

agent.getConversations()

List all conversations with this agent.

const conversations = await agent.getConversations();

Returns: Promise<Conversation[]>

Conversation · object

Show properties

id · string

Conversation UUID.

title · string

Auto-generated title from the first message.

createdAt · string

ISO 8601 timestamp.

updatedAt · string

ISO 8601 timestamp of the most recent message.

agent.getMessages(conversationId)

Retrieve all messages from a specific conversation.

const messages = await agent.getMessages("conv-uuid");
// [{ role: "user", text: "..." }, { role: "agent", text: "..." }]

conversationId · string · required

The UUID of the conversation to retrieve.

Returns: Promise<Array<{ role: string; text: string }>>

agent.deleteConversation(conversationId)

Delete a conversation and all its messages. This action is permanent.

await agent.deleteConversation("conv-uuid");

conversationId · string · required

The UUID of the conversation to delete.

Returns: Promise<void>

agent.getNotifications()

Get all notifications for this agent, along with the count of unread notifications.

const { notifications, unreadCount } = await agent.getNotifications();

Returns: Promise<{ notifications: Notification[]; unreadCount: number }>

Notification · object

Show properties

id · number

Notification ID.

type · string

Notification category, e.g. "payment_received".

title · string

Short notification title.

body · string

Full notification text.

read · boolean

Whether the notification has been read.

createdAt · string

ISO 8601 timestamp.

agent.markNotificationsRead()

Mark all notifications for this agent as read.

await agent.markNotificationsRead();

Returns: Promise<void>

agent.clearNotifications()

Delete all notifications for this agent.

await agent.clearNotifications();

Returns: Promise<void>

---

AI-powered tools

When you call agent.chat(), the agent’s language model has access to these 17 tools. You do not call these directly — the AI invokes them automatically based on your natural language request.

Tool	What it does
send_payment	Send a stealth payment to a meta-address or .wraith name
pay_agent	Pay another agent by .wraith name
scan_payments	Scan on-chain announcements for incoming stealth payments
get_balance	Check wallet balance (native asset + tokens)
create_invoice	Create a payment invoice with a shareable link
check_invoices	Check status of existing invoices
withdraw	Withdraw funds from a specific stealth address
withdraw_all	Withdraw from all detected stealth addresses
schedule_payment	Schedule a recurring stealth payment
list_schedules	List all scheduled payments
cancel_schedule	Cancel a scheduled payment
resolve_name	Look up a .wraith name on-chain
register_name	Register a .wraith name on-chain
get_agent_info	Get full agent identity and TEE attestation status
fund_wallet	Request testnet tokens from the chain faucet
privacy_check	Run a privacy analysis with a scored report

Example: invoicing

const res = await agent.chat("create an invoice for 1.0 ETH with memo consulting fee");
console.log(res.response);
// "Invoice created — [Pay 1.0 ETH](https://pay.wraith.dev/invoice/...)"

Example: privacy check

const res = await agent.chat("run a privacy check");
console.log(res.response);
// "Privacy Score: 85/100
//  Issues:
//  - (medium) 7 unspent stealth addresses — consider consolidating
//  Best Practices:
//  - Use a fresh destination for each withdrawal
//  - Space withdrawals at least 1 hour apart"

---

Authentication

Every request the SDK makes includes the following headers automatically:

Header	Value	Purpose
Authorization	Bearer wraith_...	Platform API key authentication
X-AI-Provider	"openai" / "claude" / "gemini"	Specifies the AI provider when using bring-your-own-model
X-AI-Key	sk-...	Your AI provider API key when using bring-your-own-model

You do not need to set these headers manually — the Wraith client handles them based on the WraithConfig you provide.

---

Error handling

All SDK methods throw on failure. The error message comes directly from the server response.

try {
  await agent.chat("send 100 ETH to bob.wraith");
} catch (err) {
  console.error(err.message); // "Insufficient balance"
}

Errors are plain Error instances. Check err.message for the server-provided reason. Future SDK versions may add structured error types with status codes.