Skip to documentationDocumentation
On this page

Currencies & networks

Get supported payment currencies.

Returns all available payment currencies with their network details and confirmation requirements. Use it to decide which currencies and networks can be offered in the environment determined by the API key.

Usage notes#

Every authenticated key has the implicit catalog:read permission. The key selects the environment; do not send an environment query parameter.

currency and network together identify a pair. Use the returned decimals and confirmations_required for that environment. status: online indicates a current USD price; it does not guarantee that your merchant is enabled for every operation on that pair. A pair can remain in the catalog as offline when its price is unavailable.

Currency and network identifiers#

These identifiers describe the supported catalog vocabulary, not a guarantee that every pair is currently enabled. The actual response is authoritative for availability, precision, and confirmations.

CurrencyNetworkAsset
BTCbitcoinBitcoin
ETHethereumEthereum
ETHarbitrumEther on Arbitrum
ETHbaseEther on Base
POLpolygonPolygon
BNBbscBNB
SOLsolanaSolana
TRXtronTRON
USDTethereumTether on Ethereum
USDTtronTether on TRON
USDTbscTether on BSC
USDTarbitrumTether on Arbitrum
USDTpolygonTether on Polygon
USDCethereumUSD Coin on Ethereum
USDCsolanaUSD Coin on Solana
USDCarbitrumUSD Coin on Arbitrum
USDCpolygonUSD Coin on Polygon

Always supply network for crypto requests.

Fiat invoice prices#

You can price an invoice in an enabled fiat currency and let the customer choose a cryptocurrency at checkout. These denomination codes describe the invoice price; they are not deposit or payout networks and are not returned by this endpoint. Availability is validated when you create the invoice; a listed denomination may be disabled.

CurrencyNameDecimal placesNetwork
USDUS dollar2Omit network
EUREuro2Omit network

Send the invoice price in amount and the fiat code in currency. The API validates whether the denomination is available. The crypto payment amount is calculated when the customer selects a payment option. See invoice creation and amounts.

GET/v1/currencies
curl
curl --request GET 'https://api.thehalfin.com/v1/currencies' \
  --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

Response Body

200 Currency list.

application/json

  • dataarray<object>Required

    Example: [{"currency":"USDC","network":"ethereum","name":"USD Coin on Ethereum","decimals":6,"confirmations_required":12,"status":"online","is_native":false}]

    • currencystringRequired
      Asset ticker.

      Example: string

    • networkstringRequired
      Network identifier.

      Example: string

    • namestringRequired
      Human-readable currency and network name.

      Example: string

    • decimalsintegerRequired
      Number of decimal places.
      • Format: int32

      Example: 0

    • confirmations_requiredintegerRequired
      Required blockchain confirmations.
      • Format: int32

      Example: 0

    • statusstringRequired
      Online when a current USD price exists for the pair (constant for stablecoins or a fresh market rate), offline otherwise.

      Example: string

    • is_nativebooleanRequired
      Whether this currency is the network's native asset.

      Example: false

  • 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

200 response
{
  "data": [
    {
      "currency": "USDC",
      "network": "ethereum",
      "name": "USD Coin on Ethereum",
      "decimals": 6,
      "confirmations_required": 12,
      "status": "online",
      "is_native": false
    }
  ],
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

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

400 response
{
  "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

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

403 `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":"api_key_ip_forbidden","message":"string","details":["string"]}

    • code"api_key_ip_forbidden"Required
      `api_key_ip_forbidden`: The request source address is not allowed by the API key.

      Example: api_key_ip_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

403 response
{
  "error": {
    "code": "api_key_ip_forbidden",
    "message": "API key is not allowed from this IP address"
  },
  "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

500 response
{
  "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

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