> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Trade Flows

> Bilateral commodity trade data from UN Comtrade, mirror data discrepancy detection, entity resolution, and sanctions cross-referencing.

Bilateral commodity trade data from UN Comtrade, mirror data discrepancy detection, entity resolution, and sanctions cross-referencing.

## `GET` `/api/v1/trade-flows`

<Note>Requires API key.</Note>

Bilateral trade flow data. Use ?view param for different analyses.

**Parameters**

| Name        | Type   | Required | Description                                              |
| ----------- | ------ | -------- | -------------------------------------------------------- |
| `view`      | string |          | 'flows' (default) \| 'mirror' \| 'sanctions' \| 'entity' |
| `exporter`  | string |          | Exporter country name filter                             |
| `importer`  | string |          | Importer country name filter                             |
| `commodity` | string |          | Commodity name filter (e.g. Wheat, Soybeans)             |
| `period`    | string |          | Year filter (e.g. '2024')                                |
| `limit`     | number |          | Max results (default 50)                                 |

**Response**

```json theme={null}
{ "flows": [...] } or { "discrepancies": [...] } or { "matches": [...] } or { "entities": [...] }
```

**Example**

```bash theme={null}
curl -X GET -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/trade-flows?view=VALUE&exporter=VALUE
```

## `GET` `/api/v1/trade-flows?view=mirror`

Mirror data discrepancies: exporter-reported vs importer-reported volumes for the same commodity/country pair. Large discrepancies signal trade re-routing or misclassification.

**Response**

```json theme={null}
{ "discrepancies": [{ "exporter_name", "importer_name", "commodity_name", "exported_mt", "imported_mt", "discrepancy_pct", "status" }] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/trade-flows?view=mirror
```

## `GET` `/api/v1/trade-flows?view=sanctions`

Vessels matched against OFAC sanctions list via IMO, MMSI, or name-based entity resolution.

**Response**

```json theme={null}
{ "matches": [{ "imo_number", "vessel_name", "sanctioned_entity", "list_source", "match_type" }], "match_types": { "direct_imo", "mmsi", "name" } }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/trade-flows?view=sanctions
```

## `GET` `/api/v1/trade-flows?view=entity`

Supply chain entity graph: vessels linked to owners, ports, sanctions, P\&I coverage, and dark fleet history.

**Parameters**

| Name  | Type   | Required | Description          |
| ----- | ------ | -------- | -------------------- |
| `imo` | string |          | Filter by IMO number |

**Response**

```json theme={null}
{ "entities": [{ "imo_number", "vessel_name", "port_name", "is_sanctioned", "dark_event_count", "risk_score" }] }
```

**Example**

```bash theme={null}
curl -X GET \
  https://axiomoverwatch.io/api/v1/trade-flows?view=entity?imo=VALUE
```