Static addresses are permanent payment addresses that auto-create invoices when funds arrive.

A static address is a permanent blockchain address tied to your merchant account. Any payment to a static address automatically creates an invoice. Use static addresses for account top-ups or recurring payments — not as a replacement for invoice payment links when tracking a specific order.

Address object

Field	Type	Description
`id`	uuid	Unique address identifier
`currency`	string	Crypto currency code
`network`	string	Blockchain network the address lives on (e.g. `tron`, `ethereum`)
`environment`	string	`live` or `test`
`gate_id`	string	Payment gate (chain) identifier
`address`	string	The blockchain address string
`address_tag`	string	Memo or destination tag (required by some chains)
`label`	string	Human-readable label for this address
`total_received`	string	Cumulative amount received (decimal string)
`invoice_count`	integer	Number of invoices auto-created from this address
`created_at`	datetime	Creation timestamp

How it works

You create a static address for a currency.
Give the payer (or your internal system) the address and, if present, the address_tag.
When a payment arrives, halfin auto-creates an invoice with source: "static_address".
You receive invoice.confirming and invoice.paid webhooks as usual.
balance.credited fires when the merchant balance is credited.

Creating a static address

A static address requires a currency code; label is optional. For assets that exist on several chains (such as USDT and USDC), pass the network parameter to choose the chain — without it, multi-network currencies are rejected with a validation error. Single-network currencies (BTC, SOL, TRX, …) don't need network; the chain is inferred.

curl -X POST https://api-sandbox.thehalfin.com/v1/addresses \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HALFIN_API_KEY" \
  -d '{"currency":"USDT","network":"tron","label":"Account top-up"}'

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

const client = createHalfin({ apiKey: process.env.HALFIN_API_KEY! });
const { data } = await createAddress({
  client,
  body: { currency: 'USDT', network: 'tron', label: 'Account top-up' },
});

console.log(data.address); // blockchain address to show the payer
console.log(data.network); // "tron"

Destination tags / memos

Some chains require a memo or destination tag in addition to the address. Always show address_tag alongside the address when it is non-null. Deposits that omit a required tag may be unroutable.

Use cases

Account top-ups — one address per user for recurring payments
Treasury funding — permanent internal payment address
Recurring payments — trusted payers send to the same address each time

Methods

Create — POST /v1/addresses
List — GET /v1/addresses
Get — GET /v1/addresses/{addressID}
List address invoices — GET /v1/addresses/{addressID}/invoices

Overview