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

Use static addresses for deposits or top-ups, not as a replacement for invoice payment links. If a customer is paying a specific order, start with Payment Flows and invoices.

Creating a Static Address

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

Response:

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

With the SDK

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

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

const { data } = await createAddress({
  client,
  body: {
    currency: 'BTC',
    label: 'Account top-up',
  },
});

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

How It Works

You create a static address for a currency
Store the address on your backend for the payer or account top-up flow
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://dashboard.halfin.xyz/api/v1/addresses/00000000-0000-0000-0000-000000000002/invoices \
  -H "X-API-Key: sk_test_0000000000000000000000000000000000000000000000000000000000000000"

Use Cases

Account top-ups -- assign one address per user for balance deposits
Treasury deposits -- keep a permanent address for internal funding flows
Recurring deposits -- trusted payers send to the same address each time

Static Addresses

Creating a Static Address

With the SDK

How It Works

Listing Invoices for an Address

Use Cases

On this page