Wraith and WraithAgent SDK reference

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.

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

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

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

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.

Get Started

Core Concepts

Guides

SDK Reference

Roadmap

Wraith and WraithAgent SDK reference

`Wraith` class

Constructor

`WraithConfig`

`wraith.createAgent(config)`

`AgentConfig`

`wraith.agent(agentId)`

`wraith.getAgentByWallet(walletAddress)`

`wraith.getAgentByName(name)`

`wraith.listAgents()`

`WraithAgent` class

`agent.info`

`agent.chat(message, conversationId?)`

Parameters

`agent.getStatus()`

`agent.getBalance()`

`agent.scanPayments()`

`agent.exportKey(signature, message)`

`agent.getConversations()`

`agent.getMessages(conversationId)`

`agent.deleteConversation(conversationId)`

`agent.getNotifications()`

`agent.markNotificationsRead()`

`agent.clearNotifications()`

AI-powered tools

Example: invoicing

Example: privacy check

Authentication

Error handling

Get Started

Core Concepts

Guides

SDK Reference

Roadmap

​Wraith class

​Constructor

​WraithConfig

​wraith.createAgent(config)

​AgentConfig

​wraith.agent(agentId)

​wraith.getAgentByWallet(walletAddress)

​wraith.getAgentByName(name)

​wraith.listAgents()

​WraithAgent class

​agent.info

​agent.chat(message, conversationId?)

​Parameters

​agent.getStatus()

​agent.getBalance()

​agent.scanPayments()

​agent.exportKey(signature, message)

​agent.getConversations()

​agent.getMessages(conversationId)

​agent.deleteConversation(conversationId)

​agent.getNotifications()

​agent.markNotificationsRead()

​agent.clearNotifications()

​AI-powered tools

​Example: invoicing

​Example: privacy check

​Authentication

​Error handling

`Wraith` class

Constructor

`WraithConfig`

`wraith.createAgent(config)`

`AgentConfig`

`wraith.agent(agentId)`

`wraith.getAgentByWallet(walletAddress)`

`wraith.getAgentByName(name)`

`wraith.listAgents()`

`WraithAgent` class

`agent.info`

`agent.chat(message, conversationId?)`

Parameters

`agent.getStatus()`

`agent.getBalance()`

`agent.scanPayments()`

`agent.exportKey(signature, message)`

`agent.getConversations()`

`agent.getMessages(conversationId)`

`agent.deleteConversation(conversationId)`

`agent.getNotifications()`

`agent.markNotificationsRead()`

`agent.clearNotifications()`

AI-powered tools

Example: invoicing

Example: privacy check

Authentication

Error handling