# Commodity futures positions (SBX-EMTIA)

CFTC Commitments of Traders: weekly positions and open interest in 30 futures markets including wheat, cotton, copper, gold and crude oil, since 2006.

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

**List futures markets**

The 30 commodity futures markets covered — grains, oilseeds, softs, livestock, metals, energy and lumber on CBOT, CME, COMEX, NYMEX, ICE Futures U.S. and MIAX — with the contract size and the reports held. Free.

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

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `category` | query | string (`grains`, `oilseeds`, `softs`, `livestock`, `base-metals`, `precious-metals`, `energy`, `forest-products`) | no | Only this category. |

**Example**

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

### GET /v1/commodity-futures/positions

**Latest positions**

Each market's latest Commitments of Traders report (or the one on or before `date`): open interest and the long, short and spread contracts of producers/merchants, swap dealers, managed money, other reportables and non-reportables, with each group's net position and the change since the week before. Positions are as of Tuesday and released the following Friday at 15:30 US Eastern.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `markets` | query | string | no | Comma-separated market codes, e.g. wheat-srw,cotton,copper. Default: every market. |
| `category` | query | string (`grains`, `oilseeds`, `softs`, `livestock`, `base-metals`, `precious-metals`, `energy`, `forest-products`) | no | Only this category. |
| `date` | query | string | no | YYYY-MM-DD, since 2006-06-13. Default: the latest report. |

**Example**

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

### GET /v1/commodity-futures/positions/{market}

**One market over time**

One market's weekly reports between `start` and `end` (default: the last 52 weeks; at most about 5 years), since 2006-06-13.

**Credits:** 1 per call

**Parameters**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `market` | path | string | yes | A market code from /commodity-futures/markets, e.g. cotton. |
| `start` | query | string | no | YYYY-MM-DD. |
| `end` | query | string | no | YYYY-MM-DD. Default: today. |

**Example**

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