Single-Chain Agent: Complete Lifecycle Walkthrough

A single-chain agent gives you a complete private payment identity on one blockchain — a .wraith name, a stealth meta-address, and an AI agent running inside a TEE that handles everything through natural language. This guide covers every operation from creation to key export.

Main flow

Install the SDK

Add @wraith-protocol/sdk to your project.

npm install @wraith-protocol/sdk

Create the agent

Sign a message to prove wallet ownership, then call createAgent with a name and target chain.

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

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

// Sign a message to prove wallet ownership
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 on Horizen with:

A .wraith name: alice.wraith
An on-chain address for receiving direct transfers
A stealth meta-address for receiving private payments
An AI agent running inside the TEE

Inspect the agent’s identity:

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

Fund the agent

On testnet, request tokens from the faucet through the agent’s chat interface.

const res = await agent.chat("fund my wallet");
console.log(res.response);
// "Wallet funded with testnet ETH. Balance: 0.5 ETH"

Check balance

Ask the agent for your balance in natural language, or call getBalance directly.

const res = await agent.chat("what's my balance?");
// "Balance: 0.5 ETH, 0 ZEN, 0 USDC"

Or programmatically:

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

Send a stealth payment

Sending to a .wraith name automatically generates a one-time stealth address.

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

Under the hood, the agent:

Resolves bob.wraith to a stealth meta-address
Generates a one-time stealth address
Sends ETH to the stealth address
Publishes an on-chain announcement

Scan for incoming payments

Scan finds stealth addresses sent to your meta-address that only you can spend.

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

Withdraw

Withdraw from a specific stealth address or sweep everything at once.

Specific address
Withdraw all

const res = await agent.chat("withdraw 0.05 ETH from 0xabc... to 0xMyWallet");

const res = await agent.chat("withdraw all to 0xMyWallet");
// The agent warns about privacy risks first

Withdrawing all stealth addresses to a single known wallet links every incoming payment to your identity. The agent will warn you before executing — see Privacy best practices for how to avoid this.

Invoicing

Create a shareable payment link with a fixed amount and 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 the status of outstanding invoices:

const res = await agent.chat("check my invoices");

Scheduled payments

Set up a recurring payment and the agent handles it on schedule.

const res = await agent.chat("schedule 0.1 ETH to bob.wraith every week");
console.log(res.response);
// "Scheduled: 0.1 ETH to bob.wraith weekly, next run in 7 days"

Manage your schedules:

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

Privacy check

Run a full analysis of your stealth address activity to get a score and actionable recommendations.

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"

Run a privacy check regularly, especially before making large withdrawals. See the full scoring algorithm in Privacy best practices.

Notifications

Fetch new notifications, mark them read, or clear them entirely.

const { notifications, unreadCount } = await agent.getNotifications();
console.log(unreadCount); // 2

await agent.markNotificationsRead();
await agent.clearNotifications();

Conversations

The agent maintains conversation history so follow-up questions have full context.

// Start a conversation
const res1 = await agent.chat("send 0.1 ETH to bob.wraith");
const convId = res1.conversationId;

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

// List and manage conversations
const conversations = await agent.getConversations();
const messages = await agent.getMessages(convId);
await agent.deleteConversation(convId);

Export private key

Export the agent’s private key for use in an external wallet. This requires a fresh wallet signature from the owner for every call.

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..." — the agent's private key

Store the exported key securely. Anyone with the key has full control over the agent’s funds.

Reconnecting to an existing agent

You don’t need to create a new agent on every session. Reconnect by ID, wallet address, or .wraith name.

By agent ID
By wallet address
By .wraith name

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

This does not make a network call — use it when you already have the ID cached.

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

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

Available AI tools

Every agent.chat() call has access to the following tools. The AI agent selects and executes them automatically.

Tool	What it does
`fund_wallet`	Request testnet tokens from the faucet
`get_balance`	Check native and token balances
`send_payment`	Send a stealth payment to a meta-address or `.wraith` name
`pay_agent`	Pay another agent by `.wraith` name
`scan_payments`	Scan for incoming stealth payments
`withdraw`	Withdraw from a specific stealth address
`withdraw_all`	Withdraw from all stealth addresses
`create_invoice`	Create a payment invoice with a shareable link
`check_invoices`	Check invoice payment statuses
`schedule_payment`	Schedule a recurring payment
`list_schedules`	List scheduled payments
`cancel_schedule`	Cancel a scheduled payment
`resolve_name`	Look up a `.wraith` name
`register_name`	Register a `.wraith` name on-chain
`get_agent_info`	Get full agent identity and TEE status
`privacy_check`	Run a privacy analysis with scoring

Get Started

Concepts

Guides

Contracts

Single-Chain Agent: Complete Lifecycle Walkthrough

Main flow

Invoicing

Scheduled payments

Privacy check

Notifications

Conversations

Export private key

Reconnecting to an existing agent

Available AI tools

Get Started

Concepts

Guides

Contracts

​Main flow

​Invoicing

​Scheduled payments

​Privacy check

​Notifications

​Conversations

​Export private key

​Reconnecting to an existing agent

​Available AI tools

Main flow

Invoicing

Scheduled payments

Privacy check

Notifications

Conversations

Export private key

Reconnecting to an existing agent

Available AI tools