# Net International Investment Position API
> The stock of external wealth — how much each economy owns abroad versus how much the rest of the world owns of it, live from the OECD's official balance-of-payments statistics, no key. Where the current account is the yearly flow of external lending or borrowing, the net international investment position (Net IIP) is the accumulated stock those flows pile up into: a country running persistent surpluses builds a large positive Net IIP and becomes a net creditor to the world (Norway, Japan, Germany, Switzerland), while persistent deficits build a large negative one — a net debtor, like the United States. The Net IIP is one of the deepest gauges of external sustainability and a structural anchor for a currency: a big positive position earns net income on foreign assets and is a buffer in a crisis, while a large negative one leaves a currency exposed to the willingness of foreigners to keep funding it. The board endpoint ranks economies by their Net IIP as a share of GDP — the size-neutral cross-country screen — from biggest net creditors to biggest net debtors. The gross endpoint ranks by gross external assets as a share of GDP, a measure of financial openness and international integration where small financial hubs tower with foreign assets worth multiples of GDP. The country endpoint gives one economy's full external balance sheet: the Net IIP in dollars and as a share of GDP, its gross foreign assets and liabilities, and the net position broken down by function — direct investment, portfolio investment, other investment and reserve assets, which sum to the net position — with a plain-language read. Each reading carries its own quarter and discontinued series are filtered out. This is the external-stock / net-foreign-wealth cut — the companion to, and distinct from, the current-account balance (the yearly flow, not the accumulated stock), trade growth, and the gross-government-debt and debt-service feeds (public-sector domestic debt, not the whole economy's external position). Positions are in billions of US dollars and percent of GDP; figures are quarterly end-of-period stocks.

## 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/netiip-api/..."
```

## Pricing
- **Free** (Free) — 680 calls/Mo, 2 req/s
- **Starter** ($14/Mo) — 14,200 calls/Mo, 6 req/s
- **Pro** ($41/Mo) — 76,000 calls/Mo, 16 req/s
- **Mega** ($90/Mo) — 445,000 calls/Mo, 40 req/s

## Endpoints

### Country

#### `GET /v1/country` — One economy's full external balance sheet + net-by-function

**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/netiip-api/v1/country?country=USA"
```

**Response:**
```json
{
    "data": {
        "code": "USA",
        "name": "United States",
        "note": "One economy's external balance sheet: the net international investment position (in US dollars and as a share of GDP), its gross foreign assets and liabilities, and the net position broken down by function — direct investment, portfolio investment, other investment and reserve assets, which sum to the net position. A net creditor owns more abroad than the world owns of it; a net debtor the reverse. End-of-period stock; shares of GDP derived from implied GDP (same data family). Quarterly, cached a few hours.",
        "read": "Net debtor worth -87.6% of GDP — the world owns more of it than it owns abroad, a structural funding dependency. Gross foreign assets 136.7% vs liabilities 224.3% of GDP. By function: direct investment -20.3%, portfolio -60.6%, other -11%, reserves +4.4% (these sum to the net position).",
        "period": "2025-Q4",
        "source": "OECD balance-of-payments statistics (SDMX), DF_IIP",
        "net_usd_bn": -27537.02,
        "net_pct_gdp": -87.6,
        "gross_assets": {
            "usd_bn": 42957.22,
            "pct_gdp": 136.7
        },
        "is_aggregate": false,
        "gross_liabilities": {
            "usd_bn": 70494.24,
            "pct_gdp": 224.3
        },
        "net_by_function_usd_bn": {
            "reserve_assets": 1385.21,
            "other_investment": -3471.34,
            "direct_investment": -6393.85,
            "portfolio_invest
…(truncated, see openapi.json for full schema)
```

### Board

#### `GET /v1/board` — Economies ranked by net IIP (% 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/netiip-api/v1/board?countries_only=true"
```

**Response:**
```json
{
    "data": {
        "note": "Economies ranked by their net international investment position as a share of GDP — from biggest net creditors (positive: they own more abroad than the world owns of them) to biggest net debtors (negative). The Net IIP is the accumulated stock that current-account surpluses and deficits pile up into, and one of the deepest gauges of external sustainability: a large positive position is a structural buffer for a currency, a large negative one a vulnerability. Shares of GDP are derived from each economy's implied GDP (current account, same OECD data family). Pass countries_only=true to drop aggregates. Quarterly end-of-period stocks, cached a few hours.",
        "board": [
            {
                "code": "NOR",
                "name": "Norway",
                "period": "2025-Q4",
                "net_usd_bn": 2107.1,
                "net_pct_gdp": 393.8,
                "is_aggregate": false
            },
            {
                "code": "RUS",
                "name": "Russia",
                "period": "2025-Q4",
                "net_usd_bn": 1113.04,
                "net_pct_gdp": 301.6,
                "is_aggregate": false
            },
            {
                "code": "CHE",
                "name": "Switzerland",
                "period": "2025-Q4",
                "net_usd_bn": 1208.5,
                "net_pct_gdp": 111.8,
                "is_aggregate": false
            },
            {
                "code": "DNK"
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/gross` — Economies ranked by gross external assets (% 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/netiip-api/v1/gross?countries_only=true"
```

**Response:**
```json
{
    "data": {
        "note": "Economies ranked by their gross external assets as a share of GDP — how much the economy owns abroad, regardless of what it owes. This is a measure of financial openness and international integration: small financial hubs and large creditor economies tower here with foreign assets worth multiples of their GDP, while large but less open economies sit lower. A high gross position with a small net one means an economy is deeply intermediated (big assets and big liabilities). Shares of GDP derived from implied GDP. Quarterly stocks, cached a few hours.",
        "board": [
            {
                "code": "LUX",
                "name": "Luxembourg",
                "period": "2025-Q4",
                "net_pct_gdp": 27,
                "is_aggregate": false,
                "assets_usd_bn": 15710.54,
                "assets_pct_gdp": 14563.5,
                "liabilities_pct_gdp": 14536.5
            },
            {
                "code": "IRL",
                "name": "Ireland",
                "period": "2025-Q4",
                "net_pct_gdp": -53.4,
                "is_aggregate": false,
                "assets_usd_bn": 11778.68,
                "assets_pct_gdp": 1779.5,
                "liabilities_pct_gdp": 1832.9
            },
            {
                "code": "NLD",
                "name": "Netherlands",
                "period": "2025-Q4",
                "net_pct_gdp": 44.7,
                "is_aggregate": false,
          
…(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/netiip-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "board ranks by Net IIP % of GDP (net creditor to net debtor); gross ranks by gross external assets % of GDP (financial openness). Both take countries_only (true to drop aggregates). country takes country (ISO-3 code or name, required). meta takes no parameters. Positions are end-of-period stocks in billions of US dollars and percent of GDP (derived from each economy's implied GDP from the same OECD data family). 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_IIP, financial-account positions vs rest-of-world, closing balance sheet) via OECD SDMX API, US dollars + % of GDP, quarterly end-of-period stocks, live, keyless",
        "service": "netiip-api",
        "economies": 46,
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/board": "Economies ranked by net IIP as a share of GDP (countries_only optional).",
            "GET /v1/gross": "Economies ranked by gross external assets as a share of GDP (financial openness).",
            "GET /v1/country": "One economy's full external balance sheet + net-by-function breakdown (country=USA)."
        },
        "description": "Net international investment position by country — the stock of external wealth, how much each economy owns abroad versus what the world owns of it, live from the OECD's balance-of-payments st
…(truncated, see openapi.json for full schema)
```


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