# Turkish funds (SBX-FON)

Every Turkish investment, hedge, pension (BES/OKS) and exchange-traded fund on TEFAS: daily price, size, investors, returns, fees, risk and portfolio allocation.

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/funds/...?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": ["funds"]}`: 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/funds

**List funds**

Every Turkish investment fund, pension fund and ETF TEFAS lists, with the latest price, size, investors, returns, fees and risk. Filter by `type`, `category`, `founder`, `codes`, a text search `q` (code or title, Turkish letters optional), `tefas` and `riskLevel`; sort by size, investors, a return period, fee, code or name. Active funds only unless `status=all`. Updated every morning from TEFAS. Use for questions about Turkish mutual funds, hedge funds, private pension (BES) funds or ETFs: finding a fund by name or company, the best performers over a period, the largest funds, or the lowest fees.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | query | string (`investment`, `pension`, `exchange-traded`) | no | Only this type. |
| `category` | query | string | no | A category id from /funds/categories, e.g. para-piyasasi-semsiye-fonu. |
| `founder` | query | string | no | A company code from /funds/founders, e.g. ISP. |
| `codes` | query | string | no | Comma-separated fund codes (up to 100), e.g. AAL,TTE. |
| `q` | query | string | no | Words to find at the start of words of the code or the Turkish or English title; Turkish letters optional: `altin` finds ALTIN and Altın, `tekno` TEKNOLOJİ. |
| `tefas` | query | string (`true`, `false`) | no | `true`: only funds traded on the TEFAS platform; `false`: only those that are not. |
| `riskLevel` | query | integer | no | Only this risk value, 1–7. |
| `status` | query | string (`active`, `all`) | no | `active` (default) or `all` (also funds no longer priced). |
| `sort` | query | string (`aum`, `investors`, `return-1m`, `return-3m`, `return-6m`, `return-ytd`, `return-1y`, `return-3y`, `return-5y`, `fee`, `code`, `name`) | no | Sort key. Default `aum` (fund size). |
| `order` | query | string (`asc`, `desc`) | no | `desc` or `asc`; default `asc` for fee, code and name, else `desc`. Funds without the sort value come last. |
| `limit` | query | integer | no | Items per page, 1–200. |
| `cursor` | query | string | no | The `next_cursor` of the previous page, with the same filters. |

**Example**

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

### GET /v1/funds/categories

**List fund categories**

The categories TEFAS uses per fund type — umbrella fund types for investment funds, fund kinds for pension funds and ETFs — in English and Turkish, with how many active funds each has. Free.

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

No parameters.

**Example**

```bash
curl "https://api.servicebox.io/v1/funds/categories" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/funds/founders

**List fund companies**

Portfolio management and pension companies with their number of active funds and total fund value, largest first. Free.

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

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `type` | query | string (`investment`, `pension`, `exchange-traded`) | no | Only this type. |

**Example**

```bash
curl "https://api.servicebox.io/v1/funds/founders" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/funds/{code}

**Get a fund**

One fund: the latest price, size, investors, returns, fees and risk, and its portfolio allocation by asset class (stocks, government bonds, reverse repo, deposits, precious metals, foreign securities…). Use when the user names a fund code (e.g. TTE, AAL) or asks what a fund invests in.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | A TEFAS fund code, e.g. AAL. |

**Example**

```bash
curl "https://api.servicebox.io/v1/funds/<code>" \
  -H "Authorization: Bearer $SBX_API_KEY"
```

### GET /v1/funds/{code}/prices

**Daily price history**

One fund's daily price, shares, investors and size between `start` and `end` (inclusive; default the 30 days up to its latest price; at most 1,830 days per request), oldest first, with `meta.changePercent` over the range. History since October 2021. Use for a fund's price history or its change over a period.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | A TEFAS fund code, e.g. AAL. |
| `start` | query | string | no | YYYY-MM-DD. |
| `end` | query | string | no | YYYY-MM-DD. Default: the fund's latest price date. |

**Example**

```bash
curl "https://api.servicebox.io/v1/funds/<code>/prices" \
  -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/funds/openapi.json
- Pricing: https://servicebox.io/en/pricing?api=SBX-FON
- API page: https://servicebox.io/en/apis/funds