List

Returns a paginated list of static addresses for the authenticated merchant. Supports filtering by currency.

Usage notes#

Requires addresses:read. This list uses limit and cursor, with a currency filter. Read meta.has_more and pass meta.next_cursor to continue. There is no network, external-ID, or customer-ID filter; persist the address/customer relationship in your own application. See pagination.

GET/v1/addresses

curl --request GET 'https://api.thehalfin.com/v1/addresses' \
  --header "X-API-Key: $HALFIN_API_KEY"

Authorization

X-API-KeystringRequired
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.
Example: $HALFIN_API_KEY

Query Parameters

currencystringOptional
Filter by currency code.
- Maximum length: 20
Example: string
limitintegerOptional
Maximum number of items to return (default 20, max 100).
- Minimum: 1
- Maximum: 100
- Default: 20
Example: 20
cursorstringOptional
Opaque cursor from meta.next_cursor. Omit for the first page. Bound to the collection, scope, filters, and ordering.
- Maximum length: 8192
Example: string

Response Body

200 Paginated address list.

application/json

dataarray<object>Required
Example: [{"id":"00000000-0000-0000-0000-000000000003","merchant_id":"00000000-0000-0000-0000-000000000002","currency":"USDC","network":"ethereum","environment":"live","address":"0x0000000000000000000000000000000000000001","address_tag":null,"label":"Customer 1001","total_received":"0","invoice_count":0,"created_at":"2026-09-14T10:00:00Z"}]
- idstringRequired
  Static address UUID.
  - Format: uuid
  Example: 00000000-0000-0000-0000-000000000001
- merchant_idstring | nullRequired
  Owning merchant UUID.
  - Format: uuid
  Example: null
- currencystringRequired
  Currency code.
  Example: string
- networkstringRequired
  Blockchain network key (e.g. ethereum, tron, bitcoin).
  Example: string
- environment"live" | "test"Required
  Environment.
  Example: live
- addressstringRequired
  Blockchain deposit address.
  Example: string
- address_tagstring | nullRequired
  Memo/tag for chains that require it.
  Example: null
- labelstringRequired
  Human-readable label.
  Example: string
- total_receivedstringRequired
  Decimal string of total deposits received.
  Example: 1
- invoice_countintegerRequired
  Number of auto-created invoices.
  Example: 0
- created_atstringRequired
  Creation timestamp.
  - Format: date-time
  Example: 2026-01-01T00:00:00Z
- status"active" | "retired"Required
  `active`: the address takes deposits and may be shown to payers. `retired`: the address is no longer offered and must not be shown to payers; a deposit that still reaches it is recorded on its history as before. An address the platform retired is replaced by a fresh one (`replaced_by`) and is not listed among the merchant's addresses; it stays readable by id with its invoices.
  Example: active
- replaced_bystring | nullRequired
  The static address that replaced this retired one, once it is issued; null otherwise.
  - Format: uuid
  Example: null
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001","has_more":false,"next_cursor":null}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. An inbound value is adopted only from explicitly trusted ingress; public client values are replaced.
  Example: string
- has_morebooleanRequired
  True exactly when next_cursor is not null.
  Example: false
- next_cursorstring | nullRequired
  Opaque cursor for the next page. Null when this is the last page.
  Example: null

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000003",
      "merchant_id": "00000000-0000-0000-0000-000000000002",
      "currency": "USDC",
      "network": "ethereum",
      "environment": "live",
      "address": "0x0000000000000000000000000000000000000001",
      "address_tag": null,
      "label": "Customer 1001",
      "total_received": "0",
      "invoice_count": 0,
      "created_at": "2026-09-14T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001",
    "has_more": false,
    "next_cursor": null
  }
}

400 `validation_error`: The request format, parameters, headers, or field values are invalid.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"validation_error","message":"string","details":["string"]}
- code"validation_error"Required
  `validation_error`: The request format, parameters, headers, or field values are invalid.
  Example: validation_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

401 `unauthorized`: A valid API key is required.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"unauthorized","message":"string","details":["string"]}
- code"unauthorized"Required
  `unauthorized`: A valid API key is required.
  Example: unauthorized
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

403 `forbidden`: The API key does not have permission for this operation. `api_key_ip_forbidden`: The request source address is not allowed by the API key.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"forbidden","message":"string","details":["string"]}
- code"forbidden" | "api_key_ip_forbidden"Required
  `forbidden`: The API key does not have permission for this operation. `api_key_ip_forbidden`: The request source address is not allowed by the API key.
  Example: forbidden
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "forbidden",
    "message": "Permission denied"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

500 `internal_error`: The API could not complete the request. Contact support with the request ID if the error persists.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"internal_error","message":"string","details":["string"]}
- code"internal_error"Required
  `internal_error`: The API could not complete the request. Contact support with the request ID if the error persists.
  Example: internal_error
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

503 `service_unavailable`: The service is temporarily unavailable. Retry later.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"service_unavailable","message":"string","details":["string"]}
- code"service_unavailable"Required
  `service_unavailable`: The service is temporarily unavailable. Retry later.
  Example: service_unavailable
- messagestringRequired
  Human-readable description of the error.
  Example: string
- detailsarray<string>Optional
  Optional structured context (validation errors, etc.).
  Example: ["string"]
metaobjectRequired
- Unknown properties are rejected
Example: {"request_id":"00000000-0000-0000-0000-000000000001"}
- request_idstringRequired
  Correlation identifier issued by the API, also returned in the X-Request-ID response header. Client-supplied X-Request-ID values are replaced.
  Example: string

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

Usage notes# #

Authorization #

Query Parameters #

Response Body #

Usage notes#

Authorization

Query Parameters

Response Body