# Banka döviz kurları (SBX-BANKFX)

Türk bankalarının kendi sayfalarında gösterdiği döviz alış/satış kurları yan yana: makas, en ucuz alış ve en iyi satış, her kur değişimiyle geçmiş.

Sürüm: v1.0

## Kimlik doğrulama

API anahtarınızı her istekte Bearer token olarak ya da `apikey` sorgu parametresiyle gönderin:

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

Anahtar almak için https://servicebox.io/signup adresinden kaydolun ve panelden bir anahtar oluşturun. Bir ajan `POST https://api.servicebox.io/v1/accounts` ve `{"email": "...", "apis": ["bank-fx"]}` ile kendisi kaydolabilir: e-posta sahibi e-postadaki bağlantıyla onaylar, ajan dönen `poll_url` adresini yoklayarak kısa ömürlü bir anahtar alır.

## Temel URL

`https://api.servicebox.io`

## Uç noktalar

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

**Kredi:** ücretsiz (çağrı başına 0 kredi)

Parametre yok.

**Örnek**

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

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `bank` | query | string | evet | A bank id from /bank-fx/banks, e.g. isbank. |
| `currency` | query | string | evet | One ISO 4217 code, e.g. USD. |
| `start` | query | string | hayır | YYYY-MM-DD. |
| `end` | query | string | hayır | YYYY-MM-DD. Default: today. |

**Örnek**

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

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `bank` | query | string | hayır | A bank id from /bank-fx/banks, e.g. isbank. |
| `currencies` | query | string | hayır | Comma-separated ISO 4217 codes, e.g. USD,EUR. |

**Örnek**

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

**Kredi:** çağrı başına 1

**Parametreler**

| Ad | Yer | Tür | Zorunlu | Açıklama |
|---|---|---|---|---|
| `currency` | query | string | evet | One ISO 4217 code, e.g. USD. |

**Örnek**

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

## Hatalar

Hatalar, makinece okunabilir bir `type` taşıyan RFC 9457 `application/problem+json` gövdeleridir.

- `401` — anahtar eksik, bilinmiyor, süresi dolmuş ya da iptal edilmiş.
- `402` — kredi yetersiz: gövde `credits_required` ve `upgrade_url` (https://servicebox.io/pricing) taşır.
- `403` — anahtarın bu API'yi çağırma izni yok.
- `429` — hız sınırı: `retry_after` saniye bekleyin (`Retry-After` başlığıyla da gönderilir); `upgrade_url` daha büyük bir plana yönlendirir.

## Bağlantılar

- OpenAPI belgesi: https://api.servicebox.io/v1/bank-fx/openapi.json
- Fiyatlandırma: https://servicebox.io/pricing?api=SBX-BANKFX
- API sayfası: https://servicebox.io/apis/bank-fx