Authentication

All merchant API requests authenticate with an API key passed in the X-API-Key header.

API key types

Keys are 64-character hex strings prefixed with the environment: sk_test_{64 hex chars}.

Header format

X-API-Key: sk_test_0000000000000000000000000000000000000000000000000000000000000000

Environment isolation

Test and live environments are completely separate:

• Test keys only access test invoices, test balances, and test resources
• Live keys only access live invoices, live balances, and real blockchains
• You cannot mix environments - a test key will never see live data

Using the SDK

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

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

Best practices

• Rotate keys periodically in Settings → API Keys on the dashboard.
• Use test keys in CI/CD pipelines and staging environments.
• Restrict permissions - create keys with only the scopes your integration needs (e.g., invoices:write without addresses:write).
• Keep live keys server-side only - never expose them in frontend code or client-side bundles.