---
title: "Merchandise trade API Reference | Narwhal API"
description: "Retrieve exports, imports, and the exact merchandise-trade balance for one period. Services are excluded. Parameters, examples, errors, freshness, and coverage."
url: "https://narwhalapi.com/docs/api/economics/trade"
---

# Merchandise trade API

Retrieve exports, imports, and the exact merchandise-trade balance for one period. Services are excluded.

`economics_get_trade` is available through REST and the `economics_get_trade` MCP tool. Both return the same data shape and use the same credit.

## Endpoint and request

REST endpoint

```
GET /v1/economics/{country}/trade
```

Example request

```
curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/trade?period=2026-06" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

MCP uses tool `economics_get_trade` with the corresponding arguments below.

## Parameters

The accepted period format for this operation is `YYYY or YYYY-MM`.

| Name | Required | Type | Meaning |
| --- | --- | --- | --- |
| `country` | Yes | path · ISO alpha-3 | One supported uppercase country code; see this operation’s coverage list. |
| `period` | No | query · YYYY or YYYY-MM | Omit it for the latest accepted complete release, or pass one exact period. |
| `version_id` | No | query · UUID | Optional immutable publication version. Use `resource_version` from a `dataset.published` or `dataset.revised` event; omit to read the current admitted indicator. |

## Response

Example response

```
{
  "country": "USA",
  "period": "2026-06",
  "exports": "208151310516",
  "imports": "317408003903",
  "balance": "-109256693387",
  "currency": "USD",
  "not_seasonally_adjusted": true,
  "released_on": "2026-11-04"
}
```

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `country` | string | Yes | The requested uppercase ISO alpha-3 country code. |
| `period` | string | Yes | The official observation period returned. |
| `exports` | non-negative decimal string | Yes | Total merchandise exports. |
| `imports` | non-negative decimal string | Yes | Total merchandise imports. |
| `balance` | decimal string | Yes | Exact exports minus imports; it may be negative. |
| `currency` | ISO 4217 string | Yes | The currency for all three monetary values. |
| `seasonal_adjustment` | string or null | Yes | Whether the figure is seasonally adjusted, as the publisher states it: `seasonally_adjusted`, `not_seasonally_adjusted`, `calendar_adjusted` or `trend`. `null` means the publisher does not say. Never read `null` as adjusted. |
| `not_seasonally_adjusted` | `true` | No | Present, as true, only when the figures are the original series, not seasonally adjusted. Absent means the figures are seasonally adjusted, or yearly World Bank figures, which have no seasonal adjustment. |
| `released_on` | date | Yes | The official publication date, not Narwhal's retrieval time. |
| `source` | object | No | Who published the figure: the statistics office or central bank, for example `{"publisher": "Office for National Statistics"}`. Where the data reaches us through another body, `distributor` names that body too. If we cannot tell who published a figure, `source` is left out. |

## Errors and credits

- `400 invalid_query` — the country, period, or filter format is invalid.
- `401 invalid_api_key` — the Bearer key is missing or rejected.
- `404 series_not_found` — no approved observation matches the request.
- `429 rate_limit_exceeded` — the network or account short-window limit was reached; retry after `Retry-After`.
- `402 insufficient_credits` — your balance does not cover the call.
- `503 economics_unavailable` — Narwhal cannot safely serve an accepted publication.

Only a successful data response costs credit. See [all errors, headers, and retry rules](https://narwhalapi.com/docs/errors.md).

## Freshness

Omitting `period` returns Narwhal's latest stored accepted release. The API call reads Narwhal's database; it does not call the official publisher live.

`released_on` is the official publication date.

Read [how source checks, validation, stored releases, and failed checks work](https://narwhalapi.com/docs/freshness.md).

## Current public-beta coverage

35 Countries

`AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, SAU, SGP, SVN, SWE, USA`

Merchandise totals follow the country list below. Services trade is not included. For Bulgaria, Cyprus, Greece, Hungary, Malta, Romania and Slovakia the totals are Eurostat's, and for Costa Rica, Iceland, South Africa, Switzerland and Turkey the OECD's. They follow that publisher's method, so they can differ from the national office's headline. These twelve answer the newest month; their history is yearly.

### Annual World Bank history

154 Countries

`ABW, AFG, AGO, ALB, AND, ARM, ATG, AZE, BDI, BEN, BFA, BGD, BGR, BHR, BHS, BIH, BLR, BLZ, BMU, BOL, BRB, BRN, BTN, BWA, CAF, CHE, CIV, CMR, COD, COG, COM, CPV, CRI, CUW, CYM, CYP, DJI, DMA, DOM, DZA, ECU, EGY, ERI, ETH, FJI, FRO, FSM, GAB, GEO, GHA, GIN, GMB, GNB, GNQ, GRC, GRD, GTM, GUY, HKG, HND, HTI, HUN, IRN, IRQ, ISL, JAM, JOR, KAZ, KEN, KGZ, KHM, KIR, KNA, KWT, LAO, LBN, LBR, LBY, LCA, LKA, LSO, MAC, MAR, MDA, MDG, MDV, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MOZ, MRT, MUS, MWI, NAM, NCL, NER, NGA, NIC, NPL, NRU, OMN, PAN, PER, PLW, PNG, PRY, PSE, PYF, ROU, RUS, RWA, SDN, SEN, SLB, SLE, SLV, SMR, SRB, SSD, STP, SUR, SVK, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, TJK, TLS, TON, TTO, TUN, TUR, TUV, TZA, UGA, UKR, URY, UZB, VCT, VEN, VNM, VUT, WSM, YEM, ZAF, ZMB, ZWE`

These countries have no latest-value route. A request to this route returns `404 series_not_found`; read the history route instead.

Indonesia and regional Economics routes are not public. Daily FX is available through the [FX API](https://narwhalapi.com/api/fx.md).

Return to [all Economics operations](https://narwhalapi.com/docs/api/economics.md).

## Start with a free key

Free $10 credits every month, no card.Free $10 credits a month, no card.

[Get a free API key](https://narwhalapi.com/signup)

Was this page helpful?
