Rates

Returns USD exchange rates for every enabled currency and network pair in the environment determined by the API key. The response is an array with one entry per currency and network pair, identified by currency and network. Pairs without a current USD price are omitted; if none have a price, the array is empty. The response is not paginated.

What a rate means#

usd is a decimal string: the reference USD value of one unit of the currency on that network. It is not an executable exchange quote or a promise of proceeds. An invoice fixes its payment rate at checkout activation; requesting rates later does not change that snapshot.

Response entries#

data is an array. Each entry contains currency, network, usd, and updated_at. Match an entry to the currency catalog using both currency and network.

The same currency on different networks has a separate entry for each network. Native assets and tokens use the same fields. If your integration needs a lookup table or a currency-by-network matrix, build it from these entries. Do not rely on array positions to identify a pair.

The response is not paginated. When no pair has a current price, data is [].

For a market-derived rate, updated_at is the observation timestamp. For a configured constant rate, it is null. The complete response example is below.

Live and test#

Every valid API key has catalog:read. The key selects the currency/network catalog; do not send an environment parameter or use a different hostname.

Live and test can expose different pairs and confirmation requirements. Prices are shared reference valuations for pairs configured in both environments. Test coin amounts use those reference valuations; faucet coins do not have an independent market price. Test currently supports native assets on configured testnets, not live tokens such as USDT or USDC. See environments.

Missing prices#

A pair with no fresh USD price is omitted, not assigned zero. The same pair is offline in the currency catalog. A catalog or rate-service failure can fail the whole request with 503.

A catalog entry or available rate does not grant permission to transact on the pair. Your merchant must also be enabled for the requested operation.

GET/v1/rates

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

application/json

dataarray<object>Required
USD reference rates identified by currency and network, using the same pair as the currency catalog. Networks sharing a ticker have distinct entries. Pairs without a current USD price are omitted; an empty result is an empty array. Not paginated.
Example: [{"currency":"ETH","network":"ethereum","usd":"2500.00","updated_at":"2024-01-01T00:00:00Z"},{"currency":"USDC","network":"ethereum","usd":"1.00","updated_at":null},{"currency":"USDC","network":"solana","usd":"1.00","updated_at":null}]
- currencystringRequired
  Asset ticker, matching currency in the currency catalog.
  Example: string
- networkstringRequired
  Network identifier, matching network in the currency catalog.
  Example: string
- usdstringRequired
  Reference USD value of one unit of the currency on this network, as a decimal string. Not an executable exchange quote.
  - Format: decimal
  - Pattern: ^\d+(\.\d+)?$
  Example: 1
- updated_atstring | nullRequired
  Market observation timestamp, or null for a configured constant rate.
  - Format: date-time
  Example: null
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

{
  "data": [
    {
      "currency": "ETH",
      "network": "ethereum",
      "usd": "2500.00",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "currency": "USDC",
      "network": "ethereum",
      "usd": "1.00",
      "updated_at": null
    },
    {
      "currency": "USDC",
      "network": "solana",
      "usd": "1.00",
      "updated_at": null
    }
  ],
  "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

{
  "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 `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

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

{
  "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"
  }
}

What a rate means# #

Response entries# #

Live and test# #

Missing prices# #

Authorization #

Response Body #

What a rate means#

Response entries#

Live and test#

Missing prices#

Authorization

Response Body