Eligible targets

Lists merchant-safe target choices for a manual conversion from the selected credited source balance. Disabled targets remain visible with a sanitized reason.

Usage notes#

Requires balances:read. Supply source_currency and source_network. available means the target is currently eligible; temporarily_unavailable can recover, while no_route is not an available conversion path. Discovery does not reserve liquidity or guarantee later admission. Use the returned currency and network identifiers in Create.

Live-only: a test API key returns 422 not_live. See conversion lifecycle and webhooks for completion, failure, recovery, and ID reconciliation.

GET/v1/conversions/targets

curl --request GET 'https://api.thehalfin.com/v1/conversions/targets?source_currency=string&source_network=string' \
  --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

source_currencystringRequired
- Maximum length: 20
Example: string
source_networkstringRequired
- Maximum length: 64
Example: string

Response Body

200 Manual conversion target choices.

application/json

dataobjectRequired
- Unknown properties are rejected
Example: {"source_currency":"string","source_network":"string","targets":[{"currency":"string","network":"string","target_currency":"string","target_network":"string","enabled":false,"reason":null,"status":"available","status_reason":null}]}
- source_currencystringRequired
  Example: string
- source_networkstringRequired
  Example: string
- targetsarray<object>Required
  Example: [{"currency":"string","network":"string","target_currency":"string","target_network":"string","enabled":false,"reason":null,"status":"available","status_reason":null}]
  - currencystringRequired
    Asset ticker.
    Example: string
  - networkstringRequired
    Network identifier.
    Example: string
  - target_currencystringRequired
    Target currency code.
    Example: string
  - target_networkstringRequired
    Target network.
    Example: string
  - enabledbooleanRequired
    Whether this target can currently be quoted for the selected source.
    Example: false
  - reason"same_asset" | "unsupported_route" | "route_unavailable" | nullRequired
    Sanitized disabled reason. Null when enabled.
    Example: null
  - status"available" | "temporarily_unavailable" | "no_route"Required
    Merchant-facing conversion target availability.
    Example: available
  - status_reasonstring | nullRequired
    Sanitized backend reason for the availability status. Null when no extra detail exists.
    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": {
    "source_currency": "string",
    "source_network": "string",
    "targets": [
      {
        "currency": "string",
        "network": "string",
        "target_currency": "string",
        "target_network": "string",
        "enabled": false,
        "reason": null,
        "status": "available",
        "status_reason": null
      }
    ]
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000001"
  }
}

400 `validation_error`: The request format 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 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"
  }
}

422 `not_live`: Manual conversion is available with live API keys only.

application/json

errorobjectRequired
The error code and diagnostic message.
- Unknown properties are rejected
Example: {"code":"not_live","message":"string","details":["string"]}
- code"not_live"Required
  `not_live`: Manual conversion is available with live API keys only.
  Example: not_live
- 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": "not_live",
    "message": "Manual conversion is available in the live contour only."
  },
  "meta": {
    "request_id": "00000000-0000-4000-8000-000000000001"
  }
}

500 `internal_error`: The request could not be completed. Contact support with the request ID.

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 request could not be completed. Contact support with the request ID.
  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.

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.
  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