Skip to main content
Invoices let your agent request payment from anyone, even people who do not have a Wraith account. Each invoice generates a shareable payment link and QR code. When a payer completes the transfer, you can mark the invoice as paid — and the agent receives a notification automatically.

​
How agents create invoices

You do not need to call a dedicated create-invoice endpoint. Instead, ask your agent in natural language and it will invoke the create_invoice tool on your behalf: 
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/inv_abc123"
The response includes a full payment link you can send directly to the payer.

​
Get invoice


GET /invoice/:id Fetch the current state of an invoice by its ID. Use this to check whether a payment has been received.
​
id
string
required
The invoice ID, e.g., inv_abc123.

​
Response

​
id
string
Unique invoice ID.
​
agentName
string
The .wraith name of the agent that created the invoice.
​
amount
string
The requested amount as a decimal string.
​
asset
string
The asset symbol — e.g., ETH, ZEN, USDC.
​
memo
string
The memo or description attached to the invoice.
​
status
string
pending or paid.
​
txHash
string
Transaction hash of the payment, or null if not yet paid.
​
paymentLink
string
The full shareable URL for the payer — e.g., https://pay.wraith.dev/invoice/inv_abc123.
​
createdAt
string
ISO 8601 timestamp when the invoice was created.
curl https://api.wraith.dev/invoice/inv_abc123 \
  --header "Authorization: Bearer wraith_live_abc123"
Response
{
  "id": "inv_abc123",
  "agentName": "alice",
  "amount": "1.0",
  "asset": "ETH",
  "memo": "consulting fee",
  "status": "pending",
  "txHash": null,
  "paymentLink": "https://pay.wraith.dev/invoice/inv_abc123",
  "createdAt": "2025-04-10T12:00:00Z"
}

​
Mark invoice paid


POST /invoice/:id/paid Mark an invoice as paid. This is typically called by the payment frontend after a payer completes a transaction. Calling this endpoint multiple times is safe — it is idempotent and does not create duplicate notifications.
​
id
string
required
The invoice ID to mark as paid.
The endpoint returns 200 OK on success. After a successful call, the invoice status changes to paid and the agent receives a payment notification. 
curl https://api.wraith.dev/invoice/inv_abc123/paid \
  --request POST \
  --header "Authorization: Bearer wraith_live_abc123"
Wraith’s payment frontend calls this endpoint automatically when a payer completes a transfer via the payment link. You only need to call it manually if you are building a custom payment flow.