API Documentation

Everything you need to create and manage Kaspa invoices programmatically. Simple, powerful, and free for the community.

Introduction

The Living Invoices API lets you create cryptocurrency invoices that your customers can pay with Kaspa. It's designed to be simple enough that anyone can use it, but powerful enough for complex integrations.

Base URL

https://kaspa-invoices.com/api/v1

What You Can Do

  • Create invoices denominated in USD (or other fiat currencies)
  • Customers pay in KAS at the current exchange rate
  • Get notified when invoices are viewed or paid
  • Embed a payment button on your website

⚡ Quick Start

Create your first invoice in 30 seconds:

# 1. Get your API key from Settings → API Keys

# 2. Create an invoice
curl -X POST https://kaspa-invoices.com/api/v1/invoices \
  -H "X-API-Key: liv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_email": "customer@example.com",
    "items": [
      { "description": "Web Design", "unit_price": 500 }
    ]
  }'

# 3. Share the invoice URL with your customer
# → https://kaspa-invoices.com/i/INV-2026-ABC123

Authentication

Every request needs an API key. Get yours from Settings → API Keys.

Using Your API Key

Include it in the header of every request:

X-API-Key: liv_your_api_key_here

Or as a Bearer token:

Authorization: Bearer liv_your_api_key_here
⚠️ Keep Your Key Secret

Never share your API key or commit it to public repositories. If compromised, regenerate it immediately.

Rate Limits

You can make up to 100 requests per minute. If you hit the limit, you'll get a 429 response. Check these headers:

Header Description
X-RateLimit-Limit Maximum requests per minute
X-RateLimit-Remaining Requests left in current window
X-RateLimit-Reset Unix timestamp when the limit resets

Create Invoice

POST /invoices

Create a new invoice. Returns the invoice with a shareable URL.

Request Body

Field Type Required Description
to_email string Yes Customer's email address
to_name string No Customer's name
items array Yes Array of line items (see below)
due_date string No YYYY-MM-DD format. Default: 7 days from now
notes string No Notes visible to customer
send boolean No If true, invoice goes straight to "pending" status

Item Object

Field Type Required
description string Yes
unit_price number Yes
quantity number No (default: 1)

Example

{
  "to_email": "alice@example.com",
  "to_name": "Alice Smith",
  "items": [
    {
      "description": "Logo Design",
      "unit_price": 300
    },
    {
      "description": "Business Cards (500)",
      "unit_price": 75,
      "quantity": 2
    }
  ],
  "notes": "Thank you for your business!",
  "send": true
}

List Invoices

GET /invoices

Get all your invoices with optional filtering.

Query Parameters

Parameter Description
status Filter by status: draft, pending, paid, overdue, cancelled
limit Results per page (default: 20, max: 100)
page Page number (default: 1)

Example

GET /api/v1/invoices?status=pending&limit=10

Webhook Events

Get notified when things happen to your invoices.

Event Description
invoice.created A new invoice was created
invoice.viewed Someone viewed the invoice
invoice.paid Payment confirmed on the Kaspa network
invoice.overdue Invoice passed its due date without payment

Webhook Payload

{
  "event": "invoice.paid",
  "timestamp": "2026-01-15T10:30:00Z",
  "invoice": {
    "id": "INV-2026-ABC123",
    "status": "paid",
    "amount": {
      "total": 500,
      "currency": "USD"
    },
    "payment": {
      "kas_amount": 4166.67,
      "tx_id": "abc123..."
    }
  }
}

Verifying Webhooks

Each webhook includes a signature header you can use to verify it came from us:

# Header: X-Webhook-Signature
# Calculated as: HMAC-SHA256(payload, your_webhook_secret)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

Embed Widget

Add a "Pay with Kaspa" button to any website. No coding required.

Simple Embed

Just paste this where you want the button:

<script 
  src="https://kaspa-invoices.com/widget.js"
  data-invoice="INV-2026-ABC123"
  data-theme="light">
</script>

Theme Options

  • light - Green gradient (default)
  • dark - Navy gradient
  • minimal - White with border
  • kaspa - Kaspa teal

JavaScript API

For more control, use the JavaScript API:

<div id="pay-button"></div>

<script src="https://kaspa-invoices.com/widget.js"></script>
<script>
  LivingInvoices.createButton({
    invoice: 'INV-2026-ABC123',
    container: '#pay-button',
    theme: 'kaspa',
    text: 'Pay Now',
    onPayment: (result) => {
      console.log('Paid!', result.tx_id);
    }
  });
</script>
💡 Tip

The widget automatically shows the invoice amount and updates in real-time based on the current KAS price.

Need Help?

Have questions? Found a bug? Want to contribute?