REST API Documentation — FundaFX | For AI Bot and Algo Trading Developers

30-second quick start

Just grab your API key, copy and paste — you can start fetching data right away.

1

Get an API key

Issue one from the FundaFX mobile app via Settings > API Key Management. You will see a key starting with fndx_. That key is your credential.

2

Copy, paste, and run the snippet below

Replace YOUR_KEY with the key you obtained in step 1.

curl — paste into a terminal and run

curl -s "https://api.fundafx.link/api/v1/facts?limit=3&importance=high" \
  -H "X-API-Key: YOUR_KEY" | python3 -m json.tool

3

Reading the response

On success you will get a JSON response like the one below. The items array contains the facts (economic news).

Response (HTTP 200)

{
  "items": [
    {
      "id": "6615a7ca-b2df-47c8-b038-c08bf260505a",   // Unique fact ID (UUID)
      "fact_type": "media_report",                    // Type: institutional_release / official_speech / media_report
      "category": "geopolitical",                     // Category: monetary_policy / inflation / employment, etc.
      "importance": "high",                            // Importance: high / medium / low
      "text": {
        "en": {
          "title": "Global markets to stay driven by West Asia conflict; Fed neutral guidance reflects uncertainty",
          "summary": "The Afghanistannews.net report states that global markets will remain driven by the West Asia conflict...",
          "detail": null,               // Detailed description (when present)
          "quality_score": null          // Text quality score 0.0-1.0
        },
        "ja": {
          "title": "西アジア情勢が世界市場を引き続き動かす；FRBの中立的指針は不確実性を反映",
          "summary": "アフガニスタンニュースの報道によれば、西アジア情勢が世界市場を引き続き動かし...",
          "detail": null,
          "quality_score": null
        }
      },
      "currencies_affected": [             // Currencies this fact affects
        { "code": "USD" }
      ],
      "verification_details": {            // Fact-check result from AI
        "sources_checked": 2,              // Number of sources checked
        "sources_confirmed": 1,            // Number of sources that confirmed the content
        "confidence_score": 0.662,          // Confidence score (0.0-1.0)
        "verified_at": "2026-03-21T05:30:36.860963",
        "notes": "Rule check: No numeric value to rule-check; deferring to LLM. | Original article title and content match..."
      },
      "source_urls": ["http://www.afghanistannews.net/news/278934978/..."],
      "source_name": "gdelt",               // Data source name
      "source_collector": "gdelt",            // Collector pipeline name
      "event_timestamp": "2026-03-21T04:15:00+00:00"  // Event timestamp
    }
  ],
  "count": 35,          // Total items matching the filter
  "limit": 3,           // Limit for this request
  "offset": 0,          // Pagination offset
  "disclaimer": {      // Disclaimer (attached to every response)
    "en": "This information is AI-aggregated factual data and does not constitute investment advice...",
    "ja": "本情報はAIによる事実情報の収集・構造化データであり、投資助言ではありません..."
  }
}

Authentication

All API endpoints require authentication (with the exception of a few public endpoints).

How API keys work

1. How to get one: Issue one from the FundaFX mobile app at Settings > API Key Management.

2. Key format: A string starting with fndx_. The server stores only its SHA256 hash, and the plain key value is shown only once at issuance. If you lose it, please reissue.

3. Sending requests: Set the X-API-Key header on every request.

4. Monthly reset: The request counter resets on the first day of each month.

Request example

curl https://api.fundafx.link/api/v1/facts \
  -H "X-API-Key: fndx_your_api_key_here"

Rate limiting

The number of requests is limited by the API key's tier.

Tier	Limit	Price
Free	100 requests / month	Free
Pro	5,000 requests / month	$4.99 / month

Check your current usage with GET /auth/usage. When you exceed the limit, the API returns 429 Too Many Requests.

Response headers

The following headers are attached to every authenticated response.

Header	Description	Example
`X-RateLimit-Limit`	Monthly request limit	`100`
`X-RateLimit-Remaining`	Remaining requests this month	`77`
`X-RateLimit-Reset`	Seconds until counter reset	`1728000`

SDK examples

Copy-paste-ready complete code examples for Python and JavaScript.

Python (requests)

import requests

API_KEY = "fndx_your_api_key_here"  # Replace with your key
BASE    = "https://api.fundafx.link/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# --- 1. Get high-importance USD-related facts ---
resp = requests.get(
    f"{BASE}/facts",
    headers=HEADERS,
    params={"currency": "USD", "importance": "high", "limit": 5},
)
facts = resp.json()

print(f"USD-related important facts: {facts['count']} items")
for item in facts["items"]:
    title = item["text"]["ja"]["title"]
    score = item["verification_details"]["confidence_score"]
    print(f"  [{score:.2f}] {title}")

# --- 2. Fed current policy rate ---
fed = requests.get(f"{BASE}/central-banks/FED", headers=HEADERS).json()
print(f"\nFed policy rate: {fed['current_rate']}%")
print(f"Next FOMC: {fed['next_meeting_date']}")

# --- 3. EURUSD exchange rate (last 3 days) ---
rates = requests.get(
    f"{BASE}/exchange-rates/EURUSD",
    headers=HEADERS,
    params={"days": 3},
).json()
for v in rates["values"][:3]:
    print(f"  {v['date']} | EURUSD = {v['close']}")

JavaScript (fetch)

const API_KEY = "fndx_your_api_key_here";  // Replace with your key
const BASE    = "https://api.fundafx.link/api/v1";
const headers = { "X-API-Key": API_KEY };

// --- 1. Get high-importance USD-related facts ---
const factsRes = await fetch(
  `${BASE}/facts?currency=USD&importance=high&limit=5`,
  { headers }
);
const facts = await factsRes.json();

console.log(`USD-related important facts: ${facts.count} items`);
facts.items.forEach(item => {
  const title = item.text.ja.title;
  const score = item.verification_details.confidence_score;
  console.log(`  [${score?.toFixed(2)}] ${title}`);
});

// --- 2. Fed current policy rate ---
const fed = await fetch(`${BASE}/central-banks/FED`, { headers }).then(r => r.json());
console.log(`\nFed policy rate: ${fed.current_rate}%`);
console.log(`Next FOMC: ${fed.next_meeting_date}`);

// --- 3. EURUSD exchange rate (last 3 days) ---
const rates = await fetch(
  `${BASE}/exchange-rates/EURUSD?days=3`,
  { headers }
).then(r => r.json());
rates.values.slice(0, 3).forEach(v => {
  console.log(`  ${v.date} | EURUSD = ${v.close}`);
});

↑ Back to endpoint index

Auth

Check your API key usage. Inspect the remaining request count to manage your rate limits.

GET /auth/usage Auth required

Returns the current rate-limit usage for the API key. Lets you check the monthly remaining requests and tier.

Use case: check the remaining request count

It's a good idea to check the remaining request count when your app starts or before a batch job.

curl

curl -s https://api.fundafx.link/api/v1/auth/usage \
  -H "X-API-Key: YOUR_KEY"

Response 200

{
  "api_key_id": 1,                  // Internal API key ID
  "requests_this_month": 0,         // Requests this month
  "rate_limit_per_month": 100,      // Monthly limit (Free: 100, Pro: 5000)
  "tier": "free"                    // Tier: "free" or "pro"
}

↑ Back to endpoint index

Facts

Fundamental facts that move the FX market — economic data releases, monetary policy decisions, key official statements, news reports, and so on. Collected, verified, and translated by an AI pipeline.

GET /facts Auth required

Retrieve a list of facts. You can narrow results by filter. Sorted by event timestamp, newest first.

Query Parameters

Parameter	Type	Description
fact_type	string	Fact type: `institutional_release` (announcements from public bodies), `official_speech` (statements from key officials), `media_report` (news)
category	string	Category: `monetary_policy`, `employment`, `inflation`, `gdp_growth`, `fiscal_policy`, `geopolitical`, etc.
currency	string	Affected currency code: `USD`, `EUR`, `JPY`, `GBP`, `AUD`, `CAD`, `CHF`, `NZD`, `CNY`
importance	string	Importance: `high`, `medium`, `low`
source_collector	string	Source collector: `ecb`, `cb_rss`, `gdelt`, `twitter`, `news_rss`, `frb_rss`, etc.
date_from	datetime	Start datetime (ISO 8601), e.g., `2026-03-01T00:00:00Z`
date_to	datetime	End datetime (ISO 8601)
limit	int	Number of items (1-200, default 50)
offset	int	Pagination offset (default 0)

Use case: get high-importance USD news from the last week

curl

curl -s "https://api.fundafx.link/api/v1/facts?currency=USD&importance=high&limit=5&date_from=2026-03-15T00:00:00Z" \
  -H "X-API-Key: YOUR_KEY"

Response 200

{
  "items": [
    {
      "id": "6615a7ca-b2df-47c8-b038-c08bf260505a",
      "fact_type": "media_report",
      "category": "geopolitical",
      "importance": "high",
      "stage": "published",
      "text": {
        "en": {
          "title": "Global markets to stay driven by West Asia conflict; Fed neutral guidance reflects uncertainty",
          "summary": "The Afghanistannews.net report states that global markets will remain driven by the West Asia conflict, and that Federal Reserve neutral guidance reflects uncertainty.",
          "detail": null,
          "quality_score": null
        },
        "ja": {
          "title": "西アジア情勢が世界市場を引き続き動かす；FRBの中立的指針は不確実性を反映",
          "summary": "アフガニスタンニュースの報道によれば、西アジア情勢が世界市場を引き続き動かし、連邦準備制度の中立的なガイダンスが不確実性を反映している。",
          "detail": null,
          "quality_score": null
        }
      },
      "currencies_affected": [
        { "code": "USD" }
      ],
      "context": {
        "related_facts": [
          {
            "id": "2f9c4bd9-7e5f-4243-b97e-9253b0fe31b6",
            "title": "Bureau of Labor Statistics posted about employment data on X",
            "fact_type": "institutional_release",
            "event_timestamp": "2026-03-20T14:08:02+00:00"
          }
        ],
        "currency_context": {
          "USD": {
            "dominant_category": "gdp_growth",
            "recent_fact_count": 32
          }
        }
      },
      "verification_details": {
        "sources_checked": 2,
        "sources_confirmed": 1,
        "confidence_score": 0.662,
        "verified_at": "2026-03-21T05:30:36.860963",
        "notes": "Rule check: No numeric value to rule-check; deferring to LLM..."
      },
      "source_urls": ["http://www.afghanistannews.net/news/278934978/..."],
      "source_name": "gdelt",
      "source_collector": "gdelt",
      "event_timestamp": "2026-03-21T04:15:00+00:00",
      "created_at": "2026-03-20T20:30:42.740844+00:00",
      "updated_at": "2026-03-20T20:30:42.740844+00:00",
      "published_at": "2026-03-20T20:30:42.740844+00:00"
    }
  ],
  "count": 35,
  "limit": 5,
  "offset": 0,
  "disclaimer": {
    "en": "This information is AI-aggregated factual data and does not constitute investment advice. Past statistics do not guarantee future results. All investment decisions are made at your own risk and responsibility.",
    "ja": "本情報はAIによる事実情報の収集・構造化データであり、投資助言ではありません。過去の統計は将来の結果を保証するものではなく、最終的な投資判断は必ずご自身の責任で行ってください。"
  }
}

Response field details

text

Localized text by language. Keys are language codes (en = English, ja = Japanese).

Field	Type	Description
title	string	Short headline (one line)
summary	string	Summary (1-3 sentences)
detail	string \| null	Detailed description (when present)
quality_score	float \| null	Text quality score (0.0-1.0, scored automatically by AI)

currencies_affected

Array of currencies this fact affects.

Field	Type	Description
code	string	ISO currency code: `USD`, `EUR`, `JPY`, `GBP`, `AUD`, `CAD`, `CHF`, `NZD`, `CNY`

verification_details

Fact-check result from the AI pipeline.

Field	Type	Description
sources_checked	int	Number of sources checked for verification
sources_confirmed	int	Number of sources that confirmed the content
confidence_score	float	Confidence score (0.0-1.0)
verified_at	datetime \| null	Verification timestamp (ISO 8601)
notes	string \| null	Verification notes (generated by AI)

context

Contextual information for the fact. Includes related facts and the recent state of relevant currencies.

Field	Type	Description
related_facts	array \| null	List of related facts (id, title, fact_type, event_timestamp)
currency_context	object \| null	Per-currency snapshot (dominant_category, recent_fact_count)

GET /facts/{fact_id} Auth required

Retrieve a fact by UUID. Response fields are identical to each item in GET /facts.

Path Parameters

Parameter	Type	Description
fact_id	uuid required	Fact UUID (e.g., `6615a7ca-b2df-47c8-b038-c08bf260505a`)

curl

curl -s "https://api.fundafx.link/api/v1/facts/6615a7ca-b2df-47c8-b038-c08bf260505a" \
  -H "X-API-Key: YOUR_KEY"

↑ Back to endpoint index

Indicators

Metadata and time-series data for economic indicators (GDP, CPI, employment, etc.).

GET /indicators Auth required

List economic indicators. You can narrow by country code or category.

Query Parameters

Parameter	Type	Description
country_code	string	ISO country code: `US`, `JP`, `DE`, `GB`, `AU`, etc.
category	string	Category: `inflation`, `employment`, `gdp_growth`, `monetary_policy`, etc.

Use case: list US economic indicators

curl

curl -s "https://api.fundafx.link/api/v1/indicators?country_code=US" \
  -H "X-API-Key: YOUR_KEY"

Response 200

{
  "items": [
    {
      "id": 2,
      "code": "US_CPI",
      "name_en": "US Consumer Price Index",
      "name_ja": "米国消費者物価指数",
      "country_code": "US",
      "currency": "USD",
      "category": "inflation",
      "importance": "high",
      "unit": "Index",
      "frequency": "monthly",
      "source_api": "OECD",
      "source_series_id": "CPIAUCSL",
      "description": null
    },
    {
      "id": 1,
      "code": "US_GDP",
      "name_en": "US Gross Domestic Product",
      "name_ja": "米国GDP",
      "country_code": "US",
      "currency": "USD",
      "category": "gdp_growth",
      "importance": "high",
      "unit": "Billions USD",
      "frequency": "quarterly",
      "source_api": "OECD",
      "source_series_id": "GDP",
      "description": null
    },
    {
      "id": 3,
      "code": "US_NFP",
      "name_en": "US Nonfarm Payrolls",
      "name_ja": "米国非農業部門雇用者数",
      "country_code": "US",
      "currency": "USD",
      "category": "employment",
      "importance": "high",
      "unit": "Thousands",
      "frequency": "monthly",
      "source_api": "OECD",
      "source_series_id": "PAYEMS",
      "description": null
    }
  ],
  "count": 6,
  "disclaimer": { "en": "...", "ja": "..." }
}

GET /indicators/{indicator_id} Auth required

Retrieve detailed metadata and time-series data (the values array) for an indicator.

Parameters

Parameter	Type	Description
indicator_id	int required	Indicator ID (path) — pass the `id` obtained from GET /indicators
limit	int	Number of time-series data points (1-500, default 50)

Use case: get US GDP details and time-series

curl

curl -s "https://api.fundafx.link/api/v1/indicators/1" \
  -H "X-API-Key: YOUR_KEY"

Response 200

{
  "id": 1,
  "code": "US_GDP",
  "name_en": "US Gross Domestic Product",
  "name_ja": "米国GDP",
  "country_code": "US",
  "currency": "USD",
  "category": "gdp_growth",
  "importance": "high",
  "unit": "Billions USD",
  "frequency": "quarterly",
  "source_api": "OECD",
  "source_series_id": "GDP",
  "description": null,
  "values": []  // Time-series data (value, previous_value, expected_value, period, release_date)
}

GET /indicators/{indicator_id}/latest Auth required

Get only the latest value of an indicator. Convenient when you don't need historical data.

GET /indicators/rate-trends Auth required

Aggregated data for policy-rate trends. Pulls central bank info, indicator values, and related facts in a single call. Ideal for rendering rate charts.

Query Parameters

Parameter	Type	Description
currencies	string	Currency codes (comma-separated): `USD,EUR,JPY`
days	int	Period (in days, 1-3650, default 365)

↑ Back to endpoint index

Central Banks

Information for the 8 major central banks (policy rate, next meeting, governor name) and a rate-differential matrix.

GET /central-banks Auth required

Returns all active central banks. Includes current policy rate, next meeting date, and governor name.

curl

curl -s "https://api.fundafx.link/api/v1/central-banks" \
  -H "X-API-Key: YOUR_KEY"

Response 200

{
  "items": [
    {
      "id": 1,
      "code": "FED",
      "name_en": "Federal Reserve",
      "name_ja": "米連邦準備制度理事会",
      "country_code": "US",
      "currency": "USD",
      "institution_type": "central_bank",
      "website_url": "https://www.federalreserve.gov",
      "current_rate": 4.5,
      "next_meeting_date": "2026-03-18",
      "governor_name": "Jerome Powell",
      "is_active": true,
      "metadata": {}
    },
    {
      "id": 2,
      "code": "ECB",
      "name_en": "European Central Bank",
      "name_ja": "欧州中央銀行",
      "country_code": "EU",
      "currency": "EUR",
      "current_rate": 3.15,
      "next_meeting_date": "2026-03-06",
      "governor_name": "Christine Lagarde"
    },
    { "code": "BOJ", "name_ja": "日本銀行", "current_rate": 0.5, "governor_name": "Kazuo Ueda" },
    { "code": "BOE", "name_ja": "イングランド銀行", "current_rate": 4.5, "governor_name": "Andrew Bailey" },
    { "code": "RBA", "name_ja": "オーストラリア準備銀行", "current_rate": 4.1, "governor_name": "Michele Bullock" },
    { "code": "BOC", "name_ja": "カナダ銀行", "current_rate": 3.25, "governor_name": "Tiff Macklem" },
    { "code": "SNB", "name_ja": "スイス国立銀行", "current_rate": 0.5, "governor_name": "Martin Schlegel" },
    { "code": "RBNZ", "name_ja": "ニュージーランド準備銀行", "current_rate": 3.75, "governor_name": "Adrian Orr" }
  ],
  "count": 8
}

GET /central-banks/rate-matrix Auth required

Returns a rate-differential matrix across all central banks. Useful for carry-trade analysis. Cell value = row rate - column rate (%).

Response 200 (excerpt)

{
  "institutions": [
    { "code": "FED", "currency": "USD", "current_rate": 4.5 },
    { "code": "ECB", "currency": "EUR", "current_rate": 3.15 },
    { "code": "BOJ", "currency": "JPY", "current_rate": 0.5 }
  ],
  "matrix": {
    "FED": { "ECB": 1.35, "BOJ": 4.0, "BOE": 0.0, "RBA": 0.4 },  // Fed rate - counterparty rate
    "ECB": { "FED": -1.35, "BOJ": 2.65, "BOE": -1.35 },
    "BOJ": { "FED": -4.0, "ECB": -2.65, "BOE": -4.0 }
  }
}

GET /central-banks/{code} Auth required

Retrieve a central bank's details by code.

Path Parameters

Parameter	Type	Description
code	string required	`FED`, `ECB`, `BOJ`, `BOE`, `RBA`, `BOC`, `SNB`, `RBNZ`

Use case: Fed current policy rate and next meeting date

curl

curl -s "https://api.fundafx.link/api/v1/central-banks/FED" \
  -H "X-API-Key: YOUR_KEY"

Response 200

{
  "id": 1,
  "code": "FED",
  "name_en": "Federal Reserve",
  "name_ja": "米連邦準備制度理事会",
  "country_code": "US",
  "currency": "USD",
  "institution_type": "central_bank",
  "website_url": "https://www.federalreserve.gov",
  "current_rate": 4.5,                    // Current policy rate (%)
  "next_meeting_date": "2026-03-18",       // Next meeting date
  "governor_name": "Jerome Powell",        // Governor name
  "is_active": true,
  "metadata": {}
}

↑ Back to endpoint index

Exchange Rates

ECB-sourced daily FX rate time series. Only EUR-based pairs are supported.

GET /exchange-rates/{pair} Auth required

Retrieve daily rates for a currency pair. Only EUR-based pairs are supported (EURUSD, EURJPY, EURGBP, etc.). Non-EUR pairs (e.g., USDJPY) will return an error.

Parameters

Parameter	Type	Description
pair	string required	Currency pair (path): `EURUSD`, `EURJPY`, `EURGBP`, `EURAUD`, `EURCAD`, `EURCHF`, `EURNZD`
days	int	Period (in days, 1-3650, default 365)

Use case: last 3 days of EURUSD rates

curl

curl -s "https://api.fundafx.link/api/v1/exchange-rates/EURUSD?days=3" \
  -H "X-API-Key: YOUR_KEY"

Response 200

{
  "pair": "EURUSD",
  "base_currency": "EUR",
  "quote_currency": "USD",
  "values": [
    { "date": "2026-03-19", "close": 1.1489 },
    { "date": "2026-03-18", "close": 1.15 },
    { "date": "2026-03-17", "close": 1.1531 }
  ],
  "count": 3,
  "disclaimer": {
    "en": "This information is AI-aggregated factual data...",
    "ja": "本情報はAIによる事実情報の収集・構造化データであり..."
  }
}

Non-EUR pairs return an error

For example, if you specify USDJPY:

Error Response (USDJPY)

{
  "detail": "Exchange rate data not available for pair 'USDJPY'. Only EUR-based pairs are currently supported."
}

↑ Back to endpoint index

Sources

List of data sources collected by FundaFX, plus the monitored social accounts. License information for each source is included.

GET /sources Auth required

Returns all data sources (ECB, FRB, e-Stat, etc.) and the list of monitored X accounts.

curl

curl -s "https://api.fundafx.link/api/v1/sources" \
  -H "X-API-Key: YOUR_KEY"

Response 200 (excerpt)

{
  "data_sources": [
    {
      "name": "ecb",
      "display_name_en": "ECB Statistical Data",
      "display_name_ja": "ECB統計データ",
      "category": "central_bank",
      "is_active": true,
      "license": "Free use with attribution (Source: ECB statistics.)",
      "url": "https://data.ecb.europa.eu"
    },
    {
      "name": "estat",
      "display_name_en": "e-Stat (Japan Statistics)",
      "display_name_ja": "e-Stat（政府統計）",
      "category": "government",
      "is_active": true,
      "license": "CC-BY 4.0",
      "url": "https://www.e-stat.go.jp"
    }
  ],
  "monitoring_accounts": [
    { "username": "FederalReserve", "display_name": "Federal Reserve" }
  ]
}

↑ Back to endpoint index

Error codes

All error responses are returned as JSON. The error message is included in the detail field.

Code	Description	How to resolve
`400`	Invalid request parameters	Check the parameter's type and value. Example: importance must be `high` / `medium` / `low` only.
`401`	API key is invalid or missing	Check the `X-API-Key` header. If lost, reissue from the app.
`404`	Resource not found	Verify that the specified ID or code exists.
`429`	Rate limit exceeded	Check the remainder via `GET /auth/usage`. Upgrade to Pro or wait for next month.
`500`	Internal server error	Likely a transient issue. Retry after a short delay.

Error response examples

401 — Missing API key

{
  "detail": "Authentication required. Provide X-App-Token or X-API-Key header."
}

401 — Invalid API key

{
  "detail": "Invalid or inactive API key"
}

Unsupported parameter (exchange-rates example)

{
  "detail": "Exchange rate data not available for pair 'USDJPY'. Only EUR-based pairs are currently supported."
}

↑ Back to endpoint index

REST API Reference

30-second quick start

Get an API key

Copy, paste, and run the snippet below

Reading the response

Authentication

How API keys work

Rate limiting

Response headers

SDK examples

Endpoint index

Auth

Use case: check the remaining request count

Facts

Use case: get high-importance USD news from the last week

text

currencies_affected

verification_details

context

Indicators

Use case: list US economic indicators

Use case: get US GDP details and time-series

Central Banks

Use case: Fed current policy rate and next meeting date

Exchange Rates

Use case: last 3 days of EURUSD rates

Non-EUR pairs return an error

Sources

Error codes

Error response examples