# Gold & commodities (SBX-GOLD)

Daily intrinsic value of gram, çeyrek, Cumhuriyet and ounce gold (TRY, USD, EUR; since 2013); daily spot prices of Brent, WTI, natural gas and fuels; monthly prices of 67 commodities.

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

**List commodities**

Every commodity series: daily energy spot prices (EIA) and monthly prices of metals, energy, agriculture, fertilizers and raw materials (World Bank), with the span held. Free.

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

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `category` | query | string (`energy`, `precious-metals`, `base-metals`, `agriculture`, `fertilizers`, `raw-materials`) | no | Only this category. |

**Example**

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

### GET /v1/gold/commodity-prices

**Latest commodity prices**

Each series' latest price and the one before it, with the change. EIA's daily prices are released weekly (Wednesdays), the World Bank's monthly averages in the first days of each month.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `codes` | query | string | no | Comma-separated codes from /gold/commodities, e.g. brent,wti,gold. Default: every series. |
| `category` | query | string (`energy`, `precious-metals`, `base-metals`, `agriculture`, `fertilizers`, `raw-materials`) | no | Only this category. |

**Example**

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

### GET /v1/gold/commodity-prices/{code}

**One commodity over time**

One series between `start` and `end`. Daily series: at most 366 days (default: the last 30). Monthly series: YYYY-MM or YYYY-MM-DD, at most 600 months (default: the last 24).

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `code` | path | string | yes | A code from /gold/commodities, e.g. brent. |
| `start` | query | string | no | YYYY-MM-DD (monthly series: also YYYY-MM). |
| `end` | query | string | no | YYYY-MM-DD (monthly series: also YYYY-MM). Default: today. |

**Example**

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

### GET /v1/gold/prices

**Gold prices on a date**

The intrinsic value of gram gold (24, 22, 18 and 14 karat), the troy ounce and the Turkish coins (çeyrek, yarım, tam, ikibuçuk, beşli, Cumhuriyet, Ata beşli) on `date` (default: the latest price), from the price of 1 g of fine gold calculated by Narodowy Bank Polski each Polish business day. USD and EUR use NBP's mid rates of that day; TRY goes through USD at TCMB's forex midpoint of the latest bulletin on or before that day (`meta.rates`). These are melt values, without workmanship or a dealer's spread.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `currency` | query | string (`TRY`, `USD`, `EUR`) | no | `TRY` (default), `USD` or `EUR`. |
| `date` | query | string | no | YYYY-MM-DD, since 2013-01-02. A day without a price answers the latest one before it (`meta.date`). |

**Example**

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

### GET /v1/gold/prices/{product}

**One product over time**

One product's intrinsic value on every NBP business day between `start` and `end` (default: the last 30 days; at most 366 days), since 2013-01-02.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `product` | path | string | yes | A product id from /gold/products, e.g. gram-24k or ceyrek. |
| `currency` | query | string (`TRY`, `USD`, `EUR`) | no | `TRY` (default), `USD` or `EUR`. |
| `start` | query | string | no | YYYY-MM-DD. |
| `end` | query | string | no | YYYY-MM-DD. Default: today. |

**Example**

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

### GET /v1/gold/products

**List gold products**

Gram gold by karat, the troy ounce and the Turkish coins, with their weight and fine-gold content. Free.

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

No parameters.

**Example**

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