# Current Account Balance API
> Whether each economy earns more from the rest of the world than it spends — the current-account balance, live from the OECD's official balance-of-payments statistics, no key. The current account is the single most important external-balance number in macro: it nets a country's trade in goods and services, its cross-border investment income, and its transfers into one figure. A surplus means the economy is a net lender to the world and is accumulating foreign claims; a deficit means it is a net borrower, financing its spending with foreign capital. Persistent current-account positions are one of the deepest drivers of exchange rates — surplus currencies (the yen, the euro-area core, the Nordics) tend to be structurally supported, while large-deficit currencies depend on continued capital inflows and are vulnerable when risk appetite turns. The board endpoint ranks economies by their current-account balance as a share of GDP — the size-neutral cross-country screen — from biggest surpluses to biggest deficits. The goods endpoint ranks by the merchandise (goods) trade balance as a share of GDP, separating the trade story from services and income. The country endpoint gives one economy's full external decomposition: the headline balance as a share of GDP, the goods / services / primary-income / secondary-income balances in US dollars (which sum exactly to the current account) and as shares of GDP, the six-quarter trend, and a plain-language read of whether the position is improving or deteriorating and what drives it. Each reading carries its own quarter and discontinued series are filtered out. This is the external-balance / balance-of-payments cut — distinct from trade growth (real export and import growth rates, the flow of volumes, not the net balance), and from the inflation, labour-cost and confidence feeds. The headline is percent of GDP; the decomposition is in billions of US dollars per quarter and percent of GDP; figures are quarterly, seasonally adjusted.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/currentaccount-api/..."
```

## Pricing
- **Free** (Free) — 800 calls/Mo, 2 req/s
- **Starter** ($15/Mo) — 16,200 calls/Mo, 6 req/s
- **Pro** ($43/Mo) — 84,000 calls/Mo, 16 req/s
- **Mega** ($96/Mo) — 490,000 calls/Mo, 40 req/s

## Endpoints

### Country

#### `GET /v1/country` — One economy's full external decomposition + trend

**Parameters:**
- `country` (query, required, string) — ISO-3 code or country name Example: `USA`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currentaccount-api/v1/country?country=USA"
```

**Response:**
```json
{
    "data": {
        "code": "USA",
        "name": "United States",
        "note": "One economy's external balance: the headline current account as a share of GDP, decomposed into the goods, services, primary-income (cross-border investment income) and secondary-income (transfers) balances — in billions of US dollars per quarter (which sum exactly to the current account) and as shares of GDP. The six-quarter trend shows whether the position is widening or narrowing. Quarterly, seasonally adjusted, cached a few hours.",
        "read": "Deficit of 2.43% of GDP, improving (balance up 1.76 pts year-on-year) — a net borrower from the world. Composition: goods -3.08%, services +1.04%, primary income +0.3%, secondary income -0.7% (of GDP). The balances sum to the current account.",
        "trend": [
            {
                "period": "2024-Q3",
                "balance_pct": -4.42
            },
            {
                "period": "2024-Q4",
                "balance_pct": -4.18
            },
            {
                "period": "2025-Q1",
                "balance_pct": -5.84
            },
            {
                "period": "2025-Q2",
                "balance_pct": -3.25
            },
            {
                "period": "2025-Q3",
                "balance_pct": -3.08
            },
            {
                "period": "2025-Q4",
                "balance_pct": -2.43
            }
        ],
        "period": "2025-Q4",
        "source": "OECD bala
…(truncated, see openapi.json for full schema)
```

### Board

#### `GET /v1/board` — Economies ranked by current-account balance (% of GDP)

**Parameters:**
- `countries_only` (query, optional, string) — true to drop aggregates (euro area, OECD) Example: `true`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currentaccount-api/v1/board?countries_only=true"
```

**Response:**
```json
{
    "data": {
        "note": "Economies ranked by their current-account balance as a share of GDP — the size-neutral external-balance screen — from biggest surpluses to biggest deficits. A surplus means the economy is a net lender to the world; a deficit means it is a net borrower financing spending with foreign capital, the deepest structural driver of a currency. goods_pct and services_pct show the trade split. change_yoy_pts is versus four quarters ago. Each row carries its own quarter; discontinued series excluded. Pass countries_only=true to drop aggregates. Quarterly, seasonally adjusted, cached a few hours.",
        "board": [
            {
                "code": "IRL",
                "name": "Ireland",
                "period": "2026-Q1",
                "goods_pct": 17.43,
                "balance_pct": 12.9,
                "is_aggregate": false,
                "services_pct": 6.9,
                "change_yoy_pts": 8.61
            },
            {
                "code": "NOR",
                "name": "Norway",
                "period": "2025-Q4",
                "goods_pct": 11.68,
                "balance_pct": 12.38,
                "is_aggregate": false,
                "services_pct": -2.17,
                "change_yoy_pts": -0.44
            },
            {
                "code": "DNK",
                "name": "Denmark",
                "period": "2026-Q1",
                "goods_pct": 10.61,
                "balance_pct": 12.32,
                
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/goods` — Economies ranked by goods (merchandise trade) balance (% of GDP)

**Parameters:**
- `countries_only` (query, optional, string) — true to drop aggregates Example: `true`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currentaccount-api/v1/goods?countries_only=true"
```

**Response:**
```json
{
    "data": {
        "note": "Economies ranked by their merchandise (goods) trade balance as a share of GDP — the pure trade-in-goods story, separated from services and investment income. A goods surplus (Germany, Korea, the oil exporters) versus a goods deficit (the US, the UK) is the visible half of the external balance; the gap between goods_pct and the current_account_pct is what services and income add back. Shares of GDP are derived from the headline's implied GDP (exact). Quarterly, seasonally adjusted, cached a few hours.",
        "board": [
            {
                "code": "IRL",
                "name": "Ireland",
                "period": "2026-Q1",
                "goods_pct": 17.43,
                "goods_usd_bn": 28.84,
                "is_aggregate": false,
                "services_pct": 6.9,
                "current_account_pct": 12.9
            },
            {
                "code": "NOR",
                "name": "Norway",
                "period": "2025-Q4",
                "goods_pct": 11.68,
                "goods_usd_bn": 15.62,
                "is_aggregate": false,
                "services_pct": -2.17,
                "current_account_pct": 12.38
            },
            {
                "code": "DNK",
                "name": "Denmark",
                "period": "2026-Q1",
                "goods_pct": 10.61,
                "goods_usd_bn": 12.87,
                "is_aggregate": false,
                "services_pct": 0.05,
             
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/currentaccount-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "board and goods take countries_only (true to drop aggregates such as the euro area). country takes country (ISO-3 code or name, required). meta takes no parameters. The headline balance is percent of GDP; the decomposition is in billions of US dollars per quarter (summing exactly to the current account) and percent of GDP (derived from the headline's implied GDP). change_yoy_pts is versus four quarters ago. Each row carries its own quarter; discontinued series are filtered out. Quarterly data; a multi-hour protective cache fronts the OECD upstream.",
        "source": "OECD balance-of-payments (DF_BOP, current account vs rest-of-world, balances) via OECD SDMX API, % of GDP and US dollars, quarterly, seasonally adjusted, live, keyless",
        "service": "currentaccount-api",
        "economies": 49,
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/board": "Economies ranked by current-account balance as a share of GDP (countries_only optional).",
            "GET /v1/goods": "Economies ranked by the goods (merchandise trade) balance as a share of GDP.",
            "GET /v1/country": "One economy's full external decomposition + six-quarter trend (country=USA)."
        },
        "description": "Current account balance by country — whether each economy is a net lender or borrower to the world, live from the OECD's balance-of-payments statistics (no key). It serves the headline current-account balance 
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/currentaccount-api
OpenAPI spec: https://www.oanor.com/api/currentaccount-api/openapi.json