> ## Documentation Index > Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # GetCapitalFlows > GetCapitalFlows returns where money enters and leaves about 230 economies, and between any two, from official statistics. Per country: IMF balance-of-payments gross inflows and outflows by FDI, portfolio and other investment (quarterly where reported, annual otherwise) with derived Forbes and Warnock surge, stop, flight and retrenchment states; BIS cross-border deposits and borrowing of non-bank residents; IMF portfolio holdings of the country's securities; and IMF direct-investment positions. With country and counterpart: both directions of the pair across bank deposits and lending (with eight quarters of adjusted flows), portfolio holdings and direct investment (with both sides' figures), each leg marked reported, not_itemized or not_published. A person changing residence is not a balance-of-payments flow, so wealth migration does not appear. ## OpenAPI ````yaml /api/EconomicService.openapi.yaml get /api/economic/v1/get-capital-flows openapi: 3.1.0 info: title: EconomicService API version: 1.0.0 servers: - url: https://api.worldmonitor.app security: - WorldMonitorKey: [] - ApiKeyHeader: [] paths: /api/economic/v1/get-capital-flows: get: tags: - EconomicService summary: GetCapitalFlows description: >- GetCapitalFlows returns where money enters and leaves about 230 economies, and between any two, from official statistics. Per country: IMF balance-of-payments gross inflows and outflows by FDI, portfolio and other investment (quarterly where reported, annual otherwise) with derived Forbes and Warnock surge, stop, flight and retrenchment states; BIS cross-border deposits and borrowing of non-bank residents; IMF portfolio holdings of the country's securities; and IMF direct-investment positions. With country and counterpart: both directions of the pair across bank deposits and lending (with eight quarters of adjusted flows), portfolio holdings and direct investment (with both sides' figures), each leg marked reported, not_itemized or not_published. A person changing residence is not a balance-of-payments flow, so wealth migration does not appear. operationId: GetCapitalFlows parameters: - name: country in: query description: >- Optional ISO 3166-1 alpha-2 filter. When set, only that country is returned (and the counterpart, if given). required: false example: US schema: type: string - name: include_series in: query description: >- When true, include each returned country's period-by-period BOP series. Defaults to false. required: false example: true schema: type: boolean - name: counterpart in: query description: >- Optional ISO 3166-1 alpha-2 partner. With country, the response adds pair (both directions) and the counterpart's own view. Ignored without country, and when equal to country. required: false example: DE schema: type: string - name: jmespath in: query description: >- Optional JMESPath expression applied server-side to project or reduce the JSON response before it is returned (mirrors the MCP jmespath argument). Invalid expressions, expressions larger than 1024 UTF-8 bytes, or projections that exceed the 256 KB output cap return HTTP 400 with a {_jmespath_error, original_keys} envelope. Grammar and worked examples: https://www.worldmonitor.app/docs/mcp-jmespath. required: false example: keys(@) schema: type: string responses: '200': description: Successful response content: application/json: example: countries: - bank: householdDepositsAbroad: flow4qUsdBn: 1.5 stockUsdBn: 1.5 latestPeriod: 2026-Q1 nonBankBorrowingFromAbroad: flow4qUsdBn: 1.5 stockUsdBn: 1.5 nonBankDepositsAbroad: flow4qUsdBn: 1.5 stockUsdBn: 1.5 publishesBilateral: true bop: episodes: flight: - end: 2026-Q1 peakPeriod: 2026-Q1 peakZ: 1.5 quarters: 1 start: 2026-Q1 retrenchment: - end: 2026-Q1 peakPeriod: 2026-Q1 peakZ: 1.5 quarters: 1 start: 2026-Q1 stop: - end: 2026-Q1 peakPeriod: 2026-Q1 peakZ: 1.5 quarters: 1 start: 2026-Q1 surge: - end: 2026-Q1 peakPeriod: 2026-Q1 peakZ: 1.5 quarters: 1 start: 2026-Q1 frequency: example latestPeriod: 2026-Q1 series: - errorsOmissions: 1.5 inflows: fdi: 1.5 other: 1.5 portfolio: 1.5 total: 1 outflows: fdi: 1.5 other: 1.5 portfolio: 1.5 total: 1 period: 2026-Q1 state: inflow: example inflowZ: 1.5 outflow: example outflowZ: 1.5 country: US fdi: inwardUsdBn: 1.5 outwardUsdBn: 1.5 topDestinations: - country: US flow4qUsdBn: 1.5 stockUsdBn: 1.5 topInvestors: - country: US flow4qUsdBn: 1.5 stockUsdBn: 1.5 year: 1 gdpUsdBn: 1.5 latest: bisQuarter: 2026-Q1 bopQuarter: 2026-Q1 bopYear: example fdiYear: 1 pipYear: 1 method: exampleKey: example pair: aBorrowingFromB: basis: example counterpartReportUsdBn: 1 flow4qUsdBn: 1.5 history: - period: 2026-Q1 usdBn: 1.5 instrument: example aDepositsInB: basis: example counterpartReportUsdBn: 1 flow4qUsdBn: 1.5 history: - period: 2026-Q1 usdBn: 1.5 instrument: example aFdiInB: basis: example counterpartReportUsdBn: 1 flow4qUsdBn: 1.5 history: - period: 2026-Q1 usdBn: 1.5 instrument: example aHoldingsOfB: basis: example counterpartReportUsdBn: 1 flow4qUsdBn: 1.5 history: - period: 2026-Q1 usdBn: 1.5 instrument: example bBorrowingFromA: basis: example counterpartReportUsdBn: 1 flow4qUsdBn: 1.5 history: - period: 2026-Q1 usdBn: 1.5 instrument: example seededAt: 1717200000000 schema: $ref: '#/components/schemas/GetCapitalFlowsResponse' '400': description: Validation error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/JmespathProjectionError' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: >- API access requires an active subscription (the API key's subscription is inactive or expired). headers: X-Billing-Verification: description: >- Present when the 403 is a billing-provider-confirmed subscription lapse (value subscription_lapsed, matching the body `code`). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Rate limit exceeded. headers: X-RateLimit-Limit: description: Maximum requests allowed in the active rate-limit window. schema: type: string X-RateLimit-Remaining: description: Requests remaining in the active rate-limit window. schema: type: string X-RateLimit-Reset: description: >- Unix epoch milliseconds when the active rate-limit window resets. schema: type: string Retry-After: description: Seconds to wait before retrying the request. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/RateLimitError' '503': description: >- Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape. headers: Retry-After: description: Seconds to wait before retrying (1-60). schema: type: string X-Billing-Verification: description: >- Billing-verification state that produced this response (matches the body `code`). schema: type: string X-Validation-Mode: description: >- Present with value degraded when user API-key validation is temporarily unavailable. schema: type: string X-RateLimit-Mode: description: >- Present with value degraded when a fail-closed rate-limit dependency is unavailable. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/BillingVerificationError' - $ref: '#/components/schemas/GatewayError' default: description: Gateway or handler error response. content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/GatewayError' components: schemas: GetCapitalFlowsResponse: type: object properties: countries: type: array items: $ref: '#/components/schemas/CapitalFlowCountry' latest: $ref: '#/components/schemas/CapitalFlowLatest' seededAt: type: integer format: int64 description: >- When the dataset was built, Unix epoch milliseconds. 0 when unavailable.. Warning: Values > 2^53 may lose precision in JavaScript unavailable: type: boolean description: >- True when the seeded dataset is unavailable. An empty country list is not zero flow. sources: type: array items: type: string description: Source URLs. method: type: object additionalProperties: type: string description: >- Short method notes keyed by view: bop, episodes, bank, portfolio, fdi, pairs, caveat. pair: $ref: '#/components/schemas/CapitalFlowPair' description: >- GetCapitalFlowsResponse is cross-country capital-flow data from IMF and BIS official statistics. Amounts are USD billions. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: >- ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. JmespathProjectionError: description: >- Returned when a REST jmespath projection is invalid or exceeds the expression/output byte limits. properties: _jmespath_error: description: Projection error discriminator and details. type: string original_keys: description: Top-level keys or shape of the unprojected response. items: type: string type: array required: - _jmespath_error - original_keys type: object UnauthorizedError: type: object properties: error: type: string description: Human-readable error message. required: - error description: >- Returned when the API key is missing, malformed, or lacks current API access. ForbiddenError: type: object properties: error: type: string description: Human-readable entitlement failure reason. code: type: string enum: - subscription_lapsed description: >- Machine-readable denial code, present when the 403 is a billing-provider-confirmed subscription lapse (mirrored in the X-Billing-Verification response header). requiredTier: type: integer format: int32 description: Minimum entitlement tier required for this endpoint. currentTier: type: integer format: int32 description: Caller entitlement tier when known. planKey: type: string description: Caller plan key when known. required: - error description: >- Returned when a PRO-gated endpoint denies access because the caller has no resolved authenticated user, entitlements cannot be verified, or the caller lacks the required entitlement tier. Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: >- Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. RateLimitError: type: object description: Returned when a gateway or handler rate limit rejects the request. properties: error: type: string description: Human-readable rate-limit failure reason. required: - error BillingVerificationError: type: object description: >- Returned with HTTP 503 when paid access cannot be confirmed right now: the billing provider is re-verifying a recently expired subscription, or the entitlement backend is unreachable. Retryable — honor Retry-After. properties: error: type: string description: Human-readable billing-verification failure reason. code: type: string enum: - renewal_verification_pending - renewal_verification_failed - entitlement_verification_unavailable description: >- Machine-readable billing-verification state, mirrored in the X-Billing-Verification response header. requiredTier: type: integer format: int32 description: >- Minimum entitlement tier required for this endpoint, when the denial came from a tier gate. required: - error - code GatewayError: type: object description: >- Returned by gateway infrastructure errors before an RPC handler runs, such as origin, routing, method, authentication, or quota checks. properties: error: oneOf: - type: string - type: object additionalProperties: true description: Gateway error reason or structured gateway failure details. required: - error CapitalFlowCountry: type: object properties: country: type: string description: ISO 3166-1 alpha-2 code. iso3: type: string description: ISO 3166-1 alpha-3 code. gdpUsdBn: type: number format: double description: >- GDP used for percent-of-GDP figures, USD billions (World Bank, current US dollars). gdpYear: type: integer format: int32 description: Year of that GDP figure. bop: $ref: '#/components/schemas/CapitalFlowBop' bank: $ref: '#/components/schemas/CapitalFlowBank' portfolio: $ref: '#/components/schemas/CapitalFlowPortfolio' fdi: $ref: '#/components/schemas/CapitalFlowFdi' description: >- CapitalFlowCountry carries every capital-flow view for one country. A view is absent when its source publishes nothing for the country. CapitalFlowLatest: type: object properties: bopQuarter: type: string description: >- Quarter most quarterly balance-of-payments reporters have reached, YYYY-Qn. bopYear: type: string description: Year most annual-only reporters have reached. bisQuarter: type: string description: Latest BIS banking quarter, YYYY-Qn. pipYear: type: integer format: int32 description: Portfolio-positions reference year. fdiYear: type: integer format: int32 description: Direct-investment positions reference year. description: CapitalFlowLatest names the newest period of each source. CapitalFlowPair: type: object properties: country: type: string description: ISO 3166-1 alpha-2 code of a, the requested country. counterpart: type: string description: ISO 3166-1 alpha-2 code of b, the counterpart. bankPeriod: type: string description: >- BIS quarter of the bank legs, YYYY-Qn. Portfolio and FDI legs carry their own years below. portfolioYear: type: integer format: int32 description: IMF portfolio-positions year of the holding legs. aDepositsInB: $ref: '#/components/schemas/CapitalFlowPairLeg' bDepositsInA: $ref: '#/components/schemas/CapitalFlowPairLeg' aBorrowingFromB: $ref: '#/components/schemas/CapitalFlowPairLeg' bBorrowingFromA: $ref: '#/components/schemas/CapitalFlowPairLeg' aHoldingsOfB: $ref: '#/components/schemas/CapitalFlowPairLeg' bHoldingsOfA: $ref: '#/components/schemas/CapitalFlowPairLeg' aFdiInB: $ref: '#/components/schemas/CapitalFlowPairLeg' bFdiInA: $ref: '#/components/schemas/CapitalFlowPairLeg' fdiYear: type: integer format: int32 description: IMF direct-investment positions year of the FDI legs. description: >- CapitalFlowPair carries a country (a) and a counterpart (b) in both directions across bank, portfolio and direct-investment channels. FieldViolation: type: object properties: field: type: string description: >- The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: >- Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. CapitalFlowBop: type: object properties: frequency: type: string description: >- quarterly when a current quarterly series exists, otherwise annual. Annual series carry no state and no episodes. latestPeriod: type: string description: 'Latest period in the series: YYYY-Qn or YYYY.' state: $ref: '#/components/schemas/CapitalFlowState' episodes: $ref: '#/components/schemas/CapitalFlowEpisodes' totals: $ref: '#/components/schemas/CapitalFlowTotals' series: type: array items: $ref: '#/components/schemas/CapitalFlowPeriod' description: CapitalFlowBop is the IMF balance-of-payments view of one country. CapitalFlowBank: type: object properties: latestPeriod: type: string description: Latest quarter, YYYY-Qn. nonBankDepositsAbroad: $ref: '#/components/schemas/CapitalFlowPosition' householdDepositsAbroad: $ref: '#/components/schemas/CapitalFlowPosition' nonBankBorrowingFromAbroad: $ref: '#/components/schemas/CapitalFlowPosition' topBankLocations: type: array items: $ref: '#/components/schemas/CapitalFlowCounterparty' publishesBilateral: type: boolean description: >- True when the country's own banks publish a by-counterparty breakdown to the BIS. Some reporting systems publish aggregates only. topDepositorOrigins: type: array items: $ref: '#/components/schemas/CapitalFlowCounterparty' description: >- CapitalFlowBank is the BIS locational banking view of one country's residents. CapitalFlowPortfolio: type: object properties: year: type: integer format: int32 description: >- Reference year: the newest year at least 80% as well reported as the year before. foreignHoldingsUsdBn: type: number format: double description: >- Securities issued by residents of this country held by every reporting economy. foreignHoldingsPrevYearUsdBn: type: number format: double description: >- The same reporters' holdings a year earlier, so the change is like for like. changePct: type: number format: double description: >- Change between the two, percent. Mixes new money with price and exchange-rate moves. reporterCount: type: integer format: int32 description: Number of reporting economies holding the country's securities. topHolders: type: array items: $ref: '#/components/schemas/CapitalFlowCounterparty' holdingsAbroadUsdBn: type: number format: double description: >- The country's own holdings of foreign securities, when it reports them. topDestinations: type: array items: $ref: '#/components/schemas/CapitalFlowCounterparty' description: >- CapitalFlowPortfolio is the IMF portfolio-positions view of one country, from mirror data, in USD billions. CapitalFlowFdi: type: object properties: year: type: integer format: int32 description: >- Reference year: the newest year at least 80% as well reported as the year before. inwardUsdBn: type: number format: double description: Direct investment in the country by all counterparts. topInvestors: type: array items: $ref: '#/components/schemas/CapitalFlowCounterparty' outwardUsdBn: type: number format: double description: The country's direct investment abroad. topDestinations: type: array items: $ref: '#/components/schemas/CapitalFlowCounterparty' description: >- CapitalFlowFdi is the IMF direct-investment positions view of one country, as the country itself reports them, by immediate counterpart, in USD billions. Conduit economies carry large pass-through positions. CapitalFlowPairLeg: type: object properties: status: type: string description: >- reported: the reporting side published a current figure. not_itemized: the reporting side publishes bilateral data but has no current figure for this partner (zero, small, confidential, or a series that stopped); unknown, not zero. not_published: the reporting side publishes no bilateral breakdown. stockUsdBn: type: number format: double description: Outstanding position at the leg's reference period. flow4qUsdBn: type: number format: double description: >- Bank legs: sum of the last four FX- and break-adjusted quarterly changes. prevYearUsdBn: type: number format: double description: 'Portfolio legs: the same holding a year earlier.' basis: type: string description: >- FDI legs: investor when stockUsdBn is the investor's outward figure, host when only the host's inward figure exists. Empty for other legs. counterpartReportUsdBn: type: number format: double description: >- FDI legs: the other side's figure for the same position. The two sides' reports often differ. history: type: array items: $ref: '#/components/schemas/CapitalFlowPairPoint' instrument: type: string description: >- Bank legs: loans_deposits (BIS instrument G) normally; all_instruments (instrument A, which adds debt securities) for a reporting system that publishes no loans-and-deposits breakdown. Empty for other legs. description: >- CapitalFlowPairLeg is one direction of a bilateral position, in USD billions. CapitalFlowState: type: object properties: inflow: type: string description: >- surge or stop when an inflow episode is open at the latest quarter; empty otherwise. outflow: type: string description: >- flight or retrenchment when an outflow episode is open at the latest quarter; empty otherwise. inflowZ: type: number format: double description: >- Inflow z-score at the latest quarter: the change in four-quarter inflows against its trailing 20-quarter mean, in standard deviations. Beyond plus or minus 2 is an episode-level move. outflowZ: type: number format: double description: Outflow z-score at the latest quarter, on the same basis. description: >- CapitalFlowState is the episode classification at the latest quarter both sides report. Derived, not published by the source. CapitalFlowEpisodes: type: object properties: surge: type: array items: $ref: '#/components/schemas/CapitalFlowEpisode' stop: type: array items: $ref: '#/components/schemas/CapitalFlowEpisode' flight: type: array items: $ref: '#/components/schemas/CapitalFlowEpisode' retrenchment: type: array items: $ref: '#/components/schemas/CapitalFlowEpisode' description: >- CapitalFlowEpisodes lists the episodes that ended within the last ten years, oldest first, by type. CapitalFlowTotals: type: object properties: inflowsUsdBn: type: number format: double description: >- Gross inflows over the window. Absent when any quarter in it is incomplete or the quarters are not consecutive. outflowsUsdBn: type: number format: double description: Gross outflows over the window, on the same basis. netUsdBn: type: number format: double description: >- Inflows minus outflows. Positive means the country took in more than it sent out. inflowsPctGdp: type: number format: double description: Gross inflows as a percent of GDP. outflowsPctGdp: type: number format: double description: Gross outflows as a percent of GDP. inflowsYoyPct: type: number format: double description: >- Year-on-year change in gross inflows, percent. Annual series only, and only when the prior year is reported. outflowsYoyPct: type: number format: double description: Year-on-year change in gross outflows, percent, on the same basis. description: >- CapitalFlowTotals summarizes gross flows over the trailing four quarters (quarterly series) or the latest year (annual series). USD billions unless the name ends in Pct or PctGdp. CapitalFlowPeriod: type: object properties: period: type: string description: 'Period label: YYYY-Qn for quarterly series, YYYY for annual series.' inflows: $ref: '#/components/schemas/CapitalFlowComponents' outflows: $ref: '#/components/schemas/CapitalFlowComponents' errorsOmissions: type: number format: double description: >- Net errors and omissions, USD billions. Persistent negative values can indicate outflows the official categories do not record. description: >- CapitalFlowPeriod is one period of gross balance-of-payments financial-account flows. CapitalFlowPosition: type: object properties: stockUsdBn: type: number format: double description: Outstanding amount at the latest quarter. flow4qUsdBn: type: number format: double description: >- Sum of the last four FX- and break-adjusted quarterly changes: money moved, net of exchange-rate effects and reporting breaks. Positive means the position grew. description: >- CapitalFlowPosition is a cross-border bank position from BIS locational banking statistics, in USD billions. CapitalFlowCounterparty: type: object properties: country: type: string description: ISO 3166-1 alpha-2 code of the partner. stockUsdBn: type: number format: double description: Outstanding amount. flow4qUsdBn: type: number format: double description: Four-quarter adjusted flow. Bank lists only. description: >- CapitalFlowCounterparty is one partner country in a ranked bilateral list, in USD billions. CapitalFlowPairPoint: type: object properties: period: type: string description: Quarter, YYYY-Qn. usdBn: type: number format: double description: >- Adjusted flow in the quarter, USD billions. Positive means the position grew. description: CapitalFlowPairPoint is one quarterly adjusted bank flow. CapitalFlowEpisode: type: object properties: start: type: string description: >- First quarter of the episode, YYYY-Qn: the first quarter the change in four-quarter flows moved more than one standard deviation from its trailing mean. end: type: string description: >- Last quarter of the episode, YYYY-Qn. Equals the series' latest quarter while the episode is still open. quarters: type: integer format: int32 description: Number of quarters in the episode; always at least 2. peakZ: type: number format: double description: >- Largest absolute z-score reached during the episode; always at least 2. peakPeriod: type: string description: Quarter of the peak z-score, YYYY-Qn. description: >- CapitalFlowEpisode is one Forbes and Warnock (2012) episode on a quarterly series. Derived from reported flows, not published by the source. CapitalFlowComponents: type: object properties: fdi: type: number format: double description: >- Direct investment: lasting-interest stakes of 10% or more, including reinvested earnings and intercompany debt. portfolio: type: number format: double description: >- Portfolio investment: equity and debt securities that are not direct investment. other: type: number format: double description: >- Other investment: loans, deposits, currency, trade credit and other accounts. total: type: number format: double description: >- Sum of the three categories. Set only when all three are reported for the period; a partial sum would read as a collapse. description: >- CapitalFlowComponents splits one side of the financial account by functional category, in USD billions. A component is absent when the source does not report it for the period. securitySchemes: WorldMonitorKey: type: apiKey in: header name: X-WorldMonitor-Key description: User-issued WorldMonitor API key. ApiKeyHeader: type: apiKey in: header name: X-Api-Key description: Alias header for the WorldMonitor API key (X-WorldMonitor-Key). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.