Skip to main content
Wraith gives every agent a .wraith name, an on-chain address, and a stealth meta-address — all derived inside a TEE so your keys never leave secure hardware. This guide covers the complete lifecycle for a single-chain agent from creation through withdrawal.
All examples use Chain.Horizen. Swap in any supported chain — the SDK interface is identical.

​
Prerequisites

Install the SDK before you begin: 
npm install @wraith-protocol/sdk
You also need a Wraith API key and a wallet that can sign messages (MetaMask, viem, ethers, or any EIP-191-compatible signer).

​
Full lifecycle

1

Create the agent

Sign a message with your owner wallet to prove ownership, then create the agent.
import { Wraith, Chain } from "@wraith-protocol/sdk";

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

const message = "Sign to create Wraith agent";
const signature = await wallet.signMessage(message);

const agent = await wraith.createAgent({
  name: "alice",
  chain: Chain.Horizen,
  wallet: walletAddress,
  signature: signature,
  message: message,
});
The agent is now live with a .wraith name, an on-chain address, and a stealth meta-address:
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..."
2

Fund the agent

On testnet, ask the agent to request tokens from the faucet:
const res = await agent.chat("fund my wallet");
console.log(res.response);
// "Wallet funded with testnet ETH. Balance: 0.5 ETH"
3

Check your balance

Use natural language or the programmatic method:
const res = await agent.chat("what's my balance?");
// "Balance: 0.5 ETH, 0 ZEN, 0 USDC"
4

Send a stealth payment

Address the recipient by their .wraith name. The agent resolves the name, generates a one-time stealth address, sends the funds, and publishes an on-chain announcement — all in one step.
const res = await agent.chat("send 0.1 ETH to bob.wraith");
console.log(res.response);
// "Payment sent — 0.1 ETH to bob.wraith via stealth address 0x7a3f..."
Behind the scenes the agent:
  1. Resolves bob.wraith to a stealth meta-address
  2. Generates a one-time stealth address from that meta-address
  3. Sends ETH to the stealth address
  4. Publishes an on-chain announcement so the recipient can detect the payment
5

Scan for incoming payments

The agent scans announcements on-chain and filters for transfers to your stealth keys:
const res = await agent.chat("scan for payments");
console.log(res.response);
// "Found 2 incoming payments:
//  - 0.1 ETH at 0xabc... (balance: 0.1 ETH)
//  - 0.05 ETH at 0xdef... (balance: 0.05 ETH)"
6

Withdraw

Move funds out of a specific stealth address or sweep everything at once.
const res = await agent.chat(
  "withdraw 0.05 ETH from 0xabc... to 0xMyWallet"
);
Withdrawing all stealth addresses to a single known wallet links every incoming payment to your identity. Read the privacy best practices guide before sweeping funds.

​
Error handling

All SDK methods throw on failure. Wrap calls in try/catch to handle errors: 
try {
  const res = await agent.chat("send 100 ETH to bob.wraith");
} catch (err) {
  console.error(err.message); // "Insufficient balance"
}

​
Reconnect to an existing agent

If the agent already exists, reconnect without creating a new one. Three lookup methods are available: 
// By agent ID (no network call)
const agent = wraith.agent("agent-uuid");

// By owner wallet address
const agent = await wraith.getAgentByWallet("0xMyWallet");

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

​
Additional features

​
Invoicing

Create a shareable payment link with a memo: 
const res = await agent.chat(
  "create an invoice for 0.5 ETH with memo design work"
);
console.log(res.response);
// "Invoice created — [Pay 0.5 ETH](https://pay.wraith.dev/invoice/uuid)"

// Check status later
await agent.chat("check my invoices");

​
Recurring payments

Schedule a payment and manage it by ID: 
const res = await agent.chat(
  "schedule 0.1 ETH to bob.wraith every week"
);
// "Scheduled: 0.1 ETH to bob.wraith weekly, next run in 7 days"

await agent.chat("list my schedules");
await agent.chat("cancel schedule abc-123");

​
Privacy check

Ask the agent to analyse your stealth address activity and surface any privacy risks: 
const res = await agent.chat("run a privacy check");
console.log(res.response);
// "Privacy Score: 90/100
//  Issues:
//  - (info) 3 unspent stealth addresses
//  Best Practices:
//  - Use a fresh destination for each withdrawal
//  - Space withdrawals at least 1 hour apart
//  - Vary payment amounts slightly"

​
Conversation history

The agent remembers context within a conversation. Pass conversationId to continue a thread: 
const res1 = await agent.chat("send 0.1 ETH to bob.wraith");
const convId = res1.conversationId;

const res2 = await agent.chat("what was the tx hash?", convId);

// Manage conversations
const conversations = await agent.getConversations();
const messages     = await agent.getMessages(convId);
await agent.deleteConversation(convId);

​
Export private key

If you need the agent’s raw private key, sign a fresh message to authorise the export: 
const exportSig = await wallet.signMessage(
  "Export private key for agent " + agent.info.id
);
const { secret } = await agent.exportKey(
  exportSig,
  "Export private key for agent " + agent.info.id
);
console.log(secret); // "0x..."
Store the exported private key securely. Anyone with access to it has full control of the agent’s funds.

​
What’s next

Multichain setup

Run one agent across Horizen, Stellar, Ethereum, and more.

Privacy best practices

Avoid timing correlation, amount fingerprinting, and address reuse.

Bring your own model

Use OpenAI or Claude instead of the default Gemini model.

SDK reference

Full API documentation for the Wraith and WraithAgent classes.