> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.
# Get FX Rates
> Read Yuno's official daily FX rate — the same reference Yuno uses for its own reporting — so your prices and reconciliation line up with ours.
Merchants selling across borders need a single reference rate to price in one currency and reconcile in another. This endpoint returns **Yuno's official daily FX rate**, the same reference Yuno uses for its own reporting, expressed as **units of the currency per 1 USD**.
Around 161 currencies are published per day. `USD` itself is published with a rate of `1`.
**Enabled per organization**
This API requires activation for your organization. Contact your Key Account Manager (KAM) to enable it.
## What this is, and what it is not
This is a **reference rate**, published once per day for a closed day. Yuno does not commit to processing or settling at it.
* It is read-only: no quoting, no locking, no conversion applied to a payment.
* It is not a live or intra-day rate. A day's value is final once the daily load closes.
* To convert an actual transaction at checkout, use [Conversion Rate](/reference/conversion-rate/get-conversion-rate) instead. That is a different product: a provider quote for one transaction.
## Choosing what you ask for
Every parameter is optional, and the shape of the answer follows what you send:
| You send | You get |
| - | - |
| Nothing | The latest available day, every currency. |
| `currency=COP` | The latest available day, that currency only. |
| `start_date=2026-09-28` | That day, every currency. |
| `start_date=2026-09-28&end_date=2026-09-30` | That range, every currency. |
| `start_date=…¤cy=COP` | The day or range, that currency only. |
`end_date` is the only parameter with a companion: it cannot be used without `start_date`. Everything else stands alone.
**Range limits:** up to 31 days when `currency` is omitted, and up to 366 days when you ask for a single currency.
### The latest available day
With no dates, you get the most recent published day rather than a date you have to compute. The current day is never served — its value is not final until the daily load closes — so the newest day you can receive is yesterday (UTC).
If a daily load is delayed, this is also the safe way to ask: you receive the newest day that actually exists instead of an empty answer for a day that was never published.
## Reading the response
```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
"base_currency": "USD",
"rates": [
{ "fx_date": "2026-09-28", "currency": "BRL", "rate": 5.3214 },
{ "fx_date": "2026-09-28", "currency": "COP", "rate": 3306.859716727782946 },
{ "fx_date": "2026-09-28", "currency": "USD", "rate": 1 }
]
}
```
Three rules hold for every response:
1. **Sorted** by `fx_date`, then `currency`.
2. **One value per currency per day.** When more than one source exists for a day, the tie-break happens inside Yuno and is not part of this contract.
3. **What does not exist is simply absent.** A day or a currency with no published rate is not in `rates`, and a range with nothing published returns `200` with an empty array — not an error. Treat an empty `rates` as "nothing published for what you asked", never as a failure.
**Parse `rate` with a decimal type.**
Rates carry up to 15 decimal places. `3306.859716727782946` read as a double becomes `3306.859716727783`, and the difference will show up in reconciliation. Use your language's decimal or big-number type, not a float: `BigDecimal` in Java, `decimal.Decimal` in Python, `shopspring/decimal` in Go, a decimal library in JavaScript rather than `JSON.parse` alone.
### Currency codes
Codes are mostly ISO 4217, but the published set also includes codes that are not fiat currencies, such as `BTC`, `XAU` (gold) and `XAG` (silver). A well-formed code that Yuno does not publish is not an error: it comes back as an empty `rates` array.
## Caching
A published day never changes, so a response for a past day can be cached indefinitely. Asking without dates is the only request whose answer moves, once per day.
## Errors
Errors return a `code` and a `messages` array. The message names the parameter at fault.
| HTTP | `code` | When |
| - | - | - |
| 400 | `INVALID_PARAMETERS` | `end_date` sent without `start_date`; a date that is not `YYYY-MM-DD` or does not exist; `end_date` earlier than `start_date`; `end_date` later than yesterday (UTC); a range over the limit; a `currency` that is not three letters. |
| 401 | `NOT_AUTHENTICATED` / `INVALID_CREDENTIALS` | Missing or invalid `PUBLIC-API-KEY` / `PRIVATE-SECRET-KEY` headers. |
| 403 | `PRODUCT_NOT_ENABLED` | "The FX Rates API is enabled per organization. Contact your Key Account Manager (KAM) to activate it." |
| 503 | `SERVICE_UNAVAILABLE` | The rate source is temporarily unreachable. Retry; the data is unchanged. |
## OpenAPI
````yaml openapi/fx-rates/get-fx-rates.json GET /fx-rates
openapi: 3.1.0
info:
title: Yuno FX Rates API
version: '1.0'
servers:
- url: https://api-sandbox.y.uno/v1
- url: https://api.y.uno/v1
- url: https://api.eu.y.uno/v1
security: []
paths:
/fx-rates:
get:
summary: Get FX rates
description: >-
Returns Yuno's official daily FX rate for one or every currency,
expressed as units of the currency per 1 USD. With no dates it returns
the latest available day.
operationId: getFxRates
parameters:
- in: header
name: PUBLIC-API-KEY
schema:
type: string
description: Your public API key.
- in: header
name: PRIVATE-SECRET-KEY
schema:
type: string
description: Your private secret key. Never expose it client-side.
- in: query
name: start_date
required: false
schema:
type: string
format: date
example: '2026-09-28'
description: >-
First day of the range, inclusive, as `YYYY-MM-DD`. Omit it to get
the latest available day.
- in: query
name: end_date
required: false
schema:
type: string
format: date
example: '2026-09-30'
description: >-
Last day of the range, inclusive, as `YYYY-MM-DD`. Only valid
together with `start_date`, defaults to it, and cannot be later than
yesterday (UTC).
- in: query
name: currency
required: false
schema:
type: string
minLength: 3
maxLength: 3
example: COP
description: >-
One 3-letter currency code. Omit it to get every currency published
for those days.
responses:
'200':
description: OK — the rates published for the requested days.
content:
application/json:
schema:
type: object
properties:
base_currency:
type: string
description: >-
Always `USD` in this version. Explicit so the reading is
unambiguous.
example: USD
rates:
type: array
items:
type: object
properties:
fx_date:
type: string
format: date
description: Day the rate is published for.
example: '2026-09-28'
currency:
type: string
description: >-
3-letter currency code. Mostly ISO 4217; the
published set also includes codes that are not fiat
currencies, such as `BTC`, `XAU` and `XAG`.
example: COP
rate:
type: number
description: >-
Units of this currency per 1 unit of
`base_currency`, with up to 15 decimal places. `USD`
is published with a rate of 1. Parse it with a
decimal type: a double silently rounds it.
example: 3306.859716727783
examples:
one_day_every_currency:
summary: One day, every currency
value:
base_currency: USD
rates:
- fx_date: '2026-09-28'
currency: BRL
rate: 5.3214
- fx_date: '2026-09-28'
currency: COP
rate: 3306.859716727783
- fx_date: '2026-09-28'
currency: USD
rate: 1
no_rate_published:
summary: A day with no published rate
value:
base_currency: USD
rates: []
'400':
description: >-
Bad request — `INVALID_PARAMETERS` (a query parameter is missing its
companion, malformed, or out of range).
content:
application/json:
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
examples:
end_date_without_start_date:
value:
code: INVALID_PARAMETERS
messages:
- >-
The query parameter 'end_date' can only be used together
with 'start_date'.
end_date_after_yesterday:
value:
code: INVALID_PARAMETERS
messages:
- >-
The query parameter 'end_date' must not be later than
yesterday (UTC).
range_over_the_limit:
value:
code: INVALID_PARAMETERS
messages:
- >-
The range between 'start_date' and 'end_date' must not
exceed 31 days when 'currency' is omitted.
'403':
description: >-
Forbidden — `PRODUCT_NOT_ENABLED` (the product is not enabled for
your organization).
content:
application/json:
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
examples:
product_not_enabled:
value:
code: PRODUCT_NOT_ENABLED
messages:
- >-
The FX Rates API is enabled per organization. Contact
your Key Account Manager (KAM) to activate it.
'503':
description: >-
Service unavailable — `SERVICE_UNAVAILABLE` (the rate source is
temporarily unreachable).
content:
application/json:
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
examples:
service_unavailable:
value:
code: SERVICE_UNAVAILABLE
messages:
- >-
The FX rates service is temporarily unavailable, please
retry.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.