Skip to main content
Invoices are payment requests that an agent creates during a chat session. When a payer visits the payment link, they send funds to the agent’s stealth address. Once the payment is detected on-chain, you call POST /invoice/:id/paid to notify the agent. All invoice endpoints require a Bearer token in the Authorization header.

​
Invoice lifecycle

Understanding the lifecycle helps you integrate invoice flows correctly:
  1. Created — The agent generates an invoice in response to a chat message like "Create an invoice for $50". The invoice starts with status: "pending".
  2. Shared — You or the agent shares the paymentLink with the payer. The link opens a payment UI pre-filled with the amount and stealth address.
  3. Paid — The payer sends funds to the agent’s stealth address on-chain.
  4. Confirmed — Your backend detects the on-chain payment and calls POST /invoice/:id/paid to mark it complete.
  5. Notified — The TEE server triggers a notification on the agent so it knows the payment arrived.
The TEE does not automatically detect on-chain payments. Your integration is responsible for monitoring the chain and calling POST /invoice/:id/paid when funds arrive.

​
GET /invoice/:id

Fetch a single invoice by ID.

​
Path parameters

​
id
string
required
The invoice ID returned when the agent created the invoice.

​
Response

​
id
string
required
The invoice UUID.
​
agentName
string
required
The .wraith name of the agent that created this invoice.
​
amount
string
required
The requested payment amount as a decimal string (e.g., "50.00").
​
asset
string
required
The asset symbol or contract address (e.g., "EON", "USDC").
​
memo
string
required
A human-readable description of what the invoice is for.
​
status
string
required
"pending" or "paid".
​
txHash
string
The transaction hash of the payment. null until the invoice is marked paid.
​
paymentLink
string
required
A URL the payer can visit to complete payment. Share this with your payer.
​
createdAt
string
required
ISO 8601 timestamp when the invoice was created.

​
Example

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

​
Full Invoice type

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

interface Invoice {
  id: string;
  agentName: string;
  amount: string;
  asset: string;
  memo: string;
  status: "pending" | "paid";
  txHash: string | null;
  paymentLink: string;
  createdAt: string;
}

​
POST /invoice/:id/paid

Mark an invoice as paid after detecting the on-chain payment. This endpoint is idempotent — calling it multiple times for the same invoice does not create duplicate notifications or change the invoice state after the first call.

​
Path parameters

​
id
string
required
The invoice ID to mark as paid.

​
Response

Returns 200 OK with no body on success.

​
Example

curl -X POST https://api.wraith.dev/invoice/inv_abc123/paid \
  -H "Authorization: Bearer wraith_live_abc123"

​
Integrating on-chain payment detection

Use your chain’s event indexer to watch for payments to the agent’s stealth addresses, then call this endpoint when you detect a match: 
async function onPaymentDetected(invoiceId: string) {
  // Mark the invoice paid — safe to call multiple times (idempotent)
  await fetch(`https://api.wraith.dev/invoice/${invoiceId}/paid`, {
    method: "POST",
    headers: { Authorization: "Bearer wraith_live_abc123" },
  });

  // Fetch the updated invoice to confirm
  const res = await fetch(`https://api.wraith.dev/invoice/${invoiceId}`, {
    headers: { Authorization: "Bearer wraith_live_abc123" },
  });
  const invoice = await res.json();
  console.log(`Invoice ${invoice.id} is now ${invoice.status}`);
  // → "Invoice inv_abc123 is now paid"
}