Agent Endpoints: Create, Query, and Export Agents

Agents are the core resource in Wraith Protocol. Each agent has a .wraith name, one or more on-chain addresses, and a stealth meta-address for receiving payments. Use these endpoints to create, inspect, and manage agents. All endpoints require a Bearer token in the Authorization header.

POST /agent/create

Create a new agent with a .wraith name. The signature proves that the caller owns the wallet that will control this agent. On EVM chains, sign with EIP-191; on Stellar, sign with ed25519.

Request

name

string

required

The .wraith name for the agent (e.g., "alice" becomes alice.wraith). Must be 3–32 characters, lowercase alphanumeric and hyphens only.

chain

string

required

The chain to deploy the agent on. One of: "horizen", "stellar", "ethereum", "polygon", "base", "solana".

wallet

string

required

The owner wallet address. This wallet controls the agent and is required for sensitive operations like key export.

signature

string

required

A signature from wallet proving ownership. Use EIP-191 personal sign on EVM chains or ed25519 on Stellar.

message

string

The plaintext message that was signed. Required if the server needs to reconstruct the signed payload for verification.

Response

string

required

UUID that uniquely identifies this agent.

name

string

required

The registered .wraith name (without the .wraith suffix).

chain

string

required

The chain this agent is deployed on.

address

string

required

The agent’s on-chain address.

metaAddress

string

required

The agent’s stealth meta-address. Share this with senders so they can generate stealth addresses for payments to this agent.

Example

curl
TypeScript

curl -X POST https://api.wraith.dev/agent/create \
  -H "Authorization: Bearer wraith_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "alice",
    "chain": "horizen",
    "wallet": "0xYourWalletAddress",
    "signature": "0xSignatureHex",
    "message": "Create Wraith agent alice"
  }'

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

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

const agent = await wraith.createAgent({
  name: "alice",
  chain: Chain.Horizen,
  wallet: "0xYourWalletAddress",
  signature: "0xSignatureHex",
  message: "Create Wraith agent alice",
});

console.log(agent.info.id);                          // UUID
console.log(agent.info.metaAddresses[Chain.Horizen]); // stealth meta-address

GET /agents

Return all agents associated with the authenticated API key.

Response

Returns an array of AgentInfo objects.

string

required

Agent UUID.

name

string

required

The .wraith name.

chains

string[]

required

All chains this agent is active on.

addresses

object

required

Map of chain name to on-chain address.

metaAddresses

object

required

Map of chain name to stealth meta-address.

Example

curl
TypeScript

curl https://api.wraith.dev/agents \
  -H "Authorization: Bearer wraith_live_abc123"

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

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agents = await wraith.listAgents();

for (const agent of agents) {
  console.log(`${agent.name}: ${agent.id}`);
}

GET /agent/:id

Fetch a single agent by its UUID.

Path parameters

string

required

The agent UUID returned from POST /agent/create.

Response

Returns an AgentInfo object. See GET /agents for the field reference.

Example

curl
TypeScript

curl https://api.wraith.dev/agent/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer wraith_live_abc123"

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

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agent = wraith.agent("550e8400-e29b-41d4-a716-446655440000");

GET /agent/info/:name

Look up an agent by its .wraith name instead of UUID.

Path parameters

name

string

required

The .wraith name (without the .wraith suffix). For example, alice to look up alice.wraith.

Response

Returns an AgentInfo object.

Example

curl
TypeScript

curl https://api.wraith.dev/agent/info/alice \
  -H "Authorization: Bearer wraith_live_abc123"

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

GET /agent/wallet/:address

Look up an agent by the owner wallet address.

Path parameters

address

string

required

The owner wallet address that was supplied in POST /agent/create.

Response

Returns an AgentInfo object.

Example

curl
TypeScript

curl https://api.wraith.dev/agent/wallet/0xYourWalletAddress \
  -H "Authorization: Bearer wraith_live_abc123"

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

GET /agent/:id/status

Return the agent’s current balance, pending invoice count, and on-chain details.

Path parameters

string

required

The agent UUID.

Response

balance

string

required

Native asset balance as a decimal string (e.g., "0.5").

tokens

object

required

Map of token contract address to balance string.

pendingInvoices

number

required

Number of invoices with status: "pending".

address

string

required

The agent’s on-chain address.

metaAddress

string

required

The agent’s stealth meta-address.

chain

string

required

The chain this agent is deployed on.

Example

curl
TypeScript

curl https://api.wraith.dev/agent/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer wraith_live_abc123"

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

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agentClient = wraith.agent("550e8400-e29b-41d4-a716-446655440000");
const status = await agentClient.getStatus();

console.log(`Balance: ${status.balance}`);
console.log(`Pending invoices: ${status.pendingInvoices}`);

POST /agent/:id/export

Export the agent’s private key from the TEE. Use this to migrate an agent to self-custody or to sign transactions outside the SDK. Requires a fresh wallet signature to prevent replay attacks.

Treat the exported key like a seed phrase. Anyone with access to it controls the agent’s funds. The TEE cannot revoke a key after export.

Path parameters

string

required

The agent UUID.

Request

signature

string

required

A fresh signature from the owner wallet. Do not reuse a signature from a previous request.

message

string

required

The plaintext message that was signed.

Response

secret

string

required

The agent’s private key as a 0x-prefixed hex string on EVM chains, or a base64-encoded seed on Stellar.

Example

curl
TypeScript

curl -X POST https://api.wraith.dev/agent/550e8400-e29b-41d4-a716-446655440000/export \
  -H "Authorization: Bearer wraith_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "0xFreshSignatureHex",
    "message": "Export agent key 2024-01-15T10:30:00Z"
  }'

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

const wraith = new Wraith({ apiKey: "wraith_live_abc123" });
const agentClient = wraith.agent("550e8400-e29b-41d4-a716-446655440000");

const { secret } = await agentClient.exportKey(
  "0xFreshSignatureHex",
  "Export agent key 2024-01-15T10:30:00Z"
);

// Store securely — do not log or transmit this value
console.log("Private key exported");

HTTP API

​POST /agent/create

​Request

​Response

​Example

​GET /agents

​Response

​Example

​GET /agent/:id

​Path parameters

​Response

​Example

​GET /agent/info/:name

​Path parameters

​Response

​Example

​GET /agent/wallet/:address

​Path parameters

​Response

​Example

​GET /agent/:id/status

​Path parameters

​Response

​Example

​POST /agent/:id/export

​Path parameters

​Request

​Response

​Example

POST /agent/create

Request

Response

Example

GET /agents

Response

Example

GET /agent/:id

Path parameters

Response

Example

GET /agent/info/:name

Path parameters

Response

Example

GET /agent/wallet/:address

Path parameters

Response

Example

GET /agent/:id/status

Path parameters

Response

Example

POST /agent/:id/export

Path parameters

Request

Response

Example