### Install the SDK

Source: https://banksync.io/developers/mcp-setup/typescript

Install the official BankSync MCP TypeScript SDK using npm.

```bash
npm install @modelcontextprotocol/sdk
```

--------------------------------

### Example API Key Format

Source: https://banksync.io/developers/guides/authentication

BankSync API keys start with `bsk_` followed by 44 random characters.

```text
bsk_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2
```

--------------------------------

### Install BankSync MCP Server via npm

Source: https://banksync.io/developers/mcp-setup/raycast

Use this JSON configuration to install the BankSync MCP server via the npm package. Copy this to your clipboard and use the 'Install Server' command in Raycast.

```json
{
  "command": "npx",
  "args": ["-y", "@banksync/mcp"],
  "env": {
    "BANKSYNC_API_KEY": "bsk_your_api_key_here"
  },
  "type": "stdio"
}
```

--------------------------------

### Install MCP Python SDK

Source: https://banksync.io/developers/mcp-setup/python

Install the official mcp Python package using pip. This is the first step to building your MCP client.

```bash
pip install mcp
```

--------------------------------

### Install BankSync MCP Package

Source: https://banksync.io/developers/mcp-setup/codex

If your AI client does not support remote HTTP servers, use the npm package to integrate BankSync. This command installs and runs the package.

```bash
npx -y @banksync/mcp

```

--------------------------------

### Install MCPHub.nvim Plugin

Source: https://banksync.io/developers/mcp-setup/neovim

Add this plugin specification to your Neovim configuration using lazy.nvim. Ensure plenary.nvim is listed as a dependency.

```lua
{
  "ravitemer/mcphub.nvim",
  dependencies = { "nvim-lua/plenary.nvim" },
  config = function()
    require("mcphub").setup()
  end,
}
```

--------------------------------

### Install BankSync MCP Package

Source: https://banksync.io/developers/mcp-setup/continue-dev

If your AI client does not support remote HTTP servers, you can use the npm package to integrate BankSync's MCP functionality.

```bash
npx -y @banksync/mcp
```

--------------------------------

### JavaScript Request with API Key

Source: https://banksync.io/developers/guides/authentication

Example JavaScript `fetch` request to retrieve banks using API key authentication. Store your API key securely, for example, in environment variables.

```javascript
const apiKey = 'bsk_your_api_key_here';

fetch('https://api.banksync.io/v1/banks', {
  method: 'GET',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

--------------------------------

### Get Workspace Details

Source: https://banksync.io/developers/mcp-tools/get-workspace

Fetches the name, subscription plan, and settings for a given workspace. Returns a 403 error if the user is not a member of the workspace.

```APIDOC
## Get Workspace

`get_workspace`

Get name, subscription plan, and settings for a workspace. Returns 403 if the user is not a member.

### Parameters

#### Path Parameters

- **workspaceId** (string) - Required - Workspace ID — get from `list_workspaces`
```

--------------------------------

### Python Request with API Key

Source: https://banksync.io/developers/guides/authentication

Example Python `requests` library usage for fetching banks with API key authentication. It's recommended to manage API keys using environment variables.

```python
import requests

api_key = 'bsk_your_api_key_here'
headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json'
}

response = requests.get('https://api.banksync.io/v1/banks', headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
```

--------------------------------

### Get Balance

Source: https://banksync.io/developers/mcp-tools/get-balance

Fetches the current live balance, available balance, and credit limit for a bank account. This data is not cached.

```APIDOC
## get_balance

### Description
Fetch the current live balance for an account directly from the institution — not cached. Returns current balance, available balance, and credit limit.

### Parameters
#### Path Parameters
- **workspaceId** (string) - required - Workspace ID — get from list_workspaces
- **bankId** (string) - required - Bank connection ID — get from list_banks
- **accountId** (string) - required - Account ID — get from list_accounts or get_bank
```

--------------------------------

### cURL Request with API Key

Source: https://banksync.io/developers/guides/authentication

Example cURL request to fetch banks using API key authentication. Ensure to replace `bsk_your_api_key_here` with your actual key.

```curl
curl -X GET "https://api.banksync.io/v1/banks" \
  -H "X-API-Key: bsk_your_api_key_here" \
  -H "Content-Type: application/json"
```

--------------------------------

### Make First API Call with cURL

Source: https://banksync.io/developers

Use this cURL command to list your connected banks. Replace 'bsk_your_api_key_here' with your actual API key.

```bash
curl -X GET https://api.banksync.io/v1/banks \
  -H "X-API-Key: bsk_your_api_key_here"
```

--------------------------------

### Configure Atlassian Rovo and BankSync in Claude Desktop

Source: https://banksync.io/developers/mcp-setup/atlassian-rovo

Set up Atlassian and BankSync MCP servers in `claude_desktop_config.json`. This configuration specifies the type and URL for each server, including the API key for BankSync.

```json
{
  "mcpServers": {
    "atlassian": {
      "type": "http",
      "url": "https://mcp.atlassian.com/v1/mcp"
    },
    "banksync": {
      "type": "http",
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Get Loan Details

Source: https://banksync.io/developers/mcp-tools/get-loan

Fetches the details for a specific loan or liability account.

```APIDOC
## Get Loan Details

### Description
Get loan details (outstanding balance, interest rate, next payment) for a loan or liability account.

### Method
`get_loan`

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - Workspace ID — get from list_workspaces
- **bankId** (string) - Required - Bank connection ID — get from list_banks
- **accountId** (string) - Required - Account ID — get from list_accounts or get_bank
```

--------------------------------

### Get Feed Configuration

Source: https://banksync.io/developers/mcp-tools/get-feed

Fetches the detailed configuration and current status of a specified feed pipeline.

```APIDOC
## get_feed

### Description
Get the full configuration and status of a specific feed pipeline, including sourceConfig, destinationConfig, fieldMappings, and schedule.

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - Workspace ID — get from list_workspaces
- **feedId** (string) - Required - Feed ID — get from list_feeds
```

--------------------------------

### Configure Notion and BankSync MCP Servers

Source: https://banksync.io/developers/mcp-setup/notion

Add both the Notion MCP server and BankSync to your AI client's configuration file. Ensure the `NOTION_TOKEN` and `X-API-Key` are correctly set.

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_your_notion_token_here"
      }
    },
    "banksync": {
      "type": "http",
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### get_trades

Source: https://banksync.io/developers/mcp-tools

Get investment transactions (buys, sells, dividends) for an investment account. Supports date filtering.

```APIDOC
## get_trades

### Description
Get investment transactions (buys, sells, dividends) for an investment account. Supports date filtering.

### Parameters
#### Path Parameters
- `workspaceId` (string) - Required - The workspace ID
- `bankId` (string) - Required - The bank connection ID
- `accountId` (string) - Required - The investment account ID

#### Query Parameters
- `from` (YYYY-MM-DD) - Optional - Start date for trade filter
- `to` (YYYY-MM-DD) - Optional - End date for trade filter
```

--------------------------------

### get_enrichment

Source: https://banksync.io/developers/mcp-tools

Get full details for a single enrichment including its rule conditions, alert destinations, or memory configuration.

```APIDOC
## get_enrichment

### Description
Get full details for a single enrichment including its rule conditions, alert destinations, or memory configuration.

### Parameters
#### Path Parameters
- `workspaceId` (string) - Required - The workspace ID
- `enrichmentId` (string) - Required - The enrichment ID
```

--------------------------------

### create_bank_link

Source: https://banksync.io/developers/mcp-tools/create-bank-link

Initiate a new bank connection. Returns a link token and hosted authorization URL. For Plaid: open authUrl in a browser. For SaltEdge/SnapTrade: open authUrl and follow the authorization flow.

```APIDOC
## create_bank_link

### Description
Initiate a new bank connection. Returns a link token and hosted authorization URL. For Plaid: open authUrl in a browser. For SaltEdge/SnapTrade: open authUrl and follow the authorization flow.

### Parameters
#### Path Parameters
- **workspaceId** (string) - required - Workspace ID — get from list_workspaces
- **source** (enum: 'plaid' | 'saltedge' | 'snaptrade') - required - Banking data provider. Use "plaid" for US/CA, "saltedge" for EU/AU/NZ.
- **institutionId** (string) - optional - Pre-select a specific institution. Omit to let the user search.
- **countryCodes** (string[]) - optional - ISO 3166-1 alpha-2 country codes, e.g. ["US", "CA"]
```

--------------------------------

### Get Enrichment Configuration

Source: https://banksync.io/developers/mcp-tools/get-enrichment

Fetches the complete configuration for a given enrichment, which can include rule configurations or alert configurations.

```APIDOC
## Get Enrichment

### Description
Get the full configuration of a specific enrichment, including ruleConfig or alertConfig.

### Method
GET

### Endpoint
`/enrichments/{enrichmentId}`

### Parameters
#### Query Parameters
- **workspaceId** (string) - Required - Workspace ID — get from `list_workspaces`
- **enrichmentId** (string) - Required - Enrichment ID — get from `list_enrichments`

### Response
#### Success Response (200)
- **enrichmentConfig** (object) - The full configuration of the enrichment.
  - **ruleConfig** (object) - Configuration for rule-based enrichments.
  - **alertConfig** (object) - Configuration for alert-based enrichments.

### Response Example
```json
{
  "enrichmentConfig": {
    "ruleConfig": {
      "conditions": [
        {
          "field": "transaction.amount",
          "operator": "gt",
          "value": 1000
        }
      ],
      "actions": [
        {
          "type": "flag",
          "reason": "High transaction amount"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Configure BankSync MCP Server in config.yaml

Source: https://banksync.io/developers/mcp-setup/continue-dev

Add this configuration to your `~/.continue/config.yaml` file to connect BankSync as an MCP server. Ensure your API key is correctly placed and that the `mcpServers` is a list.

```yaml
mcpServers:
  - name: BankSync
    type: streamable-http
    url: https://mcp.banksync.io
    requestOptions:
      headers:
        X-API-Key: bsk_your_api_key_here

```

--------------------------------

### Configure Atlassian Rovo and BankSync in Cursor

Source: https://banksync.io/developers/mcp-setup/atlassian-rovo

Add both Atlassian and BankSync MCP servers to your `.cursor/mcp.json` file. Ensure your BankSync API key is correctly placed in the headers.

```json
{
  "mcpServers": {
    "atlassian": {
      "url": "https://mcp.atlassian.com/v1/mcp"
    },
    "banksync": {
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### get_job

Source: https://banksync.io/developers/mcp-tools

Get the detailed status of a specific sync job including progress, row counts, errors, and timing information.

```APIDOC
## get_job

### Description
Get the detailed status of a specific sync job including progress, row counts, errors, and timing information.

### Parameters
#### Path Parameters
- `workspaceId` (string) - Required - The workspace ID
- `feedId` (string) - Required - The feed ID
- `jobId` (string) - Required - The job ID
```

--------------------------------

### Configure BankSync MCP Server in Zed

Source: https://banksync.io/developers/mcp-setup/zed

Add this configuration to your `~/.config/zed/settings.json` file to connect Zed to BankSync. Ensure you merge this into your existing settings, not replace them. Replace `bsk_your_api_key_here` with your actual BankSync API key.

```json
{
  "context_servers": {
    "banksync": {
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Configure BankSync MCP Server in librechat.yaml

Source: https://banksync.io/developers/mcp-setup/librechat

Add this configuration to your `librechat.yaml` file to integrate the BankSync MCP server. Ensure you replace `bsk_your_api_key_here` with your actual BankSync API key.

```yaml
mcpServers:
  banksync:
    type: streamable-http
    url: https://mcp.banksync.io
    headers:
      X-API-Key: "bsk_your_api_key_here"
```

--------------------------------

### Get Account

Source: https://banksync.io/developers/mcp-tools/get-account

Fetches a single account's current details. Returns accountType, balance, currency, and institution name.

```APIDOC
## Get Account

### Description
Fetch a single account's current details directly from the institution. Returns accountType, balance, currency, and institution name.

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - Workspace ID — get from list_workspaces
- **bankId** (string) - Required - Bank connection ID — get from list_banks
- **accountId** (string) - Required - Account ID — get from list_accounts or get_bank
```

--------------------------------

### get_feed

Source: https://banksync.io/developers/mcp-tools

Get the full configuration and status of a feed including source config, destination config, field mappings, and sync schedule.

```APIDOC
## get_feed

### Description
Get the full configuration and status of a feed including source config, destination config, field mappings, and sync schedule.

### Parameters
#### Path Parameters
- `workspaceId` (string) - Required - The workspace ID
- `feedId` (string) - Required - The feed ID
```

--------------------------------

### Configure BankSync using npm Package as Local stdio Bridge for Amp

Source: https://banksync.io/developers/mcp-setup/amp

Use the @banksync/mcp npm package as a local stdio bridge for Amp. This method is useful if your client does not support remote HTTP servers. Configure the command, arguments, and environment variables for the npm package.

```json
{
  "amp.mcpServers": {
    "banksync": {
      "command": "npx",
      "args": ["-y", "@banksync/mcp"],
      "env": {
        "BANKSYNC_API_KEY": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### get_loan

Source: https://banksync.io/developers/mcp-tools

Get loan details for a loan or liability account including principal, interest rate, maturity date, and payment schedule.

```APIDOC
## get_loan

### Description
Get loan details for a loan or liability account including principal, interest rate, maturity date, and payment schedule.

### Parameters
#### Path Parameters
- `workspaceId` (string) - Required - The workspace ID
- `bankId` (string) - Required - The bank connection ID
- `accountId` (string) - Required - The loan account ID
```

--------------------------------

### Configure BankSync MCP Server via npm Package

Source: https://banksync.io/developers/mcp-setup/vscode

Use this `.vscode/mcp.json` configuration to connect to the BankSync MCP server via the `@banksync/mcp` npm package. This method bridges stdio to the remote server.

```json
{
  "servers": {
    "banksync": {
      "command": "npx",
      "args": ["-y", "@banksync/mcp"],
      "env": {
        "BANKSYNC_API_KEY": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Get Job

Source: https://banksync.io/developers/mcp-tools/get-job

Retrieves the current status and progress of a specific sync job. This endpoint should be polled after triggering a sync to track its completion.

```APIDOC
## get_job

### Description
Get current status and progress of a specific sync job. Poll this after trigger_sync to track completion.

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - Workspace ID — get from list_workspaces
- **feedId** (string) - Required - Feed ID — get from list_feeds
- **jobId** (string) - Required - Job ID — get from trigger_sync or list_jobs
```

--------------------------------

### Add BankSync Server via Config File

Source: https://banksync.io/developers/mcp-setup/copilot-cli

Configure BankSync as an MCP server by editing the `~/.copilot/mcp-config.json` file. Ensure the JSON is valid and includes your API key.

```json
{
  "mcpServers": {
    "banksync": {
      "type": "http",
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      },
      "tools": ["*"]
    }
  }
}
```

--------------------------------

### Configure BankSync MCP Server in Gemini CLI

Source: https://banksync.io/developers/mcp-setup/gemini-cli

Add this configuration to your Gemini CLI settings file to connect to BankSync. Ensure you replace 'bsk_your_api_key_here' with your actual BankSync API key. Use httpUrl for Streamable HTTP transport.

```json
{
  "mcpServers": {
    "banksync": {
      "httpUrl": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Configure BankSync MCP Server in Codex

Source: https://banksync.io/developers/mcp-setup/codex

Add this TOML configuration to your Codex config file to connect to the BankSync MCP server. Replace 'bsk_your_api_key_here' with your actual BankSync API key.

```toml
[mcp_servers.banksync]
url = "https://mcp.banksync.io"


[mcp_servers.banksync.http_headers]
X-API-Key = "bsk_your_api_key_here"

```

--------------------------------

### Get Bank Connection

Source: https://banksync.io/developers/mcp-tools/get-bank

Fetches a bank connection and its live accounts directly from the institution. It returns the bank ID, institution name, and a list of accounts with their respective account IDs and types.

```APIDOC
## get_bank

### Description
Get a bank connection and its live accounts fetched directly from the institution. Returns bankId, institution name, and accounts with accountId and accountType.

### Parameters
#### Path Parameters
- **workspaceId** (string) - Required - Workspace ID — get from list_workspaces
- **bankId** (string) - Required - Bank connection ID — get from list_banks
```

--------------------------------

### Configure BankSync MCP Server in Tabnine

Source: https://banksync.io/developers/mcp-setup/tabnine

Add BankSync as an MCP server to your Tabnine configuration. Ensure the API key is correctly placed under `requestInit.headers`.

```json
{
  "mcpServers": {
    "banksync": {
      "url": "https://mcp.banksync.io",
      "requestInit": {
        "headers": {
          "X-API-Key": "bsk_your_api_key_here"
        }
      }
    }
  }
}
```

--------------------------------

### Get Transactions

Source: https://banksync.io/developers/mcp-tools/get-transactions

Fetches bank transactions for a given account. Supports incremental sync with Plaid using a cursor or date range filtering for SaltEdge/SnapTrade. Returns up to 500 transactions per call.

```APIDOC
## get_transactions

### Description
Fetch bank transactions for an account. For Plaid: use cursor for incremental sync. For SaltEdge/SnapTrade: use from/to date range. Returns up to 500 transactions per call.

### Parameters
#### Path Parameters
- `workspaceId` (string) - Required - Workspace ID — get from list_workspaces
- `bankId` (string) - Required - Bank connection ID — get from list_banks
- `accountId` (string) - Required - Account ID — get from list_accounts or get_bank

#### Query Parameters
- `from` (string) - Optional - Start date YYYY-MM-DD
- `to` (string) - Optional - End date YYYY-MM-DD
- `cursor` (string) - Optional - Plaid cursor for incremental sync
```

--------------------------------

### Configure MCP Servers in .cursor/mcp.json

Source: https://banksync.io/developers/mcp-setup/pieces

Add both Pieces and BankSync MCP servers to your AI client's configuration file. Ensure PiecesOS is running locally.

```json
{
  "mcpServers": {
    "pieces": {
      "url": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
    },
    "banksync": {
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### get_data_type_schema

Source: https://banksync.io/developers/mcp-tools/get-data-type-schema

Get the available source fields for a given data type — use this before building fieldMappings in create_feed or update_feed. Returns each field's key, name, type, description, and whether it is required.

```APIDOC
## get_data_type_schema

### Description
Get the available source fields for a given data type — use this before building fieldMappings in create_feed or update_feed. Returns each field's key, name, type, description, and whether it is required.

### Parameters
#### Query Parameters
- **dataType** (enum) - Required - The data type to get the field schema for: transactions, balances, trades, holdings, or loans.
```

--------------------------------

### Configure BankSync as Streamable HTTP MCP Server

Source: https://banksync.io/developers/mcp-setup/roo-code

Add BankSync as a 'streamable-http' type MCP server in your global or project-level Roo Code configuration. Ensure your API key is correctly placed in the headers. This setup is suitable for direct HTTP connections.

```json
{
  "mcpServers": {
    "banksync": {
      "type": "streamable-http",
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### get_workspace

Source: https://banksync.io/developers/mcp-tools

Retrieves the name, subscription plan, and settings for a specific workspace.

```APIDOC
## get_workspace

### Description
Get name, subscription plan, and settings for a workspace.

### Parameters
#### Input Parameters
- `workspaceId` (string) - required - The workspace ID.
```

--------------------------------

### Configure BankSync MCP Server in Cline

Source: https://banksync.io/developers/mcp-setup/cline

Add this configuration to your `cline_mcp_settings.json` file to connect Cline to the BankSync MCP server. Ensure you replace `bsk_your_api_key_here` with your actual BankSync API key.

```json
{
  "mcpServers": {
    "banksync": {
      "url": "https://mcp.banksync.io",
      "headers": {
        "X-API-Key": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Connect to BankSync with TypeScript SDK

Source: https://banksync.io/developers/mcp-setup/typescript

Initialize the BankSync client, establish a connection using StreamableHTTPClientTransport with your API key, and list available tools. Ensure your API key is valid and has the necessary scopes.

```typescript
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://mcp.banksync.io'),
  { requestInit: { headers: { 'X-API-Key': 'bsk_your_api_key_here' } } }
);

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();
console.log(`Connected! ${tools.length} tools available`);

// Call a tool
const result = await client.callTool({
  name: 'list_workspaces',
  arguments: {},
});
console.log(result);
```

--------------------------------

### Configure BankSync as a Local MCP Server (npm Package) in Kilo Code

Source: https://banksync.io/developers/mcp-setup/kilo-code

Integrate BankSync as a local MCP server using the @banksync/mcp npm package. This method uses a command to launch the package and requires the API key to be set in the environment variables.

```jsonc
{
  "mcp": {
    "banksync": {
      "type": "local",
      "command": ["npx", "-y", "@banksync/mcp"],
      "environment": {
        "BANKSYNC_API_KEY": "bsk_your_api_key_here"
      },
      "enabled": true
    }
  }
}
```

--------------------------------

### Configure Local MCP Bridge with npm Package

Source: https://banksync.io/developers/mcp-setup/claude-desktop

Use this configuration in claude_desktop_config.json if your Claude Desktop version does not support remote HTTP servers. It sets up the @banksync/mcp npm package as a local bridge.

```json
{
  "mcpServers": {
    "banksync": {
      "command": "npx",
      "args": ["-y", "@banksync/mcp"],
      "env": {
        "BANKSYNC_API_KEY": "bsk_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### create_bank_link

Source: https://banksync.io/developers/mcp-tools

Initiates a new bank connection via Plaid, SaltEdge, or SnapTrade, returning a link token or connection URL to be completed in the BankSync app.

```APIDOC
## create_bank_link

### Description
Initiate a new bank connection via Plaid, SaltEdge, or SnapTrade. Returns a link token or connection URL that must be completed in the BankSync app.

### Parameters
#### Input Parameters
- `workspaceId` (string) - required - The workspace ID.
- `source` (enum: plaid | saltedge | snaptrade) - required - The open finance provider to use.
- `institutionId` (string) - optional - Pre-select a specific institution.
- `countryCodes` (string[]) - optional - Limit to specific countries (e.g., US, CA, AU).
```