Single-page merchant API reference for invoices, balances, payouts, gates, and webhooks.

Introduction

halfin exposes a merchant API for payment invoices, hosted checkout, reusable deposit addresses, merchant balances, payouts, rates, supported currencies, and webhook event schemas.

The public API base URL is:

https://dashboard.halfin.xyz/api

Use sk_test_... keys for isolated test data and sk_live_... keys for live funds. The environment is part of the API key; merchant API requests do not switch environments with a different public base URL.

Integration

Getting access

Create a merchant account in the dashboard.
Create a test API key under Settings -> API Keys.
Configure a webhook endpoint and save the webhook secret.
Create a first invoice with an idempotency key.
Fulfill only after a verified webhook or a server-side invoice status check.

Making a request

Merchant endpoints use JSON request bodies and JSON responses.

curl -X POST https://dashboard.halfin.xyz/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HALFIN_API_KEY" \
  -d '{
    "currency": "BTC",
    "amount": "0.01000000",
    "description": "Order #0001",
    "idempotency_key": "order-0001"
  }'

The response envelope contains data on success and meta.request_id for support and logs.

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000001",
    "currency": "BTC",
    "amount_requested": "0.01000000",
    "status": "pending",
    "checkout_url": "https://checkout.halfin.xyz/pay/00000000000000000000000000000000",
    "expires_at": "2026-06-01T12:30:00Z",
    "created_at": "2026-06-01T12:00:00Z"
  },
  "meta": {
    "request_id": "req_000000000001"
  }
}

Authentication

Surface	Authentication	Notes
Merchant endpoints	`X-API-Key: sk_test_...` or `X-API-Key: sk_live_...`	Required for invoices, payouts, balances, ledger, and static addresses.
Public data endpoints	None	Rates and currencies are public read endpoints.
Webhook delivery	`X-Halfin-Signature`	Verify every received webhook with the raw request body.

There is no merchant request HMAC scheme for ordinary API calls. HMAC is used for webhook verification only.

Gates

Gate identifiers are the values used by the API and webhook payloads. Limits are stored in the processor gate seeds and can still be restricted per merchant or environment by account settings.

Call GET /v1/currencies for the current live availability.

Production Gates

Gate ID	Asset	Network	Confirmation mode	Min	Max
`bitcoin`	BTC	bitcoin	3 blocks	0.0001	10
`ethereum`	ETH	ethereum	12 blocks	0.001	100
`solana`	SOL	solana	commitment	0.01	10000
`ethereum_usdt`	USDT	ethereum	12 blocks	1	100000
`ethereum_usdc`	USDC	ethereum	12 blocks	1	100000
`bsc`	BNB	bsc	15 blocks	0.001	100
`bsc_usdt`	USDT	bsc	15 blocks	1	100000
`tron`	TRX	tron	19 blocks	1	100000
`tron_usdt`	USDT	tron	19 blocks	1	100000
`base`	ETH	base	20 blocks	0.001	100
`arbitrum`	ETH	arbitrum	20 blocks	0.001	100
`arbitrum_usdt`	USDT	arbitrum	20 blocks	1	100000
`arbitrum_usdc`	USDC	arbitrum	20 blocks	1	100000
`polygon`	POL	polygon	128 blocks	0.1	100000
`polygon_usdt`	USDT	polygon	128 blocks	1	100000
`polygon_usdc`	USDC	polygon	128 blocks	1	100000
`solana_usdc`	USDC	solana	commitment	1	100000
`xrp`	XRP	xrp	immediate	0.1	100000

Test Environment Gates

Test keys use the same API shape and gate identifiers while keeping invoices, balances, payouts, and webhook deliveries isolated from live funds.

Test key gate group	Gate IDs
Native assets	`bitcoin`, `ethereum`, `solana`, `bsc`, `tron`, `base`, `arbitrum`, `polygon`, `xrp`
Stablecoins	`ethereum_usdt`, `ethereum_usdc`, `bsc_usdt`, `tron_usdt`, `arbitrum_usdt`, `arbitrum_usdc`, `polygon_usdt`, `polygon_usdc`, `solana_usdc`

Call GET /v1/currencies?environment=test for the current test-key availability returned by the API.

Self-Checkout

Redirect customers to the halfin-hosted payment page with the checkout_url returned by POST /v1/invoices. The customer selects a payment method on the checkout page; no wallet or blockchain integration is required on the merchant side. See the Hosted Checkout guide for the full integration steps.

Limits and Quotas

Area	Current contract
Request throttling	Public production throttling is enforced at the edge/reverse proxy, with service-level buckets where configured. A throttled request returns `429` and can include `Retry-After`.
Idempotency	Invoice creation returns the original invoice on same-key/same-body replay and rejects the same key with a different body. Payout creation with the same idempotency key returns the existing payout.
Pagination	List endpoints use `limit` and `offset`; the merchant maximum is 100.
API keys	Test and live keys are isolated. Keep live keys server-side.
Webhooks	Delivery is at least once; handlers must de-duplicate by stable payload identifiers.
Timeouts	Webhook endpoints should respond quickly with a `2xx`; slow or failing endpoints are retried.

Webhooks

halfin sends webhooks as JSON POST requests. Delivery is at least once. balance.credited includes a stable event_id. Invoice and payout events currently do not include a top-level event_id, so make handlers idempotent by the event type plus the invoice, payout, or payment IDs in data.

Events

Event	When it is sent
`invoice.confirming`	A deposit is seen and is waiting for required confirmations.
`invoice.paid`	The invoice amount is met and confirmations are sufficient.
`invoice.overpaid`	The confirmed payment is above the requested amount.
`invoice.underpaid`	The confirmed payment is below the requested amount.
`invoice.expired`	The payment window expired before payment completion.
`invoice.invalid`	The invoice entered an invalid terminal state.
`invoice.late_deposit`	Funds arrived after the invoice expired.
`invoice.deposit_reversed`	A previously observed deposit was reversed.
`invoice.activated`	A draft/deferred invoice was activated.
`invoice.draft_expired`	A draft/deferred invoice expired before activation.
`invoice.sent`	An invoice notification was sent.
`balance.credited`	Merchant balance was credited.
`payout.completed`	A payout completed.
`payout.failed`	A payout failed.
`test`	Dashboard test delivery event.

For payments with settlement conversion, use balance.credited as the fulfillment signal - invoice.paid confirms customer payment but balance credit can still be pending.

Signature Verification

Webhook requests include:

X-Halfin-Signature: t={timestamp},v1={hmac}

Compute HMAC-SHA256(secret, "{timestamp}.{raw_body}"), compare it to v1, and reject timestamps outside a 300 second window.

import crypto from 'node:crypto';

export function verifyHalfinWebhook(
  signatureHeader: string,
  rawBody: Buffer,
  secret: string,
  now = Math.floor(Date.now() / 1000),
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((part) => part.split('=') as [string, string]),
  );
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > 300) return false;
  if (!/^[0-9a-f]{64}$/.test(parts.v1 ?? '')) return false;

  const payload = `${timestamp}.${rawBody.toString('utf8')}`;
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  const expectedBuffer = Buffer.from(expected, 'hex');
  const providedBuffer = Buffer.from(parts.v1, 'hex');
  if (expectedBuffer.length !== providedBuffer.length) return false;

  return crypto.timingSafeEqual(expectedBuffer, providedBuffer);
}

Example Payloads

{
  "event": "invoice.paid",
  "created_at": "2026-06-01T12:05:00Z",
  "data": {
    "invoice_id": "00000000-0000-0000-0000-000000000001",
    "external_id": "order-0001",
    "currency": "BTC",
    "environment": "live",
    "amount_requested": "0.01000000",
    "amount_paid": "0.01000000",
    "status": "paid",
    "paid_at": "2026-06-01T12:05:00Z"
  }
}

{
  "event_id": "00000000-0000-0000-0000-000000000102",
  "event": "balance.credited",
  "created_at": "2026-06-01T12:06:00Z",
  "data": {
    "invoice_id": "00000000-0000-0000-0000-000000000001",
    "payment_id": "00000000-0000-0000-0000-000000000002",
    "external_id": "order-0001",
    "outcome": "target_credited",
    "source_amount": "0.01000000",
    "source_currency": "BTC",
    "source_network": "bitcoin",
    "credited_amount": "600.000000",
    "credited_currency": "USDC",
    "credited_network": "ethereum"
  }
}

Webhook Schemas

Request Body

eventstring

Event type identifier.

Value in

"invoice.confirming" | "invoice.paid" | "invoice.overpaid" | "invoice.underpaid" | "invoice.expired" | "invoice.invalid" | "invoice.deposit_reversed"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceWebhookData

Payload data for invoice webhook events (invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.invalid, invoice.deposit_reversed).

Phase 4 (multi-fiat plan §D) adds amount_fiat + fiat_currency alongside the legacy amount_usd. Dual emission lets webhook consumers migrate on their own timeline; once the ss_core_webhook_legacy_amount_usd_emitted_total counter drops to zero for 7 consecutive days, Phase 5+ removes the legacy amount_usd field.

Request Body

eventstring

Event type identifier.

Value in

"invoice.confirming" | "invoice.paid" | "invoice.overpaid" | "invoice.underpaid" | "invoice.expired" | "invoice.invalid" | "invoice.deposit_reversed"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceWebhookData

Payload data for invoice webhook events (invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.invalid, invoice.deposit_reversed).

Request Body

eventstring

Event type identifier.

Value in

"invoice.confirming" | "invoice.paid" | "invoice.overpaid" | "invoice.underpaid" | "invoice.expired" | "invoice.invalid" | "invoice.deposit_reversed"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceWebhookData

Payload data for invoice webhook events (invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.invalid, invoice.deposit_reversed).

Request Body

eventstring

Event type identifier.

Value in

"invoice.confirming" | "invoice.paid" | "invoice.overpaid" | "invoice.underpaid" | "invoice.expired" | "invoice.invalid" | "invoice.deposit_reversed"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceWebhookData

Payload data for invoice webhook events (invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.invalid, invoice.deposit_reversed).

Request Body

eventstring

Event type identifier.

Value in

"invoice.confirming" | "invoice.paid" | "invoice.overpaid" | "invoice.underpaid" | "invoice.expired" | "invoice.invalid" | "invoice.deposit_reversed"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceWebhookData

Payload data for invoice webhook events (invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.invalid, invoice.deposit_reversed).

Request Body

eventstring

Event type identifier.

Value in

"invoice.confirming" | "invoice.paid" | "invoice.overpaid" | "invoice.underpaid" | "invoice.expired" | "invoice.invalid" | "invoice.deposit_reversed"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceWebhookData

Payload data for invoice webhook events (invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.invalid, invoice.deposit_reversed).

Request Body

eventstring

Event type identifier.

Value in"invoice.late_deposit"

created_atstring

Event creation timestamp.

Formatdate-time

dataLateDepositWebhookData

Payload data for invoice.late_deposit events.

Commit 2 of the rate-freshness + offerability refactor adds four OPTIONAL fields (rate_applied, rate_updated_at, rate_age_ms, rate_stale) that land ONLY on static-address credits. Invoice-based late deposits carry a slot-locked rate and omit these fields — the slot's exchange_rate is authoritative for the invoice-based case. Merchant SDK consumers that depend on additionalProperties: false are unaffected because the new keys are explicitly listed.

Request Body

eventstring

Event type identifier.

Value in

"invoice.confirming" | "invoice.paid" | "invoice.overpaid" | "invoice.underpaid" | "invoice.expired" | "invoice.invalid" | "invoice.deposit_reversed"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceWebhookData

Payload data for invoice webhook events (invoice.confirming, invoice.paid, invoice.overpaid, invoice.underpaid, invoice.expired, invoice.invalid, invoice.deposit_reversed).

Request Body

eventstring

Event type identifier.

Value in"invoice.activated"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceActivatedWebhookData

Payload data for invoice.activated events.

Request Body

eventstring

Event type identifier.

Value in"invoice.draft_expired"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceDraftExpiredWebhookData

Payload data for invoice.draft_expired events.

Request Body

eventstring

Event type identifier.

Value in"invoice.sent"

created_atstring

Event creation timestamp.

Formatdate-time

dataInvoiceSentWebhookData

Payload data for invoice.sent events.

Request Body

event_idstring

Stable event UUID for merchant-side idempotency.

Formatuuid

eventstring

Event type identifier.

Value in"balance.credited"

created_atstring

Balance credit transaction timestamp.

Formatdate-time

dataBalanceCreditedWebhookData

Payload data for balance.credited events emitted only after spendable merchant balance is credited.

Request Body

eventstring

Event type identifier.

Value in"payout.completed"

created_atstring

Event creation timestamp.

Formatdate-time

dataPayoutCompletedWebhookData

Payload data for payout.completed events.

Request Body

eventstring

Event type identifier.

Value in"payout.failed"

created_atstring

Event creation timestamp.

Formatdate-time

dataPayoutFailedWebhookData

Payload data for payout.failed events.

Request Body

typestring

Test event type identifier.

Value in"test"

messagestring

Human-readable test message.

environmentstring

Environment selected for the test delivery.

Value in"live" | "test"

created_atstring

Event creation timestamp.

Formatdate-time

Changelog

Date	Change
2026-05-27	Documentation rebuilt as a single-page API reference. No API behavior changed in this documentation update.
2026-05-13	Public OpenAPI reference published for merchant endpoints, public data endpoints, and webhook schemas.

API Methods

Method Overview

Group	Method	Path	Auth
Public Data	GET	`/v1/rates`	None
Public Data	GET	`/v1/currencies`	None
Balances	GET	`/v1/balances`	API key
Balances	GET	`/v1/balances/{currency}/ledger`	API key
Invoices	POST	`/v1/invoices`	API key
Invoices	GET	`/v1/invoices`	API key
Invoices	GET	`/v1/invoices/{invoiceID}`	API key
Invoices	POST	`/v1/invoices/{invoiceID}/cancel`	API key
Static Addresses	POST	`/v1/addresses`	API key
Static Addresses	GET	`/v1/addresses`	API key
Static Addresses	GET	`/v1/addresses/{addressID}`	API key
Static Addresses	GET	`/v1/addresses/{addressID}/invoices`	API key
Payouts	POST	`/v1/payouts`	API key
Payouts	GET	`/v1/payouts`	API key
Payouts	GET	`/v1/payouts/{payoutID}`	API key
Payouts	POST	`/v1/payouts/{payoutID}/cancel`	API key

Public Data

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/rates", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/rates", {  method: "GET"})

{
  "data": {
    "property1": {
      "usd": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "property2": {
      "usd": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Query Parameters

environment?string

Which environment's currencies to return. Defaults to live.

Default"live"

Value in"live" | "test"

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/currencies?environment=live", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/currencies?environment=live", {  method: "GET"})

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "network": "string",
      "decimals": 0,
      "confirmations_required": 0,
      "status": "string"
    }
  ],
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Balances

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Query Parameters

environment?string

Reserved for forward compatibility with JWT-authenticated dashboard callers. For API-key callers the environment is determined by the key itself and this parameter is ignored.

Value in"live" | "test"

limit?integer

Reserved for forward compatibility.

Range1 <= value <= 100

offset?integer

Reserved for forward compatibility.

Range0 <= value

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/balances?environment=live&limit=1&offset=0", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/balances?environment=live&limit=1&offset=0", {  method: "GET"})

{
  "data": [
    {
      "currency": "BTC",
      "network": "bitcoin",
      "environment": "live",
      "available": "string",
      "pending": "string",
      "total_received": "string",
      "total_fees": "string",
      "total_paid_out": "string",
      "total_in_base_currency": "string"
    }
  ],
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Path Parameters

currencystring

Currency code (e.g. BTC, ETH, SOL).

Lengthlength <= 20

Query Parameters

entry_type?string

Filter by ledger entry type.

Lengthlength <= 255

limit?integer

Maximum number of items to return (default 20, max 100).

Default20

Range1 <= value <= 100

offset?integer

Number of items to skip.

Default0

Range0 <= value

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/balances/string/ledger?entry_type=string&limit=20&offset=0", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/balances/string/ledger?entry_type=string&limit=20&offset=0", {  method: "GET"})

{
  "data": [
    {
      "id": 0,
      "environment": "live",
      "entry_type": "string",
      "amount": "string",
      "direction": "credit",
      "balance_after": "string",
      "reference_type": "string",
      "reference_id": "97c1ff22-6e4f-4821-b1d3-5236781d37b8",
      "description": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "request_id": "string",
    "pagination": {
      "total": 0,
      "limit": 0,
      "offset": 0,
      "has_more": true
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Invoices

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Request Body

currency?string

Cryptocurrency code (e.g. BTC, ETH, SOL). Required when deferred is false. Optional when deferred is true (payer chooses at activation time).

Lengthlength <= 20

network?string

Blockchain network (e.g. ethereum, polygon, solana, tron, bsc, arbitrum). Required for multi-chain tokens whose network cannot be unambiguously inferred from the currency ticker (USDT, USDC, ETH). Optional for unambiguous tokens (BTC, SOL, TRX, etc.) — the backend fills it in via currency.InferNetwork when omitted. Sending an unsupported (currency, network) pair returns a 400 validation_error.

Lengthlength <= 30

amount?string

Crypto-denominated amount the merchant wants to collect, as a decimal string in units of currency. Required unless amount_fiat (or the legacy amount_usd) is sent instead. Mutually exclusive with the fiat-amount fields — sending both is a validation error.

Lengthlength <= 50

amount_usd?string

DEPRECATED — legacy alias for amount_fiat with fiat_currency='USD'. Kept accepted during the Phase 4 backward-compat window (plan §C.2 rule 1 / §D). Migrate to amount_fiat + fiat_currency.

Aliasing precedence rules (§C.2, checked in this order):

amount_usd supplied alone (no amount_fiat, and fiat_currency is empty or "USD") → normalized to amount_fiat + fiat_currency='USD'.
BOTH amount_usd AND amount_fiat supplied (fiat_currency implicit or explicit "USD") → amount_fiat wins, amount_usd is ignored for pricing.
amount_usd supplied together with a non-USD fiat_currency → request is rejected with 400 conflicting_amount_fields REGARDLESS of whether amount_fiat is also present. Rule 3 overrides Rule 2 — the conflict check runs before the "amount_fiat wins" resolution, because silently coercing a mixed amount_usd + non-USD fiat_currency payload would mis-bill the merchant by the USD/ cross rate (plan §C.2 rule 3 / financial-ask #2).

Lengthlength <= 50

amount_fiat?string

Fiat-denominated amount in the currency named by fiat_currency (default USD). The invoice is billed against the selected crypto at the activation-time exchange rate. Sent instead of amount to express "charge the customer $50 / €50 / £50 worth of BTC". When sent without currency the invoice behaves like the existing deferred "any crypto" flow. When sent alongside a specific currency + network the invoice is locked to that pair (no currency picker on checkout); this combination requires deferred=true. Mutually exclusive with amount.

When BOTH amount_fiat and the legacy amount_usd are supplied, amount_fiat takes precedence (§C.2 rule 2). However, the conflict guard in §C.2 rule 3 (amount_usd + non-USD fiat_currency → 400 conflicting_amount_fields) is evaluated first and overrides rule 2 — see the amount_usd description for the full precedence list.

Lengthlength <= 50

fiat_currency?string

ISO 4217 code that denominates amount_fiat. Defaults to USD when omitted. Must be one of the server-side fiat allowlist (plan §C.2 rule 7 / appsec-ask #7). Sending a code outside the allowlist returns a 400 invalid_fiat_currency.

Lengthlength <= 3

Value in"USD" | "EUR" | "GBP" | "JPY" | "AUD" | "CAD" | "CHF" | "NZD" | "SEK" | "NOK" | "DKK" | "SGD" | "HKD" | "INR" | "BRL"

deferred?boolean

If true, creates a draft invoice. The payment timer starts when the payer activates via the checkout page.

Defaultfalse

description?string

Human-readable invoice description.

Lengthlength <= 1000

external_id?string

Merchant-supplied external reference ID.

Lengthlength <= 255

idempotency_key?string

Idempotency key to prevent duplicate invoices.

Lengthlength <= 255

metadata?object

Key-value metadata attached to the invoice.

Propertiesproperties <= 50

Empty Object

redirect_url?string

URL to redirect the customer after payment.

Formaturi

Lengthlength <= 2048

ttl_minutes?integer

Invoice expiration time as a minute count (0 = default).

underpayment_threshold?string

Decimal string. Payments below this tolerance are rejected.

Lengthlength <= 50

customer_email?string

Optional customer email address. When present, ss-core dispatches an asynchronous INVOICE_PAYMENT_REQUESTED email to this address after the invoice row is committed (fire-and-forget goroutine; the response does not block on Resend). The value is also copied into payer_email so the manual /send endpoint can reuse it without re-entry.

Dispatch is idempotent against a retried CreateInvoice with the same idempotency_key: a subsequent hit that resolves to the existing invoice does not re-send. Phase 5 extends the same auto-send pipeline to INVOICE_PAID and INVOICE_EXPIRED status transitions, also guarded by per-invoice idempotency timestamps.

Future sends are suppressed if Resend reports a hard bounce for this address via the bounce webhook — once the row's email_bounced flag is set, no further emails are issued regardless of subsequent status transitions.

Formatemail

Lengthlength <= 320

Response Body

const body = JSON.stringify({})

fetch("https://dashboard.halfin.xyz/api/v1/invoices", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body
})

const body = JSON.stringify({})fetch("https://dashboard.halfin.xyz/api/v1/invoices", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
    "currency": "string",
    "network": "string",
    "amount_requested": "string",
    "amount_paid": "string",
    "amount_usd": "string",
    "amount_fiat": "string",
    "amount_in_base_currency": "string",
    "fiat_currency": "string",
    "status": "draft",
    "environment": "live",
    "deposit_address": "string",
    "deposit_address_tag": "string",
    "description": "string",
    "external_id": "string",
    "idempotency_key": "string",
    "metadata": {},
    "redirect_url": "string",
    "source": "string",
    "static_address_id": "dfe0e820-d96d-4e58-a685-774321eca4db",
    "checkout_url": "string",
    "payments": [
      {
        "tx_hash": "string",
        "amount": "string",
        "confirmations": 0,
        "required_confirmations": 0,
        "status": "string",
        "detected_at": "2019-08-24T14:15:22Z",
        "settlement_conversion": {
          "target_currency": "string",
          "target_network": "string",
          "source_amount": "string",
          "target_gross_amount": "string",
          "fee_amount": "string",
          "net_amount": "string",
          "quote_status": "not_required",
          "execution_status": "not_required",
          "failure_class": "string",
          "quoted_at": "2019-08-24T14:15:22Z",
          "locked_until": "2019-08-24T14:15:22Z"
        }
      }
    ],
    "expires_at": "2019-08-24T14:15:22Z",
    "paid_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "is_deferred": true,
    "draft_expires_at": "2019-08-24T14:15:22Z",
    "activated_at": "2019-08-24T14:15:22Z",
    "activation_count": 0,
    "is_locked_fiat": true,
    "target_settlement_asset": "passthrough",
    "settlement_target_currency": "USDC",
    "settlement_target_network": "ethereum",
    "payer_email": "string",
    "sent_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Query Parameters

status?string

Filter by status.

Lengthlength <= 255

currency?string

Filter by currency code.

Lengthlength <= 20

limit?integer

Maximum number of items to return (default 20, max 100).

Default20

Range1 <= value <= 100

offset?integer

Number of items to skip.

Default0

Range0 <= value

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/invoices?status=string&currency=string&limit=20&offset=0", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/invoices?status=string&currency=string&limit=20&offset=0", {  method: "GET"})

{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
      "currency": "string",
      "network": "string",
      "amount_requested": "string",
      "amount_paid": "string",
      "amount_usd": "string",
      "amount_fiat": "string",
      "amount_in_base_currency": "string",
      "fiat_currency": "string",
      "status": "draft",
      "environment": "live",
      "deposit_address": "string",
      "deposit_address_tag": "string",
      "description": "string",
      "external_id": "string",
      "idempotency_key": "string",
      "metadata": {},
      "redirect_url": "string",
      "source": "string",
      "static_address_id": "dfe0e820-d96d-4e58-a685-774321eca4db",
      "checkout_url": "string",
      "payments": [
        {
          "tx_hash": "string",
          "amount": "string",
          "confirmations": 0,
          "required_confirmations": 0,
          "status": "string",
          "detected_at": "2019-08-24T14:15:22Z",
          "settlement_conversion": {
            "target_currency": "string",
            "target_network": "string",
            "source_amount": "string",
            "target_gross_amount": "string",
            "fee_amount": "string",
            "net_amount": "string",
            "quote_status": "not_required",
            "execution_status": "not_required",
            "failure_class": "string",
            "quoted_at": "2019-08-24T14:15:22Z",
            "locked_until": "2019-08-24T14:15:22Z"
          }
        }
      ],
      "expires_at": "2019-08-24T14:15:22Z",
      "paid_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "is_deferred": true,
      "draft_expires_at": "2019-08-24T14:15:22Z",
      "activated_at": "2019-08-24T14:15:22Z",
      "activation_count": 0,
      "is_locked_fiat": true,
      "target_settlement_asset": "passthrough",
      "settlement_target_currency": "USDC",
      "settlement_target_network": "ethereum",
      "payer_email": "string",
      "sent_at": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "request_id": "string",
    "pagination": {
      "total": 0,
      "limit": 0,
      "offset": 0,
      "has_more": true
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Path Parameters

invoiceIDstring

Invoice UUID.

Formatuuid

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08", {  method: "GET"})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
    "currency": "string",
    "network": "string",
    "amount_requested": "string",
    "amount_paid": "string",
    "amount_usd": "string",
    "amount_fiat": "string",
    "amount_in_base_currency": "string",
    "fiat_currency": "string",
    "status": "draft",
    "environment": "live",
    "deposit_address": "string",
    "deposit_address_tag": "string",
    "description": "string",
    "external_id": "string",
    "idempotency_key": "string",
    "metadata": {},
    "redirect_url": "string",
    "source": "string",
    "static_address_id": "dfe0e820-d96d-4e58-a685-774321eca4db",
    "checkout_url": "string",
    "payments": [
      {
        "tx_hash": "string",
        "amount": "string",
        "confirmations": 0,
        "required_confirmations": 0,
        "status": "string",
        "detected_at": "2019-08-24T14:15:22Z",
        "settlement_conversion": {
          "target_currency": "string",
          "target_network": "string",
          "source_amount": "string",
          "target_gross_amount": "string",
          "fee_amount": "string",
          "net_amount": "string",
          "quote_status": "not_required",
          "execution_status": "not_required",
          "failure_class": "string",
          "quoted_at": "2019-08-24T14:15:22Z",
          "locked_until": "2019-08-24T14:15:22Z"
        }
      }
    ],
    "expires_at": "2019-08-24T14:15:22Z",
    "paid_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "is_deferred": true,
    "draft_expires_at": "2019-08-24T14:15:22Z",
    "activated_at": "2019-08-24T14:15:22Z",
    "activation_count": 0,
    "is_locked_fiat": true,
    "target_settlement_asset": "passthrough",
    "settlement_target_currency": "USDC",
    "settlement_target_network": "ethereum",
    "payer_email": "string",
    "sent_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Path Parameters

invoiceIDstring

Invoice UUID.

Formatuuid

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel", {
  method: "POST"
})

fetch("https://dashboard.halfin.xyz/api/v1/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel", {  method: "POST"})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
    "currency": "string",
    "network": "string",
    "amount_requested": "string",
    "amount_paid": "string",
    "amount_usd": "string",
    "amount_fiat": "string",
    "amount_in_base_currency": "string",
    "fiat_currency": "string",
    "status": "draft",
    "environment": "live",
    "deposit_address": "string",
    "deposit_address_tag": "string",
    "description": "string",
    "external_id": "string",
    "idempotency_key": "string",
    "metadata": {},
    "redirect_url": "string",
    "source": "string",
    "static_address_id": "dfe0e820-d96d-4e58-a685-774321eca4db",
    "checkout_url": "string",
    "payments": [
      {
        "tx_hash": "string",
        "amount": "string",
        "confirmations": 0,
        "required_confirmations": 0,
        "status": "string",
        "detected_at": "2019-08-24T14:15:22Z",
        "settlement_conversion": {
          "target_currency": "string",
          "target_network": "string",
          "source_amount": "string",
          "target_gross_amount": "string",
          "fee_amount": "string",
          "net_amount": "string",
          "quote_status": "not_required",
          "execution_status": "not_required",
          "failure_class": "string",
          "quoted_at": "2019-08-24T14:15:22Z",
          "locked_until": "2019-08-24T14:15:22Z"
        }
      }
    ],
    "expires_at": "2019-08-24T14:15:22Z",
    "paid_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "is_deferred": true,
    "draft_expires_at": "2019-08-24T14:15:22Z",
    "activated_at": "2019-08-24T14:15:22Z",
    "activation_count": 0,
    "is_locked_fiat": true,
    "target_settlement_asset": "passthrough",
    "settlement_target_currency": "USDC",
    "settlement_target_network": "ethereum",
    "payer_email": "string",
    "sent_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Static Addresses

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Request Body

currencystring

Cryptocurrency code for the static address.

Lengthlength <= 20

label?string

Optional human-readable label.

Lengthlength <= 1000

Response Body

const body = JSON.stringify({
  "currency": "string"
})

fetch("https://dashboard.halfin.xyz/api/v1/addresses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body
})

const body = JSON.stringify({  "currency": "string"})fetch("https://dashboard.halfin.xyz/api/v1/addresses", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
    "currency": "string",
    "environment": "live",
    "gate_id": "string",
    "address": "string",
    "address_tag": "string",
    "label": "string",
    "total_received": "string",
    "invoice_count": 0,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Query Parameters

currency?string

Filter by currency code.

Lengthlength <= 20

limit?integer

Maximum number of items to return (default 20, max 100).

Default20

Range1 <= value <= 100

offset?integer

Number of items to skip.

Default0

Range0 <= value

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/addresses?currency=string&limit=20&offset=0", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/addresses?currency=string&limit=20&offset=0", {  method: "GET"})

{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
      "currency": "string",
      "environment": "live",
      "gate_id": "string",
      "address": "string",
      "address_tag": "string",
      "label": "string",
      "total_received": "string",
      "invoice_count": 0,
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "request_id": "string",
    "pagination": {
      "total": 0,
      "limit": 0,
      "offset": 0,
      "has_more": true
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Path Parameters

addressIDstring

Static address UUID.

Formatuuid

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/addresses/497f6eca-6276-4993-bfeb-53cbbbba6f08", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/addresses/497f6eca-6276-4993-bfeb-53cbbbba6f08", {  method: "GET"})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
    "currency": "string",
    "environment": "live",
    "gate_id": "string",
    "address": "string",
    "address_tag": "string",
    "label": "string",
    "total_received": "string",
    "invoice_count": 0,
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Path Parameters

addressIDstring

Static address UUID.

Formatuuid

Query Parameters

limit?integer

Maximum number of items to return (default 20, max 100).

Default20

Range1 <= value <= 100

offset?integer

Number of items to skip.

Default0

Range0 <= value

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/addresses/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices?limit=20&offset=0", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/addresses/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices?limit=20&offset=0", {  method: "GET"})

{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
      "currency": "string",
      "network": "string",
      "amount_requested": "string",
      "amount_paid": "string",
      "amount_usd": "string",
      "amount_fiat": "string",
      "amount_in_base_currency": "string",
      "fiat_currency": "string",
      "status": "draft",
      "environment": "live",
      "deposit_address": "string",
      "deposit_address_tag": "string",
      "description": "string",
      "external_id": "string",
      "idempotency_key": "string",
      "metadata": {},
      "redirect_url": "string",
      "source": "string",
      "static_address_id": "dfe0e820-d96d-4e58-a685-774321eca4db",
      "checkout_url": "string",
      "payments": [
        {
          "tx_hash": "string",
          "amount": "string",
          "confirmations": 0,
          "required_confirmations": 0,
          "status": "string",
          "detected_at": "2019-08-24T14:15:22Z",
          "settlement_conversion": {
            "target_currency": "string",
            "target_network": "string",
            "source_amount": "string",
            "target_gross_amount": "string",
            "fee_amount": "string",
            "net_amount": "string",
            "quote_status": "not_required",
            "execution_status": "not_required",
            "failure_class": "string",
            "quoted_at": "2019-08-24T14:15:22Z",
            "locked_until": "2019-08-24T14:15:22Z"
          }
        }
      ],
      "expires_at": "2019-08-24T14:15:22Z",
      "paid_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "is_deferred": true,
      "draft_expires_at": "2019-08-24T14:15:22Z",
      "activated_at": "2019-08-24T14:15:22Z",
      "activation_count": 0,
      "is_locked_fiat": true,
      "target_settlement_asset": "passthrough",
      "settlement_target_currency": "USDC",
      "settlement_target_network": "ethereum",
      "payer_email": "string",
      "sent_at": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "request_id": "string",
    "pagination": {
      "total": 0,
      "limit": 0,
      "offset": 0,
      "has_more": true
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Payouts

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Request Body

currencystring

Cryptocurrency code.

Lengthlength <= 20

amountstring

Decimal string amount to send.

Lengthlength <= 50

destinationstring

Destination blockchain address.

Lengthlength <= 256

destination_tag?string

Memo/tag for chains that require it.

Lengthlength <= 256

description?string

Human-readable payout description.

Lengthlength <= 1000

metadata?object

Key-value metadata.

Propertiesproperties <= 50

Empty Object

idempotency_key?string

Idempotency key to prevent duplicate payouts.

Lengthlength <= 255

Response Body

const body = JSON.stringify({
  "currency": "string",
  "amount": "string",
  "destination": "string"
})

fetch("https://dashboard.halfin.xyz/api/v1/payouts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body
})

const body = JSON.stringify({  "currency": "string",  "amount": "string",  "destination": "string"})fetch("https://dashboard.halfin.xyz/api/v1/payouts", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "currency": "string",
    "network": "string",
    "amount": "string",
    "amount_in_base_currency": "string",
    "network_fee": "string",
    "fee_amount": "string",
    "destination": "string",
    "destination_tag": "string",
    "status": "pending_approval",
    "environment": "live",
    "tx_hash": "string",
    "idempotency_key": "string",
    "description": "string",
    "executable_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Query Parameters

status?string

Filter by status.

Lengthlength <= 255

limit?integer

Maximum number of items to return (default 20, max 100).

Default20

Range1 <= value <= 100

offset?integer

Number of items to skip.

Default0

Range0 <= value

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/payouts?status=string&limit=20&offset=0", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/payouts?status=string&limit=20&offset=0", {  method: "GET"})

{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "currency": "string",
      "network": "string",
      "amount": "string",
      "amount_in_base_currency": "string",
      "network_fee": "string",
      "fee_amount": "string",
      "destination": "string",
      "destination_tag": "string",
      "status": "pending_approval",
      "environment": "live",
      "tx_hash": "string",
      "idempotency_key": "string",
      "description": "string",
      "executable_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "request_id": "string",
    "pagination": {
      "total": 0,
      "limit": 0,
      "offset": 0,
      "has_more": true
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Path Parameters

payoutIDstring

Payout UUID.

Formatuuid

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/payouts/497f6eca-6276-4993-bfeb-53cbbbba6f08", {
  method: "GET"
})

fetch("https://dashboard.halfin.xyz/api/v1/payouts/497f6eca-6276-4993-bfeb-53cbbbba6f08", {  method: "GET"})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "currency": "string",
    "network": "string",
    "amount": "string",
    "amount_in_base_currency": "string",
    "network_fee": "string",
    "fee_amount": "string",
    "destination": "string",
    "destination_tag": "string",
    "status": "pending_approval",
    "environment": "live",
    "tx_hash": "string",
    "idempotency_key": "string",
    "description": "string",
    "executable_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

Authorization

X-API-Key<token>

API key issued by the merchant dashboard. The key's environment (live/test) determines which data the caller can access. Permissions on the key control which endpoints are reachable.

In: header

Path Parameters

payoutIDstring

Payout UUID.

Formatuuid

Response Body

fetch("https://dashboard.halfin.xyz/api/v1/payouts/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel", {
  method: "POST"
})

fetch("https://dashboard.halfin.xyz/api/v1/payouts/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel", {  method: "POST"})

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "currency": "string",
    "network": "string",
    "amount": "string",
    "amount_in_base_currency": "string",
    "network_fee": "string",
    "fee_amount": "string",
    "destination": "string",
    "destination_tag": "string",
    "status": "pending_approval",
    "environment": "live",
    "tx_hash": "string",
    "idempotency_key": "string",
    "description": "string",
    "executable_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      "string"
    ]
  },
  "meta": {
    "request_id": "string"
  }
}

halfin API

200

500

200

500

200

401

403

500

200

400

401

403

500

201

400

401

403

422

500

503

200

401

403

500

200

400

401

403

404

500

200

400

401

403

404

409

500

201

400

401

403

422

500

503

200

401

403

500

200

400

401

403

404

500

200

400

401

403

404

500

201

400

401

403

422

500

503

200

401

403