Skip to main content
All types documented here are exported from @wraith-protocol/sdk. Import only what you need — tree-shaking ensures unused types add no runtime overhead.
import type {
  AgentInfo,
  ChatResponse,
  ToolCall,
  Conversation,
  Invoice,
  Notification,
  Balance,
  Payment,
} from "@wraith-protocol/sdk";

Chain

The Chain enum lists every supported blockchain. Pass Chain.All to indicate that an operation spans all chains the agent is deployed on.
enum Chain {
  Horizen  = "horizen",
  Ethereum = "ethereum",
  Polygon  = "polygon",
  Base     = "base",
  Stellar  = "stellar",
  Solana   = "solana",
  All      = "all",
}

WraithConfig

Configuration passed to the Wraith constructor.
interface WraithConfig {
  apiKey: string;
  baseUrl?: string;  // defaults to "https://api.wraith.dev"
  ai?: {
    provider: "gemini" | "openai" | "claude";
    apiKey: string;
  };
}
FieldRequiredDescription
apiKeyYesYour Wraith platform API key (wraith_live_...).
baseUrlNoOverride the API base URL — useful for self-hosted deployments.
ai.providerNoAI provider for BYOM mode.
ai.apiKeyNoYour API key for the chosen AI provider.

AgentConfig

Passed to wraith.createAgent().
interface AgentConfig {
  name: string;
  chain: Chain | Chain[];
  wallet: string;
  signature: string;
  message?: string;
}
FieldRequiredDescription
nameYesAgent name without the .wraith suffix. 3–32 characters, lowercase alphanumeric and hyphens.
chainYesThe chain(s) to deploy the agent on.
walletYesOwner wallet address.
signatureYesEIP-191 or ed25519 signature proving wallet ownership.
messageNoThe message that was signed, used for server-side verification.

AgentInfo

The agent’s identity, returned by create, list, and lookup operations.
interface AgentInfo {
  id: string;
  name: string;
  chains: Chain[];
  addresses: Record<Chain, string>;
  metaAddresses: Record<Chain, string>;
}
FieldDescription
idUUID that uniquely identifies the agent.
nameShort name without the .wraith suffix.
chainsAll chains the agent is deployed on.
addressesMap of chain to the agent’s on-chain address.
metaAddressesMap of chain to the agent’s stealth meta-address (used to receive private payments).

ChatResponse

Returned by agent.chat() and POST /agent/:id/chat.
interface ChatResponse {
  response: string;
  toolCalls?: ToolCall[];
  conversationId: string;
}
FieldDescription
responseThe agent’s natural language reply.
toolCallsThe tools the agent executed, if any.
conversationIdPass this value in your next request to continue the conversation.

ToolCall

Describes a single tool the agent invoked while processing a message.
interface ToolCall {
  name: string;
  status: string;
  detail?: string;
}
FieldDescription
nameTool name — e.g., send_payment, create_invoice, scan_payments.
status"success" or "error".
detailJSON string with the tool’s result or error details. Parse with JSON.parse(detail).

Conversation

Represents a chat session with the agent.
interface Conversation {
  id: string;
  title: string;
  createdAt: string;
  updatedAt: string;
}
FieldDescription
idUnique conversation UUID.
titleAuto-generated title based on the first message.
createdAtISO 8601 creation timestamp.
updatedAtISO 8601 timestamp of the most recent message.

Message

A single message within a conversation.
interface Message {
  role: "user" | "agent" | "tool" | "system";
  text: string;
  createdAt: string;
}
FieldDescription
roleWho sent the message: the user, the agent, a tool execution, or the system.
textThe message content. For tool role messages, this is a JSON string.
createdAtISO 8601 timestamp.

Invoice

Represents a payment request created by an agent.
interface Invoice {
  id: string;
  agentName: string;
  amount: string;
  asset: string;
  memo: string;
  status: "pending" | "paid";
  txHash: string | null;
  paymentLink: string;
  createdAt: string;
}
FieldDescription
idUnique invoice ID.
agentNameThe .wraith name of the agent that created the invoice.
amountRequested amount as a decimal string.
assetAsset symbol — e.g., ETH, ZEN, USDC.
memoDescription or note attached to the invoice.
status"pending" until paid, then "paid".
txHashTransaction hash of the payment, or null if not yet paid.
paymentLinkShareable URL the payer opens to complete payment.
createdAtISO 8601 creation timestamp.

Notification

An event notification delivered to an agent.
interface Notification {
  id: number;
  type: string;
  title: string;
  body: string;
  read: boolean;
  createdAt: string;
}
FieldDescription
idAuto-incrementing integer ID.
typeEvent type — e.g., payment_received, invoice_paid, schedule_executed.
titleShort event summary.
bodyFull event description including amounts and addresses.
readtrue if marked as read.
createdAtISO 8601 timestamp.

Balance

The agent’s asset holdings, returned by agent.getBalance().
interface Balance {
  native: string;
  tokens: Record<string, string>;
}
FieldDescription
nativeNative chain asset balance as a decimal string — e.g., "1.5" for 1.5 ETH.
tokensMap of token symbol to balance string — e.g., { "USDC": "50.0", "ZEN": "100.0" }.

Payment

A stealth payment detected by agent.scanPayments().
interface Payment {
  stealthAddress: string;
  balance: string;
  ephemeralPubKey: string;
}
FieldDescription
stealthAddressThe stealth address that received the payment.
balanceThe balance held at this stealth address.
ephemeralPubKeyThe ephemeral public key used to generate the stealth address.

TxResult

Returned by operations that submit on-chain transactions.
interface TxResult {
  txHash: string;
  txLink: string;
}
FieldDescription
txHashThe transaction hash.
txLinkA block explorer URL for the transaction.

Schedule

A recurring payment schedule.
interface Schedule {
  id: string;
  recipient: string;
  amount: string;
  asset: string;
  interval: "daily" | "weekly" | "monthly";
  status: "active" | "paused" | "cancelled";
  nextRun: string;
}
FieldDescription
idUnique schedule ID.
recipientRecipient .wraith name or stealth meta-address.
amountPayment amount as a decimal string.
assetAsset symbol.
intervalPayment frequency: daily, weekly, or monthly.
statusactive, paused, or cancelled.
nextRunISO 8601 timestamp of the next scheduled execution.