---
title: "Convert a single amount between two ISO 4217 currencies (ECB rates)"
method: GET
path: "/api/v1/fx/convert"
tags: ["FX"]
---

# Convert a single amount between two ISO 4217 currencies (ECB rates)

`GET /api/v1/fx/convert`

## Request

- Base URL: `https://api.hub-equity.com`
- URL: `https://api.hub-equity.com/api/v1/fx/convert`
- Auth: HTTP bearer

Single-amount FX conversion using ECB reference rates. `rate_type` ∈ {closing (spot — BS items), average_ytd (P&L / CF), average_prior_year}. Cross rates (e.g. USD→JPY) resolve via the EUR pivot.

Returns `success=false` (with `converted_amount=0.0`) when no ECB fix is available — do NOT cite the amount in that case. `404` for a malformed request (bad ISO code, unsupported pair, bad date/rate_type).

Differs from `/fx/rates` (raw spot+avg rates for client-side math on a metric series) — this does the `amount × rate` arithmetic.

## Query parameters

- `amount` number, required: Source amount (positive or negative).
- `from_currency` string, required: ISO 4217 source code (e.g. USD).
- `to_currency` string, required: ISO 4217 target code (e.g. EUR).
- `date` string, nullable: ISO date (YYYY-MM-DD) for the spot / end-of-window. Defaults to today.
- `rate_type` string: closing (default) | average_ytd | average_prior_year.

## Response `200`

Conversion result (check the `success` field).

- ApiResponseConvertCurrencyResult
  - `success` boolean, required
  - `data` ConvertCurrencyResult
    - `success` boolean: False when no FX fix could be resolved (rate_used == 0). When false, DO NOT cite converted_amount - it is 0.0, not a real conversion.
    - `converted_amount` number, required
    - `rate_used` number, required
    - `rate_type` 'closing' | 'average_ytd' | 'average_prior_year', required
    - `rate_kind_resolved` string, required: Kind of rate that resolved this conversion : 'spot' or 'avg_period'.
    - `from_currency` string, required
    - `to_currency` string, required
    - `requested_date` string, required
    - `fix_date` string, nullable: The requested date, echoed. The rate used is the latest ECB fixing available on or before it (weekend, holiday, or no recent fixing).
    - `source` string: Provenance - currently ECB Reference Rates only.
    - `notes` string[]
  - `error` ApiError: API error details.
    - `code` string, required
    - `message` string, required
    - `details` object, nullable
  - `meta` ApiMeta: API response metadata. Pagination fields (``page`` / ``per_page`` / ``total``) are populated on collection endpoints only. They are omitted from the payload on single-resource endpoints.
    - `timestamp` string, date-time
    - `request_id` string, nullable
    - `page` integer, nullable
    - `per_page` integer, nullable
    - `total` integer, nullable
  - `links` ApiLinks: HATEOAS-style pagination cursors. Host-relative path + query links for a collection page. Present on collection endpoints, ``null`` fields where a page doesn't exist (``next`` on the last page, ``prev`` on the first). The whole ``links`` object is omitted from single-resource responses (see ``ApiResponse`` serializer).
    - `self` string, nullable
    - `first` string, nullable
    - `prev` string, nullable
    - `next` string, nullable
    - `last` string, nullable

## Other responses

- `404`: Malformed request — unsupported pair / bad date.
- `422`: Validation Error

---

[API](https://skmtc.dev/hub-equity/apis/hub-equity-api.md) · [All operations](https://skmtc.dev/hub-equity/apis/hub-equity-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hub-equity/apis/hub-equity-api/revisions/e8eeda5dc13e?raw)