A Wraith agent is your persistent identity on the network. It combines a human-readable .wraith name, chain-specific addresses, stealth cryptographic keys, and an AI model that understands natural language payment commands — all running inside Trusted Execution Environment hardware.
What an agent contains
When you create an agent, Wraith provisions:
- A
.wraith name (for example alice.wraith) registered on-chain
- A wallet address on each target chain
- A stealth meta-address on each target chain for receiving private payments
- An AI agent inside the TEE ready to process natural language commands
You never handle the cryptographic keys directly. The TEE derives them on demand for every operation, then discards them from memory.
Creating an agent
Sign a message with your owner wallet to prove ownership, then call createAgent:
import { Wraith, Chain } from "@wraith-protocol/sdk";
const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
// 1. Sign a message with the owner wallet to prove ownership
const message = "Sign to create Wraith agent";
const signature = await wallet.signMessage(message);
// 2. Create the agent
const agent = await wraith.createAgent({
name: "alice",
chain: Chain.Horizen,
wallet: "0xYourWalletAddress",
signature: signature,
message: message,
});
agent.info fields
After creation, inspect the agent’s identity through agent.info:
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..."
| Field | Type | Description |
|---|
id | string | UUID that uniquely identifies this agent |
name | string | The .wraith name without the TLD (e.g. "alice") |
chains | Chain[] | All chains this agent is registered on |
addresses | Record<Chain, string> | On-chain wallet address per chain |
metaAddresses | Record<Chain, string> | Stealth meta-address per chain (e.g. "st:eth:0x...") |
Reconnecting to an existing agent
If you already created an agent, reconnect without creating a new one. Three methods are available:
// By agent ID — no network call
const agent = wraith.agent("agent-uuid-here");
// By owner wallet address
const agent = await wraith.getAgentByWallet("0xYourWallet");
// By .wraith name
const agent = await wraith.getAgentByName("alice");
Use wraith.agent(id) when you already have the UUID — it avoids a network round-trip. Use getAgentByWallet or getAgentByName when you need to look up the ID from an identifier you have in storage.
Multichain agents
A multichain agent has one .wraith name with separate addresses and stealth keys on each chain. Pass an array of chains at creation time:
const agent = await wraith.createAgent({
name: "alice",
chain: [Chain.Horizen, Chain.Stellar, Chain.Ethereum],
wallet: "0xYourWallet",
signature: "0xSignature",
});
console.log(agent.info.chains);
// [Chain.Horizen, Chain.Stellar, Chain.Ethereum]
console.log(agent.info.addresses);
// {
// horizen: "0xabc...",
// stellar: "GABC...",
// ethereum: "0xdef..."
// }
console.log(agent.info.metaAddresses);
// {
// horizen: "st:eth:0x...",
// stellar: "st:xlm:...",
// ethereum: "st:eth:0x..."
// }
Chain.All to register on every chain the platform supports:
const agent = await wraith.createAgent({
name: "alice",
chain: Chain.All,
wallet: "0xYourWallet",
signature: "0xSignature",
});
Chain-aware chat
The AI agent infers the chain from context. When the asset is unambiguous it routes automatically:
await agent.chat("send 10 XLM to carol.wraith");
// XLM -> Stellar (unambiguous)
await agent.chat("send 100 ZEN to bob.wraith");
// ZEN -> Horizen (unambiguous)
await agent.chat("send 0.1 ETH to bob.wraith");
// "ETH exists on both Horizen and Ethereum. Which chain do you mean?"
await agent.chat("horizen");
// "Payment sent — 0.1 ETH to bob.wraith on Horizen..."
await agent.chat("send 0.1 ETH to bob.wraith on horizen");
What the AI agent can do
When you call agent.chat(), the AI has access to a full set of payment tools:
| 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 for incoming stealth payments |
get_balance | Check wallet balance (native + tokens) |
create_invoice | Create a payment invoice with a shareable link |
check_invoices | Check invoice payment statuses |
withdraw | Withdraw from a specific stealth address |
withdraw_all | Withdraw from all stealth addresses |
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 |
fund_wallet | Request testnet tokens from faucet |
privacy_check | Run a privacy analysis with scoring |
Example: create an invoice
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: run a 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"
Exporting the private key
If you need to take the agent’s private key out of the TEE — for example, to migrate to self-custody — call exportKey with a fresh wallet signature:
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..."
Key export requires a fresh signature from the owner wallet. Without that signature, nobody — including Wraith — can export the key.
Bring your own AI model
By default the agent uses Wraith’s hosted Gemini model. Pass your own model configuration to use OpenAI or Claude instead:
const wraith = new Wraith({
apiKey: "wraith_...",
ai: { provider: "openai", apiKey: "sk-..." },
});
"gemini", "openai", "claude".