Guides

Static Addresses

Create permanent deposit addresses for recurring payments and donations

Static addresses are permanent blockchain addresses tied to your merchant account. Any deposit to a static address automatically creates an invoice.

Creating a Static Address

curl -X POST https://api.halfin.xyz/api/v1/addresses \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_0000000000000000000000000000000000000000000000000000000000000000" \
  -d '{
    "currency": "BTC",
    "label": "Donation page"
  }'

Response:

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000002",
    "currency": "BTC",
    "address": "bc1qstaticexampleaddress",
    "address_tag": null,
    "label": "Donation page",
    "total_received": "0",
    "invoice_count": 0,
    "created_at": "2026-01-01T00:00:00Z"
  },
  "meta": { "request_id": "req_def456" }
}

With the SDK

import { createHalfin } from '@halfin/sdk-merchant';

const halfin = createHalfin({
  apiKey: process.env.HALFIN_API_KEY!,
  baseUrl: 'https://api.halfin.xyz/api',
});

const address = await halfin.createAddress({
  currency: 'BTC',
  label: 'Donation page',
});

console.log(address.data.address);
// → "bc1qstaticexampleaddress"

How It Works

You create a static address for a currency
Display the address on your site (donation page, account top-up, etc.)
When a deposit arrives, halfin auto-creates an invoice with source: "static_address"
You receive invoice.confirming and invoice.paid webhooks as usual

Listing Invoices for an Address

curl https://api.halfin.xyz/api/v1/addresses/00000000-0000-0000-0000-000000000002/invoices \
  -H "X-API-Key: sk_test_0000000000000000000000000000000000000000000000000000000000000000"

Use Cases

Donation pages -- embed a permanent address with a QR code
Account top-ups -- assign one address per user for balance deposits
Recurring payments -- customers send to the same address each time

Authentication

API key types, header format, and security best practices

Rate Limits

API rate limits and how to handle 429 responses

On this page

Creating a Static Address With the SDK How It Works Listing Invoices for an Address Use Cases