// REST API

FINTECH_API_DOCS

Read-only financial data endpoints. Connect your AI agent, scripts, or tools to your live account data.

OVERVIEW

FINTECH_MCP is a read-only financial data platform that connects your bank and investment accounts to AI agents via the Model Context Protocol (MCP) and a standard REST API.

After linking your accounts through the dashboard, any MCP-compatible AI assistant (Claude, Cursor, etc.) or your own scripts can query your live balances, transaction history, and investment holdings — without ever getting write access to your accounts.

The REST API is what the MCP server calls internally. You can call it directly too, using the same API keys you generate in your dashboard. The five MCP tools map directly to these endpoints:

MCP Tool REST Endpoint Plan
fintech_accounts_list GET /api/v1/accounts All
fintech_transactions_list GET /api/v1/transactions All
fintech_spending_by_category GET /api/v1/spending/by-category All
fintech_investment_holdings_list GET /api/v1/investments/holdings Pro
fintech_investment_transactions_list GET /api/v1/investments/transactions Pro
BASE_URL
https://www.fintechmcp.app/api/v1
AUTH_METHOD
Bearer token (Authorization header)
FORMAT
JSON — all responses are application/json

AUTHENTICATION

All endpoints require a Bearer token in the Authorization header. Tokens are created in your dashboard under the API Keys section.

API keys are prefixed with ftm_.

Request Header
http
Authorization: Bearer ftm_your_api_key_here
Example with curl
bash
curl https://www.fintechmcp.app/api/v1/accounts \
  -H "Authorization: Bearer ftm_your_api_key_here"
// UNAUTHORIZED — 401
Requests without a valid token receive a 401 Unauthorized response with a WWW-Authenticate header pointing to the OAuth discovery endpoint. MCP clients use this to initiate the OAuth 2.1 login flow automatically.

ERROR_CODES

All errors return JSON with an error field describing the problem.
Param Type Required Description
200 OK no Request succeeded. Response body contains the data.
401 Unauthorized no Missing or invalid Bearer token.
403 Forbidden no Valid token but your plan does not include this endpoint.
500 Server Error no Internal error. Try again or contact support.
Example error response
json
{
  "error": "Investment data requires the Pro plan."
}
GET /api/v1/accounts

GET_ACCOUNTS

Returns all bank and financial accounts linked to your profile, along with their latest cached balance. Balances are refreshed on each Plaid sync — they are not fetched live on every request.
Example Request
bash
curl https://www.fintechmcp.app/api/v1/accounts \
  -H "Authorization: Bearer ftm_..."
Example Response
json
{
  "count": 2,
  "accounts": [
    {
      "id": "01961a2b-...",
      "name": "Chase Checking",
      "official_name": "CHASE TOTAL CHECKING",
      "mask": "4242",
      "type": "depository",
      "subtype": "checking",
      "institution": "Chase",
      "balance": {
        "current": 3412.88,
        "available": 3312.88,
        "limit": null,
        "iso_currency_code": "USD",
        "fetched_at": "2026-03-12T08:00:00.000Z"
      }
    },
    {
      "id": "01961a2c-...",
      "name": "Citi Double Cash",
      "official_name": "CITI DOUBLE CASH CARD",
      "mask": "1234",
      "type": "credit",
      "subtype": "credit card",
      "institution": "Citibank",
      "balance": {
        "current": -842.50,
        "available": 9157.50,
        "limit": 10000.00,
        "iso_currency_code": "USD",
        "fetched_at": "2026-03-12T08:00:00.000Z"
      }
    }
  ]
}
GET /api/v1/transactions

GET_TRANSACTIONS

Returns a paginated list of bank transactions. The response also includes the full accounts list for convenient cross-referencing by AI agents.
Query Parameters
Param Type Required Description
account_id string no Filter results to a single account by its ID.
start_date YYYY-MM-DD no Return only transactions on or after this date.
end_date YYYY-MM-DD no Return only transactions on or before this date.
limit integer no Max results per page. Min 1, max 500, default 100.
offset integer no Number of records to skip for pagination. Default 0.
Example Request
bash
curl "https://www.fintechmcp.app/api/v1/transactions?start_date=2026-03-01&limit=5" \
  -H "Authorization: Bearer ftm_..."
Example Response
json
{
  "count": 2,
  "offset": 0,
  "limit": 5,
  "accounts": [ ... ],
  "transactions": [
    {
      "id": "01961b00-...",
      "account_id": "01961a2b-...",
      "account": { "name": "Chase Checking", ... },
      "plaid_transaction_id": "abc123xyz",
      "amount": 4.50,
      "iso_currency_code": "USD",
      "date": "2026-03-11",
      "name": "STARBUCKS #12345",
      "merchant_name": "Starbucks",
      "category": "Food and Drink",
      "subcategory": "Coffee Shop",
      "pending": false
    },
    {
      "id": "01961b01-...",
      "account_id": "01961a2b-...",
      "account": { "name": "Chase Checking", ... },
      "plaid_transaction_id": "def456uvw",
      "amount": 128.40,
      "iso_currency_code": "USD",
      "date": "2026-03-10",
      "name": "WHOLE FOODS MKT",
      "merchant_name": "Whole Foods Market",
      "category": "Shops",
      "subcategory": "Groceries",
      "pending": false
    }
  ]
}
// NOTE: Positive amount = money leaving your account (debit/purchase). Negative = money entering (credit/refund).
GET /api/v1/spending/by-category

GET_SPENDING_BY_CATEGORY

Returns total spending grouped by category for a given date range, excluding pending transactions and negative-amount entries (income, payroll, refunds). Results are sorted by total_spending descending. Defaults to the last 30 days if no dates are provided.
Query Parameters
Param Type Required Description
start_date YYYY-MM-DD no Start of the date range. Defaults to 30 days before end_date.
end_date YYYY-MM-DD no End of the date range. Defaults to today.
Example Request
bash
curl "https://www.fintechmcp.app/api/v1/spending/by-category?start_date=2026-03-01&end_date=2026-03-31" \
  -H "Authorization: Bearer ftm_..."
Example Response
json
{
  "start_date": "2026-03-01",
  "end_date": "2026-03-31",
  "count": 3,
  "spending_by_category": [
    {
      "category": "Food and Drink",
      "total_spending": 284.50,
      "transaction_count": 12,
      "iso_currency_code": "USD"
    },
    {
      "category": "Shops",
      "total_spending": 178.20,
      "transaction_count": 5,
      "iso_currency_code": "USD"
    },
    {
      "category": "Travel",
      "total_spending": 94.00,
      "transaction_count": 2,
      "iso_currency_code": "USD"
    }
  ]
}
GET /api/v1/investments/holdings

GET_INVESTMENT_HOLDINGS

Requires PRO plan
Returns all current investment holdings across linked brokerage and retirement accounts, including quantities, current prices, and total values. Returns 403 if the authenticated user is not on the Pro plan.
Example Request
bash
curl https://www.fintechmcp.app/api/v1/investments/holdings \
  -H "Authorization: Bearer ftm_..."
Example Response
json
{
  "count": 2,
  "accounts": [
    {
      "id": "01961a2d-...",
      "name": "Fidelity Brokerage",
      "type": "investment",
      "subtype": "brokerage",
      "institution": "Fidelity",
      "balance": {
        "current": 48200.00,
        "available": null,
        "limit": null,
        "iso_currency_code": "USD",
        "fetched_at": "2026-03-12T08:00:00.000Z"
      }
    }
  ],
  "holdings": [
    {
      "id": "01961b10-...",
      "account_id": "01961a2d-...",
      "account": { "name": "Fidelity Brokerage", ... },
      "ticker_symbol": "VTI",
      "security_name": "Vanguard Total Stock Market ETF",
      "security_type": "etf",
      "quantity": 120.5,
      "institution_value": 28680.00,
      "institution_price": 238.01,
      "iso_currency_code": "USD",
      "fetched_at": "2026-03-12T08:00:00.000Z"
    },
    {
      "id": "01961b11-...",
      "account_id": "01961a2d-...",
      "account": { "name": "Fidelity Brokerage", ... },
      "ticker_symbol": "FXAIX",
      "security_name": "Fidelity 500 Index Fund",
      "security_type": "mutual fund",
      "quantity": 98.2,
      "institution_value": 19520.00,
      "institution_price": 198.78,
      "iso_currency_code": "USD",
      "fetched_at": "2026-03-12T08:00:00.000Z"
    }
  ]
}
GET /api/v1/investments/transactions

GET_INVESTMENT_TRANSACTIONS

Requires PRO plan
Returns a paginated list of investment transactions — buys, sells, dividends, transfers, and more. Returns 403 if the authenticated user is not on the Pro plan.
Query Parameters
Param Type Required Description
account_id string no Filter results to a single investment account by its ID.
limit integer no Max results per page. Min 1, max 500, default 100.
offset integer no Number of records to skip for pagination. Default 0.
Example Request
bash
curl "https://www.fintechmcp.app/api/v1/investments/transactions?limit=3" \
  -H "Authorization: Bearer ftm_..."
Example Response
json
{
  "count": 2,
  "offset": 0,
  "limit": 3,
  "accounts": [ ... ],
  "transactions": [
    {
      "id": "01961b20-...",
      "account_id": "01961a2d-...",
      "account": { "name": "Fidelity Brokerage", ... },
      "ticker_symbol": "VTI",
      "security_name": "Vanguard Total Stock Market ETF",
      "type": "buy",
      "subtype": "buy",
      "quantity": 10.0,
      "amount": 2380.10,
      "price": 238.01,
      "fees": 0.00,
      "iso_currency_code": "USD",
      "date": "2026-03-05",
      "name": "BUY VTI"
    },
    {
      "id": "01961b21-...",
      "account_id": "01961a2d-...",
      "account": { "name": "Fidelity Brokerage", ... },
      "ticker_symbol": "FXAIX",
      "security_name": "Fidelity 500 Index Fund",
      "type": "dividend",
      "subtype": "qualified dividend",
      "quantity": null,
      "amount": -42.18,
      "price": null,
      "fees": null,
      "iso_currency_code": "USD",
      "date": "2026-03-01",
      "name": "DIVIDEND FXAIX"
    }
  ]
}
// TRANSACTION TYPES: Common values for type include buy, sell, dividend, transfer, fee, cash. Positive amount = outflow (buy/fee); negative = inflow (sell/dividend).