Skip to main content
The Wraith and WraithAgent classes are the primary interface for building with Wraith. They handle all communication with the managed TEE infrastructure.

Wraith Class

Constructor

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

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

WraithConfig

ParameterTypeRequiredDescription
apiKeystringYesYour Wraith platform API key
baseUrlstringNoOverride the API base URL (defaults to https://api.wraith.dev)
aiobjectNoBring your own AI model configuration
ai.provider"gemini" | "openai" | "claude"NoAI provider name
ai.apiKeystringNoYour AI provider API key

wraith.createAgent(config)

Create a new agent with a .wraith name and stealth keys.
import { Chain } from "@wraith-protocol/sdk";

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

AgentConfig

ParameterTypeRequiredDescription
namestringYesAgent name (becomes name.wraith)
chainChain | Chain[]YesTarget chain(s) for the agent
walletstringYesOwner wallet address
signaturestringYesEIP-191 signature proving wallet ownership
messagestringNoMessage that was signed (for verification)
Returns a WraithAgent instance.

wraith.agent(agentId)

Connect to an existing agent by ID. Does not make a network call.
const agent = wraith.agent("agent-uuid-here");

wraith.getAgentByWallet(walletAddress)

Look up an agent by its owner wallet address.
const agent = await wraith.getAgentByWallet("0xYourWallet");

wraith.getAgentByName(name)

Look up an agent by its .wraith name.
const agent = await wraith.getAgentByName("alice");

wraith.listAgents()

List all agents associated with your API key.
const agents = await wraith.listAgents();
// AgentInfo[]

WraithAgent Class

Returned by wraith.createAgent(), wraith.getAgentByWallet(), and wraith.getAgentByName(). Provides all agent operations.

agent.info

The agent’s identity information.
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..."

agent.chat(message, conversationId?)

Natural language interaction with the AI agent.
const response = await agent.chat("send 0.1 ETH to bob.wraith");
ParameterTypeRequiredDescription
messagestringYesNatural language message
conversationIdstringNoContinue an existing conversation
Returns a ChatResponse:
const res = await agent.chat("send 0.1 ETH to bob.wraith");
console.log(res.response);      // "Payment sent — 0.1 ETH to bob.wraith..."
console.log(res.toolCalls);     // [{ name: "send_payment", status: "success" }]
console.log(res.conversationId); // "conv-uuid"

// Continue the conversation
const followUp = await agent.chat("what was the tx hash?", res.conversationId);

agent.getStatus()

Get the agent’s current status including balance and stats.
const status = await agent.getStatus();

agent.getBalance()

Get the agent’s balance across all assets.
const balance = await agent.getBalance();
console.log(balance.native);  // "1.5"
console.log(balance.tokens);  // { ZEN: "100.0", USDC: "50.0" }

agent.scanPayments()

Scan for incoming stealth payments via the AI agent.
const payments = await agent.scanPayments();
// Payment[]

agent.exportKey(signature, message)

Export the agent’s private key. Requires a fresh wallet signature for verification.
const sig = await wallet.signMessage("Export private key for agent " + agent.info.id);
const { secret } = await agent.exportKey(sig, "Export private key for agent " + agent.info.id);
console.log(secret); // "0x..."

agent.getConversations()

List all conversations with this agent.
const conversations = await agent.getConversations();

agent.getMessages(conversationId)

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

agent.deleteConversation(conversationId)

Delete a conversation and its messages.
await agent.deleteConversation("conv-uuid");

agent.getNotifications()

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

agent.markNotificationsRead()

Mark all notifications as read.
await agent.markNotificationsRead();

agent.clearNotifications()

Delete all notifications.
await agent.clearNotifications();

AI-Powered Tools

When you use agent.chat(), the AI agent has access to these tools:
ToolWhat It Does
send_paymentSend a stealth payment to a meta-address or .wraith name
pay_agentPay another agent by .wraith name
scan_paymentsScan for incoming stealth payments
get_balanceCheck wallet balance (native + tokens)
create_invoiceCreate a payment invoice with a shareable link
check_invoicesCheck invoice payment statuses
withdrawWithdraw from a specific stealth address
withdraw_allWithdraw from all stealth addresses
schedule_paymentSchedule a recurring payment
list_schedulesList scheduled payments
cancel_scheduleCancel a scheduled payment
resolve_nameLook up a .wraith name
register_nameRegister a .wraith name on-chain
get_agent_infoGet full agent identity and TEE status
fund_walletRequest testnet tokens from faucet
privacy_checkRun a privacy analysis with scoring

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 includes:
HeaderValuePurpose
AuthorizationBearer wraith_...Platform API key
X-AI-Provider"openai" / "claude" / "gemini"Optional — for bring your own model
X-AI-Keysk-...Optional — your AI provider key

Error Handling

All methods throw on failure. The error message comes from the server:
try {
  await agent.chat("send 100 ETH to bob.wraith");
} catch (err) {
  console.error(err.message); // "Insufficient balance"
}