Rates
Exchange rates API
GET /v1/rates returns the latest exchange rate for a given currency pair.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
baseCurrency | yes | Base currency, e.g. RUB |
quoteCurrency | yes | Quote currency, e.g. BYN |
amount | no | Amount to convert (default: 1) |
rateSourceId | no | Partner/source id. If no rate under that source exists, falls back to the generic rate and sets fallback: true. Omit to request the generic rate directly. |
Example
GET /v1/rates?baseCurrency=RUB"eCurrency=BYN{
"ok": true,
"baseCurrency": "RUB",
"quoteCurrency": "BYN",
"rate": 5.0,
"amount": 1,
"converted": 5.0,
"rateSource": null,
"fallback": false
}With rateSourceId=2 (e.g. VTB) where no VTB rate exists, the response falls back to generic:
{
"ok": true,
"baseCurrency": "RUB",
"quoteCurrency": "BYN",
"rate": 5.0,
"amount": 1,
"converted": 5.0,
"rateSource": null,
"fallback": true
}Symbols
GET /v1/symbols returns the list of supported currency pairs.
POST /v1/symbols adds a new currency pair. Requires bearer auth.
Body
| Field | Required | Description |
|---|---|---|
baseCurrency | yes | Base currency, 2–10 chars, e.g. RUB |
quoteCurrency | yes | Quote currency, 2–10 chars, e.g. BYN |
Currencies are uppercased and trimmed. baseCurrency must differ from quoteCurrency. Duplicate pairs return 409.
Example
POST /v1/symbols
Authorization: Bearer <token>
Content-Type: application/json
{ "baseCurrency": "RUB", "quoteCurrency": "BYN" }{
"ok": true,
"symbol": {
"id": 1,
"baseCurrency": "RUB",
"quoteCurrency": "BYN",
"createdAt": "2026-04-16T12:00:00.000Z"
}
}Rate Sources
A rate source represents a partner or channel that may have its own quoted rate for a pair (e.g. VTB, XFER). When a rate is submitted without a source, it's stored as the generic rate. GET /v1/rates with rateSourceId returns the partner rate if present, otherwise falls back to the generic rate (fallback: true).
GET /v1/rate-sources — list all sources, ordered by priority asc. Generic is implicit (not in the list).
POST /v1/rate-sources — create a source. Body:
| Field | Required | Description |
|---|---|---|
code | yes | Stable code, 1–32 chars, [A-Za-z0-9_-]+ |
name | yes | Display name, 1–64 chars |
priority | no | Integer ≥ 0, sort order (default 0) |
Duplicate code returns 409.
PATCH /v1/rate-sources/:id — update name and/or priority. code is immutable.
Example
POST /v1/rate-sources
Authorization: Bearer <token>
Content-Type: application/json
{ "code": "VTB", "name": "VTB Bank", "priority": 10 }{
"ok": true,
"rateSource": {
"id": 1,
"code": "VTB",
"name": "VTB Bank",
"priority": 10,
"createdAt": "2026-04-16T12:00:00.000Z"
}
}Posting a rate under a source
POST /v1/rates accepts an optional rateSourceId. Omit it to store the rate as generic.
POST /v1/rates
Authorization: Bearer <token>
Content-Type: application/json
{ "baseCurrency": "RUB", "quoteCurrency": "BYN", "rate": "5.0", "rateSourceId": 1 }