> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usewraith.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Client

> Wraith and WraithAgent classes for the managed platform

The `Wraith` and `WraithAgent` classes are the primary interface for building with Wraith. They handle all communication with the managed TEE infrastructure.

## `Wraith` Class

### Constructor

```typescript theme={null}
import { Wraith } from "@wraith-protocol/sdk";

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

#### `WraithConfig`

| Parameter     | Type                               | Required | Description                                                      |
| ------------- | ---------------------------------- | -------- | ---------------------------------------------------------------- |
| `apiKey`      | `string`                           | Yes      | Your Wraith platform API key                                     |
| `baseUrl`     | `string`                           | No       | Override the API base URL (defaults to `https://api.wraith.dev`) |
| `ai`          | `object`                           | No       | Bring your own AI model configuration                            |
| `ai.provider` | `"gemini" \| "openai" \| "claude"` | No       | AI provider name                                                 |
| `ai.apiKey`   | `string`                           | No       | Your AI provider API key                                         |

### `wraith.createAgent(config)`

Create a new agent with a `.wraith` name and stealth keys.

```typescript theme={null}
import { Chain } from "@wraith-protocol/sdk";

const agent = await wraith.createAgent({
  name: "alice",
  chain: Chain.Horizen,
  wallet: "0xYourWallet",
  signature: "0xSignatureFromWallet",
});
```

#### `AgentConfig`

| Parameter   | Type               | Required | Description                                |
| ----------- | ------------------ | -------- | ------------------------------------------ |
| `name`      | `string`           | Yes      | Agent name (becomes `name.wraith`)         |
| `chain`     | `Chain \| Chain[]` | Yes      | Target chain(s) for the agent              |
| `wallet`    | `string`           | Yes      | Owner wallet address                       |
| `signature` | `string`           | Yes      | EIP-191 signature proving wallet ownership |
| `message`   | `string`           | No       | Message that was signed (for verification) |

Returns a `WraithAgent` instance.

### `wraith.agent(agentId)`

Connect to an existing agent by ID. Does not make a network call.

```typescript theme={null}
const agent = wraith.agent("agent-uuid-here");
```

### `wraith.getAgentByWallet(walletAddress)`

Look up an agent by its owner wallet address.

```typescript theme={null}
const agent = await wraith.getAgentByWallet("0xYourWallet");
```

### `wraith.getAgentByName(name)`

Look up an agent by its `.wraith` name.

```typescript theme={null}
const agent = await wraith.getAgentByName("alice");
```

### `wraith.listAgents()`

List all agents associated with your API key.

```typescript theme={null}
const agents = await wraith.listAgents();
// AgentInfo[]
```

***

## `WraithAgent` Class

Returned by `wraith.createAgent()`, `wraith.getAgentByWallet()`, and `wraith.getAgentByName()`. Provides all agent operations.

### `agent.info`

The agent's identity information.

```typescript theme={null}
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..."
```

### `agent.chat(message, conversationId?)`

Natural language interaction with the AI agent.

```typescript theme={null}
const response = await agent.chat("send 0.1 ETH to bob.wraith");
```

| Parameter        | Type     | Required | Description                       |
| ---------------- | -------- | -------- | --------------------------------- |
| `message`        | `string` | Yes      | Natural language message          |
| `conversationId` | `string` | No       | Continue an existing conversation |

Returns a `ChatResponse`:

```typescript theme={null}
const res = await agent.chat("send 0.1 ETH to bob.wraith");
console.log(res.response);      // "Payment sent — 0.1 ETH to bob.wraith..."
console.log(res.toolCalls);     // [{ name: "send_payment", status: "success" }]
console.log(res.conversationId); // "conv-uuid"

// Continue the conversation
const followUp = await agent.chat("what was the tx hash?", res.conversationId);
```

### `agent.getStatus()`

Get the agent's current status including balance and stats.

```typescript theme={null}
const status = await agent.getStatus();
```

### `agent.getBalance()`

Get the agent's balance across all assets.

```typescript theme={null}
const balance = await agent.getBalance();
console.log(balance.native);  // "1.5"
console.log(balance.tokens);  // { ZEN: "100.0", USDC: "50.0" }
```

### `agent.scanPayments()`

Scan for incoming stealth payments via the AI agent.

```typescript theme={null}
const payments = await agent.scanPayments();
// Payment[]
```

### `agent.exportKey(signature, message)`

Export the agent's private key. Requires a fresh wallet signature for verification.

```typescript theme={null}
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..."
```

### `agent.getConversations()`

List all conversations with this agent.

```typescript theme={null}
const conversations = await agent.getConversations();
```

### `agent.getMessages(conversationId)`

Get messages from a specific conversation.

```typescript theme={null}
const messages = await agent.getMessages("conv-uuid");
// [{ role: "user", text: "..." }, { role: "agent", text: "..." }]
```

### `agent.deleteConversation(conversationId)`

Delete a conversation and its messages.

```typescript theme={null}
await agent.deleteConversation("conv-uuid");
```

### `agent.getNotifications()`

Get notifications for this agent.

```typescript theme={null}
const { notifications, unreadCount } = await agent.getNotifications();
```

### `agent.markNotificationsRead()`

Mark all notifications as read.

```typescript theme={null}
await agent.markNotificationsRead();
```

### `agent.clearNotifications()`

Delete all notifications.

```typescript theme={null}
await agent.clearNotifications();
```

***

## AI-Powered Tools

When you use `agent.chat()`, the AI agent has access to these 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: Invoicing

```typescript theme={null}
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

```typescript theme={null}
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 includes:

| Header          | Value                                | Purpose                             |
| --------------- | ------------------------------------ | ----------------------------------- |
| `Authorization` | `Bearer wraith_...`                  | Platform API key                    |
| `X-AI-Provider` | `"openai"` / `"claude"` / `"gemini"` | Optional — for bring your own model |
| `X-AI-Key`      | `sk-...`                             | Optional — your AI provider key     |

## Error Handling

All methods throw on failure. The error message comes from the server:

```typescript theme={null}
try {
  await agent.chat("send 100 ETH to bob.wraith");
} catch (err) {
  console.error(err.message); // "Insufficient balance"
}
```