{"openapi":"3.0.3","info":{"title":"forex.mobile Public API","description":"Free REST API providing forex broker data, comparisons, recommendations, live forex rates, and glossary terms. No API key required — 100 requests/day per IP. Built for developers and AI agents. Also available as an MCP server: `npx forex-mobile-mcp`.","version":"1.0.0","termsOfService":"https://forex.mobile/terms-of-service","contact":{"name":"forex.mobile","url":"https://forex.mobile/api","email":"hello@forex.mobile"},"license":{"name":"Data is free to use with attribution","url":"https://forex.mobile/api"}},"externalDocs":{"description":"API documentation and usage examples","url":"https://forex.mobile/api"},"servers":[{"url":"https://forex.mobile","description":"Production"}],"tags":[{"name":"Brokers","description":"Broker data, comparisons, recommendations"},{"name":"Market Data","description":"Live forex rates"},{"name":"Glossary","description":"Forex term definitions"}],"paths":{"/api/v1":{"get":{"summary":"API index","description":"Returns the list of available endpoints with descriptions and examples.","operationId":"getApiIndex","responses":{"200":{"description":"Index of all available endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}}}}},"/api/v1/brokers":{"get":{"tags":["Brokers"],"summary":"List all brokers","description":"Returns all reviewed forex brokers with scores, spreads, regulation, Trustpilot ratings, platforms, minimum deposits, and affiliate links. Updated with live data.","operationId":"listBrokers","responses":{"200":{"description":"All brokers","content":{"application/json":{"schema":{"type":"object","required":["count","brokers","_meta"],"properties":{"count":{"type":"integer","example":14},"brokers":{"type":"array","items":{"$ref":"#/components/schemas/Broker"}},"_meta":{"$ref":"#/components/schemas/Meta"}}}}}},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/brokers/{slug}":{"get":{"tags":["Brokers"],"summary":"Get single broker","description":"Returns detailed data for a single broker by its key slug.","operationId":"getBroker","parameters":[{"name":"slug","in":"path","required":true,"description":"Broker key (e.g. `exness`, `xm`, `avatrade`, `ic-markets`)","schema":{"type":"string","example":"exness"}}],"responses":{"200":{"description":"Broker data","content":{"application/json":{"schema":{"type":"object","required":["broker","_meta"],"properties":{"broker":{"$ref":"#/components/schemas/Broker"},"_meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/compare":{"get":{"tags":["Brokers"],"summary":"Compare two brokers","description":"Side-by-side comparison with an auto-generated verdict paragraph highlighting score, minimum deposit, Trustpilot rating, platform variety, and Islamic account availability.","operationId":"compareBrokers","parameters":[{"name":"a","in":"query","required":true,"description":"First broker key","schema":{"type":"string","example":"exness"}},{"name":"b","in":"query","required":true,"description":"Second broker key","schema":{"type":"string","example":"xm"}}],"responses":{"200":{"description":"Comparison result","content":{"application/json":{"schema":{"type":"object","required":["comparison","_meta"],"properties":{"comparison":{"type":"object","required":["a","b","verdict"],"properties":{"a":{"$ref":"#/components/schemas/Broker"},"b":{"$ref":"#/components/schemas/Broker"},"verdict":{"type":"string","example":"Exness scores 4.8/5 vs XM's 4.7/5. XM has a lower minimum deposit ($5 vs $10). Exness rates higher on Trustpilot."}}},"_meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/recommend":{"get":{"tags":["Brokers"],"summary":"Recommend top 3 brokers","description":"Returns the top 3 broker recommendations filtered by country, trader experience level, and priority (spreads, education, regulation, or minimum deposit). Country → region mapping covers 50+ countries across MENA, APAC, Europe, Americas, and Africa.","operationId":"recommendBrokers","parameters":[{"name":"country","in":"query","required":true,"description":"Country slug (e.g. `uae`, `saudi-arabia`, `vietnam`, `us`, `germany`, `nigeria`)","schema":{"type":"string","example":"uae"}},{"name":"experience","in":"query","required":false,"description":"Trader experience level","schema":{"type":"string","enum":["beginner","intermediate","advanced"],"default":"beginner"}},{"name":"priority","in":"query","required":false,"description":"What the trader cares about most","schema":{"type":"string","enum":["spreads","education","regulation","deposit"],"default":"spreads"}}],"responses":{"200":{"description":"Top 3 recommendations","content":{"application/json":{"schema":{"type":"object","required":["query","recommendations","_meta"],"properties":{"query":{"type":"object","properties":{"country":{"type":"string"},"experience":{"type":"string"},"priority":{"type":"string"}}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"_meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimit"}}}},"/api/v1/rates":{"get":{"tags":["Market Data"],"summary":"Live forex rates","description":"Returns current forex rates for major pairs and metals (EUR/USD, GBP/USD, USD/JPY, XAU/USD, etc.). Data from Yahoo Finance. Update frequency: ~15 minutes during market hours.","operationId":"getRates","parameters":[{"name":"from","in":"query","required":false,"description":"Base currency (optional). If omitted, returns all major pairs.","schema":{"type":"string","example":"EUR"}},{"name":"to","in":"query","required":false,"description":"Quote currency (optional)","schema":{"type":"string","example":"USD"}}],"responses":{"200":{"description":"Forex rates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RatesResponse"}}}},"429":{"$ref":"#/components/responses/RateLimit"},"502":{"description":"Upstream rate provider unavailable"}}}},"/api/v1/glossary":{"get":{"tags":["Glossary"],"summary":"Glossary terms","description":"Returns all forex glossary terms, or a single term by slug. Each term includes a short one-line definition and a longer detailed explanation.","operationId":"getGlossary","parameters":[{"name":"term","in":"query","required":false,"description":"Term slug for single-term lookup (e.g. `pip`, `leverage`, `spread`). Omit for the full list.","schema":{"type":"string","example":"pip"}}],"responses":{"200":{"description":"Glossary data","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["term","_meta"],"properties":{"term":{"$ref":"#/components/schemas/GlossaryTerm"},"_meta":{"$ref":"#/components/schemas/Meta"}}},{"type":"object","required":["count","terms","_meta"],"properties":{"count":{"type":"integer","example":50},"terms":{"type":"array","items":{"$ref":"#/components/schemas/GlossaryTerm"}},"_meta":{"$ref":"#/components/schemas/Meta"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimit"}}}}},"components":{"schemas":{"Broker":{"type":"object","required":["key","name","score","minDeposit","spreads","regulation"],"properties":{"key":{"type":"string","example":"exness","description":"Unique broker key / slug"},"name":{"type":"string","example":"Exness"},"score":{"type":"number","format":"float","minimum":0,"maximum":5,"example":4.8},"minDeposit":{"type":"string","example":"$10"},"spreads":{"type":"string","example":"0.0 pips"},"regulation":{"type":"array","items":{"type":"string"},"example":["FCA","CySEC","FSCA"]},"founded":{"type":"integer","example":2008},"hq":{"type":"string","example":"Cyprus"},"platforms":{"type":"array","items":{"type":"string"},"example":["MT4","MT5"]},"affiliateUrl":{"type":"string","format":"uri","description":"URL with affiliate tracking parameters. Partners may earn commission on signups."},"directUrl":{"type":"string","format":"uri","description":"Plain direct URL without tracking (if available).","nullable":true},"trustpilotScore":{"type":"number","format":"float","example":4.5,"minimum":0,"maximum":5},"trustpilotReviews":{"type":"integer","example":12500},"tags":{"type":"array","items":{"type":"string"},"example":["Low spreads","Islamic accounts","Instant withdrawals"]},"islamicAccount":{"type":"boolean","example":true},"proscons":{"type":"object","properties":{"pros":{"type":"array","items":{"type":"string"}},"cons":{"type":"array","items":{"type":"string"}}}},"reviewSlug":{"type":"string","nullable":true,"description":"Path slug for the in-depth review at forex.mobile/reviews/{slug}","example":"exness"}}},"Recommendation":{"type":"object","required":["rank","broker","key","score","reason","affiliateUrl"],"properties":{"rank":{"type":"integer","minimum":1,"maximum":3},"broker":{"type":"string","example":"Exness"},"key":{"type":"string","example":"exness"},"score":{"type":"number","format":"float","example":4.8},"reason":{"type":"string","example":"Instant AED/SAR withdrawals, Islamic accounts, 0.0 pip spreads"},"affiliateUrl":{"type":"string","format":"uri"},"tags":{"type":"array","items":{"type":"string"},"example":["#1 in MENA","Low spreads"]}}},"GlossaryTerm":{"type":"object","required":["slug","term","short","long","category"],"properties":{"slug":{"type":"string","example":"pip"},"term":{"type":"string","example":"Pip"},"short":{"type":"string","description":"One-line definition","example":"The smallest price move in a currency pair (typically 0.0001)."},"long":{"type":"string","description":"Detailed explanation (can be multiple paragraphs, may include examples)"},"category":{"type":"string","example":"trading-basics","enum":["trading-basics","chart-analysis","risk-management","platforms","regulation","advanced"]},"related":{"type":"array","items":{"type":"string"},"example":["spread","pip-value","leverage"]}}},"RatesResponse":{"type":"object","properties":{"rates":{"type":"object","additionalProperties":{"type":"object","properties":{"price":{"type":"number","example":1.0856},"change":{"type":"number","example":0.0023},"changePct":{"type":"number","example":0.21},"updatedAt":{"type":"string","format":"date-time"}}},"example":{"EUR/USD":{"price":1.0856,"change":0.0023,"changePct":0.21},"GBP/USD":{"price":1.2634,"change":-0.0011,"changePct":-0.09},"XAU/USD":{"price":2382.45,"change":12.3,"changePct":0.52}}},"_meta":{"$ref":"#/components/schemas/Meta"}}},"ApiIndex":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"endpoints":{"type":"array","items":{"type":"object"}},"_meta":{"$ref":"#/components/schemas/Meta"}}},"Meta":{"type":"object","required":["source","api_version","docs"],"properties":{"source":{"type":"string","example":"forex.mobile"},"api_version":{"type":"string","example":"v1"},"docs":{"type":"string","format":"uri","example":"https://forex.mobile/api"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"example":{"type":"string"},"available":{"type":"array","items":{"type":"string"}},"_meta":{"$ref":"#/components/schemas/Meta"}}}},"responses":{"BadRequest":{"description":"Missing or invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimit":{"description":"Rate limit exceeded. Free tier: 100 requests per day per IP. Resets at midnight UTC. Contact hello@forex.mobile for higher limits.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Maximum requests allowed per day"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current window"},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp when the rate limit resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}