Wraith agents: identity and key management

A Wraith agent is your persistent identity on the Wraith network: a .wraith name, stealth keys, and an AI model that handles payments in natural language.

A Wraith agent is more than an API client. It is a long-lived identity that lives inside Trusted Execution Environment (TEE) hardware: it has a human-readable name registered on-chain, stealth keys that never leave the secure enclave, and an AI model with 17 tools for sending, receiving, and analyzing payments. You create an agent once and reconnect to it across sessions — it persists and accumulates conversation history between calls.

What an agent contains

Every agent has four core properties:

UUID

A unique identifier you use to reconnect to an existing agent without querying the chain. Never changes.

.wraith name

A human-readable name registered on-chain (e.g., alice.wraith). Other agents can send payments to you by name.

On-chain address

The agent’s wallet address on each supported chain. This is the address you see in agent.info.addresses.

Stealth meta-address

The st:eth:0x... string that encodes your spending and viewing public keys. Published on-chain so senders can derive one-time addresses for you.

You can inspect all of these through agent.info:

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

const wraith = new Wraith({ apiKey: "wraith_..." });
const agent = await wraith.getAgentByName("alice");

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

Key management

Your agent’s spending key and viewing key are derived inside the TEE from your wallet signature and never written to disk. The TEE attestation guarantees that the derivation code ran unmodified and that no one — including Wraith infrastructure operators — can read the private material.

Key derivation uses DStack inside a Phala Network Intel TDX enclave. The derived keys exist only in encrypted TEE memory. See the Privacy model page for the full security model.

When you need to move keys out of the TEE — for example to self-custody — you can export them with a fresh wallet signature:

const exportMessage = "Export private key for agent " + agent.info.id;
const sig = await wallet.signMessage(exportMessage);

const { secret } = await agent.exportKey(sig, exportMessage);
console.log(secret); // "0x..."

The export requires you to prove wallet ownership at call time. The key is returned to you directly; Wraith does not log or store it.

.wraith names

.wraith names are on-chain identifiers that map to stealth meta-addresses. They work like ENS names but are built for stealth payments:

• Human-readable — alice.wraith instead of st:eth:0x04a8...
• Registered on-chain — stored in the WraithNames contract, keyed to a spending public key
• No wallet address stored — the registry links the name to the meta-address, not to your wallet, so the name alone cannot identify you

When a sender pays alice.wraith, the agent resolves the name to the meta-address and generates a one-time stealth address without the sender ever knowing your wallet address.

Creating an agent

Authentication uses EIP-191: you sign a message with the wallet that will own the agent. This proves wallet ownership without sending a transaction.

1. Sign a message with your wallet

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

   import { Wraith, Chain } from "@wraith-protocol/sdk";
   
   const wraith = new Wraith({ apiKey: "wraith_..." });
   
   const agent = await wraith.createAgent({
     name: "alice",
     chain: Chain.Horizen,
     wallet: "0xYourWalletAddress",
     signature,
     message,
   });
   

   The TEE derives your stealth keys from the signature, registers alice.wraith on-chain, and returns a live WraithAgent instance.

3. Verify the agent is live

   console.log(agent.info.id);
   // "uuid-..."
   
   console.log(agent.info.metaAddresses[Chain.Horizen]);
   // "st:eth:0x..."
   

Reconnecting to an existing agent

You do not need to create a new agent each session. Reconnect using any of three lookup methods:

By agent ID

// Synchronous — no network call
const agent = wraith.agent("agent-uuid-here");

To list all agents under your API key:

const agents = await wraith.listAgents();
// AgentInfo[]

Talking to your agent

Every agent exposes a chat() method that accepts natural language. The AI model routes your message to the appropriate tool and returns a response with details on what it executed:

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

console.log(res.toolCalls);
// [{ name: "send_payment", status: "success" }]

You can continue a conversation across multiple turns using the conversationId:

const first = await agent.chat("scan for incoming payments");
const followUp = await agent.chat("withdraw the largest one", first.conversationId);

AI tools

When you call agent.chat(), the AI has access to 17 tools. You never call these directly — the model selects and invokes them based on your message.

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 the faucet
privacy_check	Run 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: scheduled payments

await agent.chat("send 0.05 ETH to carol.wraith every week");
// Agent schedules a recurring stealth payment

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 headers

Every SDK request to the Wraith TEE server includes your API key and, optionally, your own AI provider credentials:

Header	Value	Purpose
Authorization	Bearer wraith_...	Your Wraith platform API key
X-AI-Provider	"openai" / "claude" / "gemini"	Optional — bring your own model
X-AI-Key	sk-...	Optional — your AI provider key

You can use your own OpenAI or Claude API key instead of the default Gemini model by passing ai.provider and ai.apiKey to the Wraith constructor.

Next steps

What are stealth addresses?

Understand how one-time addresses are derived and why they protect recipient privacy.

Privacy model and TEE security

Learn how TEE hardware protects your keys and how to maximize your privacy score.