# Bank exchange rates (SBX-BANKFX)

The buying and selling rates Turkish banks show on their own pages, side by side: spreads, the cheapest bank to buy from and the best to sell to, and every rate change.

Version: v1.0

## Authentication

Send your API key on every request, either as a Bearer token or as the `apikey` query parameter:

```
Authorization: Bearer <YOUR_API_KEY>
https://api.servicebox.io/v1/bank-fx/...?apikey=<YOUR_API_KEY>
```

Get a key: sign up at https://servicebox.io/en/signup and create one on the dashboard. An agent can sign up itself with `POST https://api.servicebox.io/v1/accounts` and `{"email": "...", "apis": ["bank-fx"]}`: the owner of the mailbox approves by email and the agent collects a short-lived key by polling the returned `poll_url`.

## Base URL

`https://api.servicebox.io`

## Endpoints

### GET /v1/bank-fx/banks

**List banks**

The banks whose rates are read, with the page each is read from, the channel, how many currencies it shows and when it was last read. Free.

**Credits:** free (0 credits per call)

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/bank-fx/banks" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/bank-fx/history

**Rate changes over time**

Every change of one bank's rate for one currency between `start` and `end` (UTC days, inclusive; default the last 7 days; at most 31). The first item is the rate that held at `start`. Recorded since 2026-09-29. Use for how one bank's rate for a currency changed over recent days.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `bank` | query | string | yes | A bank id from /bank-fx/banks, e.g. isbank. |
| `currency` | query | string | yes | One ISO 4217 code, e.g. USD. |
| `start` | query | string | no | YYYY-MM-DD. |
| `end` | query | string | no | YYYY-MM-DD. Default: today. |

**Example**

```bash
curl "https://api.servicebox.io/v1/bank-fx/history?bank=<bank>&currency=<currency>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/bank-fx/rates

**Latest bank rates**

Each bank's latest buying and selling rate per currency, in TRY, with the spread. Rates are read from the banks' public pages every 5 minutes on weekdays (hourly otherwise); `observedAt` is the last read and `changedAt` when the rate last moved. Filter by `bank` and `currencies`. Use when the user asks what Turkish banks charge or pay for USD, EUR, GBP or another currency, or for one bank's rates. `buying` is what the bank pays you for one unit (you sell); `selling` is what you pay the bank (you buy). For the official TCMB rate use the currency (FX) tools instead.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `bank` | query | string | no | A bank id from /bank-fx/banks, e.g. isbank. |
| `currencies` | query | string | no | Comma-separated ISO 4217 codes, e.g. USD,EUR. |

**Example**

```bash
curl "https://api.servicebox.io/v1/bank-fx/rates" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/bank-fx/rates/compare

**Compare banks**

One currency at every bank, cheapest to buy first (lowest selling rate), with `meta.cheapestToBuy` (lowest selling) and `meta.bestToSell` (highest buying). Banks with stale rates are listed but not picked. Use when the user asks which bank is cheapest to buy a foreign currency from (lowest selling rate) or best to sell it to (highest buying rate): one call compares every bank.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `currency` | query | string | yes | One ISO 4217 code, e.g. USD. |

**Example**

```bash
curl "https://api.servicebox.io/v1/bank-fx/rates/compare?currency=<currency>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

## Errors

Errors are RFC 9457 `application/problem+json` bodies with a machine-readable `type`.

- `401` — the key is missing, unknown, expired or revoked.
- `402` — not enough credits: the body carries `credits_required` and `upgrade_url` (https://servicebox.io/en/pricing).
- `403` — the key is not allowed to call this API.
- `429` — rate limited: wait `retry_after` seconds (also sent as the `Retry-After` header); `upgrade_url` points to a larger plan.

## Links

- OpenAPI document: https://api.servicebox.io/v1/bank-fx/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-BANKFX
- API page: https://servicebox.io/en/apis/bank-fx