Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usewraith.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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"
}