Developer Documentation

Build custom integrations with the NYX Finance API. Pull your accounts, transactions, holdings, and net worth into your own tools — or let an LLM do it for you via our MCP server.

Base URLhttps://nyxfinance.app/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. API keys start with nyx_sk_ and are scoped to your account.

Example

curl https://nyxfinance.app/api/v1/accounts \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Create and manage your API keys at Dashboard → Settings → API Keys.

Security Best Practices

• Never commit API keys to version control. Use environment variables.
• Rotate keys regularly — especially if you suspect a leak.
• Use separate keys for development and production.
• Revoke unused keys from your dashboard immediately.

Rate Limits

The API allows 60 requests per minute per API key. Exceeding this limit returns a 429 status code. Rate limit headers are included in every response.

429 Response

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait 23 seconds before retrying.",
    "retryAfter": 23
  }
}

Errors

All errors follow a consistent JSON envelope. The code field is a machine-readable constant; the message field is a human-readable explanation.

Error Envelope

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account with ID abc-123 not found."
  }
}

Status	Code	Description
400	`BAD_REQUEST`	Invalid or missing request parameters
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	API key lacks permission for this resource
404	`NOT_FOUND`	Resource does not exist
429	`RATE_LIMITED`	Too many requests — slow down
500	`INTERNAL_ERROR`	Something broke on our end — sorry about that

Accounts

GET/accounts

List all accounts linked to your NYX profile.

Request

curl https://nyxfinance.app/api/v1/accounts \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "acc_01HQ...",
      "name": "Chase Checking",
      "type": "checking",
      "balanceCurrent": 4521.33,
      "balanceAvailable": 4521.33,
      "currency": "USD",
      "institution": "Chase",
      "mask": "4892",
      "ownership": "mine",
      "createdAt": "2025-11-14T08:30:00Z"
    }
  ],
  "total": 7
}

GET/accounts/:id

Retrieve a single account by ID.

Request

curl https://nyxfinance.app/api/v1/accounts/acc_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": {
    "id": "acc_01HQ...",
    "name": "Chase Checking",
    "type": "checking",
    "balanceCurrent": 4521.33,
    "balanceAvailable": 4521.33,
    "currency": "USD",
    "institution": "Chase",
    "mask": "4892",
    "ownership": "mine",
    "createdAt": "2025-11-14T08:30:00Z"
  }
}

Transactions

GET/transactions

List transactions with optional filters. Results are paginated (default 50, max 200).

Query Parameters

accountId— Filter by account UUID

categoryId— Filter by category UUID

search— Full-text search on merchant name

dateFrom— Start date (YYYY-MM-DD)

dateTo— End date (YYYY-MM-DD)

minAmount— Minimum absolute amount

maxAmount— Maximum absolute amount

limit— Results per page (default 50, max 200)

offset— Pagination offset

Request

curl "https://nyxfinance.app/api/v1/transactions?accountId=acc_01HQ...&limit=10" \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "txn_01HQ...",
      "accountId": "acc_01HQ...",
      "date": "2026-02-25",
      "merchantName": "Trader Joe's",
      "amount": -47.82,
      "category": "Groceries",
      "pending": false,
      "tags": ["essentials"]
    }
  ],
  "total": 342,
  "limit": 10,
  "offset": 0
}

POST/transactions

Create a manual transaction.

Request

curl -X POST https://nyxfinance.app/api/v1/transactions \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_01HQ...",
    "date": "2026-02-25",
    "merchantName": "Coffee Shop",
    "amount": -5.50,
    "categoryId": "cat_01HQ..."
  }'

Response

{
  "data": {
    "id": "txn_01HQ...",
    "accountId": "acc_01HQ...",
    "date": "2026-02-25",
    "merchantName": "Coffee Shop",
    "amount": -5.50,
    "category": "Food & Drink",
    "pending": false,
    "tags": []
  }
}

PUT/transactions/:id

Update an existing transaction. Only mutable fields can be changed (merchant name, category, tags, notes).

Request

curl -X PUT https://nyxfinance.app/api/v1/transactions/txn_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Fancy Coffee Shop",
    "categoryId": "cat_01HQ...",
    "tags": ["treats"]
  }'

Response

{
  "data": {
    "id": "txn_01HQ...",
    "merchantName": "Fancy Coffee Shop",
    "category": "Food & Drink",
    "tags": ["treats"]
  }
}

DELETE/transactions/:id

Delete a transaction. Only manually-created transactions can be deleted.

Request

curl -X DELETE https://nyxfinance.app/api/v1/transactions/txn_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "success": true
}

Budgets

GET/budgets

List all budgets with current spending progress.

Request

curl https://nyxfinance.app/api/v1/budgets \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "bgt_01HQ...",
      "name": "February 2026",
      "period": "monthly",
      "totalLimit": 3000.00,
      "totalSpent": 1847.22,
      "startDate": "2026-02-01",
      "endDate": "2026-02-28",
      "categories": [
        {
          "categoryId": "cat_01HQ...",
          "name": "Groceries",
          "limit": 600.00,
          "spent": 412.33
        }
      ]
    }
  ],
  "total": 3
}

GET/budgets/:id

Get detailed budget information including category breakdowns.

Request

curl https://nyxfinance.app/api/v1/budgets/bgt_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": {
    "id": "bgt_01HQ...",
    "name": "February 2026",
    "period": "monthly",
    "totalLimit": 3000.00,
    "totalSpent": 1847.22,
    "startDate": "2026-02-01",
    "endDate": "2026-02-28",
    "rollover": true,
    "categories": [
      {
        "categoryId": "cat_01HQ...",
        "name": "Groceries",
        "limit": 600.00,
        "spent": 412.33,
        "rolloverAmount": 42.10
      }
    ]
  }
}

Goals

GET/goals

List all savings goals.

Request

curl https://nyxfinance.app/api/v1/goals \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "goal_01HQ...",
      "name": "Emergency Fund",
      "targetAmount": 15000.00,
      "currentAmount": 8200.00,
      "targetDate": "2026-12-31",
      "linkedAccountId": "acc_01HQ...",
      "percentComplete": 54.67
    }
  ],
  "total": 2
}

POST/goals

Create a new savings goal.

Request

curl -X POST https://nyxfinance.app/api/v1/goals \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vacation Fund",
    "targetAmount": 5000.00,
    "targetDate": "2026-08-01"
  }'

Response

{
  "data": {
    "id": "goal_01HQ...",
    "name": "Vacation Fund",
    "targetAmount": 5000.00,
    "currentAmount": 0,
    "targetDate": "2026-08-01",
    "percentComplete": 0
  }
}

PUT/goals/:id

Update an existing goal.

Request

curl -X PUT https://nyxfinance.app/api/v1/goals/goal_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "targetAmount": 6000.00,
    "currentAmount": 1500.00
  }'

Response

{
  "data": {
    "id": "goal_01HQ...",
    "name": "Vacation Fund",
    "targetAmount": 6000.00,
    "currentAmount": 1500.00,
    "targetDate": "2026-08-01",
    "percentComplete": 25.00
  }
}

Investments

GET/investments/holdings

List all investment holdings (stocks, ETFs, mutual funds, bonds).

Request

curl https://nyxfinance.app/api/v1/investments/holdings \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "hold_01HQ...",
      "accountId": "acc_01HQ...",
      "symbol": "VTI",
      "name": "Vanguard Total Stock Market ETF",
      "quantity": 42.5,
      "costBasis": 8925.00,
      "currentPrice": 245.30,
      "marketValue": 10425.25,
      "gainLoss": 1500.25,
      "gainLossPercent": 16.81
    }
  ],
  "total": 12
}

POST/investments/holdings

Add a manual investment holding.

Request

curl -X POST https://nyxfinance.app/api/v1/investments/holdings \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_01HQ...",
    "symbol": "AAPL",
    "quantity": 10,
    "costBasis": 1750.00
  }'

Response

{
  "data": {
    "id": "hold_01HQ...",
    "symbol": "AAPL",
    "quantity": 10,
    "costBasis": 1750.00
  }
}

PUT/investments/holdings/:id

Update a manual investment holding.

Request

curl -X PUT https://nyxfinance.app/api/v1/investments/holdings/hold_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 15, "costBasis": 2625.00 }'

Response

{
  "data": {
    "id": "hold_01HQ...",
    "symbol": "AAPL",
    "quantity": 15,
    "costBasis": 2625.00
  }
}

DELETE/investments/holdings/:id

Delete a manual investment holding.

Request

curl -X DELETE https://nyxfinance.app/api/v1/investments/holdings/hold_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "success": true
}

Crypto

GET/crypto/holdings

List all cryptocurrency holdings with live prices.

Request

curl https://nyxfinance.app/api/v1/crypto/holdings \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "cry_01HQ...",
      "symbol": "BTC",
      "name": "Bitcoin",
      "quantity": 0.45,
      "costBasis": 28000.00,
      "currentPrice": 84521.00,
      "marketValue": 38034.45,
      "gainLoss": 10034.45,
      "gainLossPercent": 35.84
    }
  ],
  "total": 4
}

POST/crypto/holdings

Add a crypto holding.

Request

curl -X POST https://nyxfinance.app/api/v1/crypto/holdings \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "ETH",
    "quantity": 5.0,
    "costBasis": 15000.00
  }'

Response

{
  "data": {
    "id": "cry_01HQ...",
    "symbol": "ETH",
    "quantity": 5.0,
    "costBasis": 15000.00
  }
}

PUT/crypto/holdings/:id

Update a crypto holding.

Request

curl -X PUT https://nyxfinance.app/api/v1/crypto/holdings/cry_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 7.5, "costBasis": 22500.00 }'

Response

{
  "data": {
    "id": "cry_01HQ...",
    "symbol": "ETH",
    "quantity": 7.5,
    "costBasis": 22500.00
  }
}

DELETE/crypto/holdings/:id

Delete a crypto holding.

Request

curl -X DELETE https://nyxfinance.app/api/v1/crypto/holdings/cry_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "success": true
}

Metals

GET/metals/holdings

List all precious metals holdings with current spot prices.

Request

curl https://nyxfinance.app/api/v1/metals/holdings \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "mtl_01HQ...",
      "metal": "gold",
      "weightOz": 10.0,
      "costBasisPerOz": 1850.00,
      "totalCostBasis": 18500.00,
      "spotPrice": 2045.30,
      "marketValue": 20453.00,
      "gainLoss": 1953.00,
      "gainLossPercent": 10.56
    }
  ],
  "total": 2
}

POST/metals/holdings

Add a precious metals holding.

Request

curl -X POST https://nyxfinance.app/api/v1/metals/holdings \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "metal": "silver",
    "weightOz": 100.0,
    "costBasisPerOz": 23.50
  }'

Response

{
  "data": {
    "id": "mtl_01HQ...",
    "metal": "silver",
    "weightOz": 100.0,
    "costBasisPerOz": 23.50,
    "totalCostBasis": 2350.00
  }
}

PUT/metals/holdings/:id

Update a precious metals holding.

Request

curl -X PUT https://nyxfinance.app/api/v1/metals/holdings/mtl_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "weightOz": 150.0 }'

Response

{
  "data": {
    "id": "mtl_01HQ...",
    "metal": "silver",
    "weightOz": 150.0,
    "costBasisPerOz": 23.50,
    "totalCostBasis": 3525.00
  }
}

DELETE/metals/holdings/:id

Delete a precious metals holding.

Request

curl -X DELETE https://nyxfinance.app/api/v1/metals/holdings/mtl_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "success": true
}

Real Estate

GET/real-estate

List all real estate properties.

Request

curl https://nyxfinance.app/api/v1/real-estate \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "re_01HQ...",
      "name": "Primary Residence",
      "estimatedValue": 450000.00,
      "outstandingMortgage": 280000.00,
      "equity": 170000.00,
      "address": "123 Main St",
      "propertyType": "single_family"
    }
  ],
  "total": 1
}

POST/real-estate

Add a real estate property.

Request

curl -X POST https://nyxfinance.app/api/v1/real-estate \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rental Property",
    "estimatedValue": 320000.00,
    "outstandingMortgage": 240000.00,
    "propertyType": "single_family"
  }'

Response

{
  "data": {
    "id": "re_01HQ...",
    "name": "Rental Property",
    "estimatedValue": 320000.00,
    "outstandingMortgage": 240000.00,
    "equity": 80000.00,
    "propertyType": "single_family"
  }
}

PUT/real-estate/:id

Update a real estate property.

Request

curl -X PUT https://nyxfinance.app/api/v1/real-estate/re_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "estimatedValue": 465000.00 }'

Response

{
  "data": {
    "id": "re_01HQ...",
    "name": "Primary Residence",
    "estimatedValue": 465000.00,
    "outstandingMortgage": 280000.00,
    "equity": 185000.00
  }
}

Other Assets

GET/other-assets

List all other tracked assets (vehicles, collectibles, etc.).

Request

curl https://nyxfinance.app/api/v1/other-assets \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "oa_01HQ...",
      "name": "2022 Toyota 4Runner",
      "category": "vehicle",
      "estimatedValue": 38000.00,
      "purchasePrice": 45000.00,
      "purchaseDate": "2022-03-15"
    }
  ],
  "total": 2
}

POST/other-assets

Add another tracked asset.

Request

curl -X POST https://nyxfinance.app/api/v1/other-assets \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Watch Collection",
    "category": "collectible",
    "estimatedValue": 12000.00,
    "purchasePrice": 8500.00
  }'

Response

{
  "data": {
    "id": "oa_01HQ...",
    "name": "Watch Collection",
    "category": "collectible",
    "estimatedValue": 12000.00,
    "purchasePrice": 8500.00
  }
}

PUT/other-assets/:id

Update an other asset.

Request

curl -X PUT https://nyxfinance.app/api/v1/other-assets/oa_01HQ... \
  -H "Authorization: Bearer nyx_sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "estimatedValue": 40000.00 }'

Response

{
  "data": {
    "id": "oa_01HQ...",
    "name": "2022 Toyota 4Runner",
    "estimatedValue": 40000.00
  }
}

Recurring

GET/recurring

List all detected recurring transactions (subscriptions, bills, paychecks).

Request

curl https://nyxfinance.app/api/v1/recurring \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "id": "rec_01HQ...",
      "merchantName": "Netflix",
      "amount": -15.49,
      "frequency": "monthly",
      "lastDate": "2026-02-01",
      "nextExpectedDate": "2026-03-01",
      "category": "Entertainment",
      "isActive": true
    }
  ],
  "total": 14
}

Net Worth

GET/net-worth

Get your current net worth breakdown.

Request

curl https://nyxfinance.app/api/v1/net-worth \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": {
    "netWorth": 287450.33,
    "totalAssets": 412300.33,
    "totalLiabilities": 124850.00,
    "breakdown": {
      "cash": 24521.33,
      "investments": 142500.00,
      "crypto": 38034.45,
      "metals": 20453.00,
      "realEstate": 170000.00,
      "otherAssets": 16791.55,
      "creditCards": -4850.00,
      "loans": -120000.00
    },
    "asOf": "2026-02-27T02:00:00Z"
  }
}

GET/net-worth/history

Get historical net worth snapshots.

Query Parameters

days— Number of days of history (default 30, max 365)

Request

curl "https://nyxfinance.app/api/v1/net-worth/history?days=90" \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "date": "2026-02-27",
      "netWorth": 287450.33,
      "totalAssets": 412300.33,
      "totalLiabilities": 124850.00
    },
    {
      "date": "2026-02-26",
      "netWorth": 286210.12,
      "totalAssets": 411100.12,
      "totalLiabilities": 124890.00
    }
  ],
  "total": 90
}

Reports

GET/reports/cashflow

Get income vs. expense cash flow data by month.

Query Parameters

months— Number of months (default 6, max 24)

Request

curl "https://nyxfinance.app/api/v1/reports/cashflow?months=3" \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "month": "2026-02",
      "income": 6500.00,
      "expenses": 4200.33,
      "net": 2299.67
    },
    {
      "month": "2026-01",
      "income": 6500.00,
      "expenses": 3890.12,
      "net": 2609.88
    }
  ]
}

GET/reports/spending

Get spending breakdown grouped by category, merchant, or tag.

Query Parameters

dateFrom— Start date (YYYY-MM-DD)

dateTo— End date (YYYY-MM-DD)

groupBy— "category" | "merchant" | "tag" (default: "category")

Request

curl "https://nyxfinance.app/api/v1/reports/spending?dateFrom=2026-02-01&dateTo=2026-02-28&groupBy=category" \
  -H "Authorization: Bearer nyx_sk_live_abc123..."

Response

{
  "data": [
    {
      "group": "Groceries",
      "total": 412.33,
      "count": 8,
      "percentOfTotal": 22.3
    },
    {
      "group": "Dining",
      "total": 287.50,
      "count": 12,
      "percentOfTotal": 15.5
    }
  ],
  "totalSpending": 1847.22,
  "dateFrom": "2026-02-01",
  "dateTo": "2026-02-28"
}

MCP Server

The NYX Finance MCP (Model Context Protocol) server lets LLMs like Claude interact with your financial data directly. Ask questions about your spending, check your net worth, or analyze trends — all through natural language in any MCP-compatible client.

Installation

npx @nyx/mcp-server

Configuration for Claude Desktop

Add the following to your Claude Desktop claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "nyx-finance": {
      "command": "npx",
      "args": ["@nyx/mcp-server"],
      "env": {
        "NYX_API_KEY": "nyx_sk_live_abc123..."
      }
    }
  }
}

Available Tools

Tool	Description
`list_accounts`	List all linked accounts and balances
`get_transactions`	Search and filter transactions
`get_spending_report`	Get spending breakdown by category or merchant
`get_cashflow`	Get income vs. expenses by month
`get_net_worth`	Get current net worth and asset breakdown
`get_net_worth_history`	Get historical net worth trend
`list_budgets`	List budgets with current spending progress
`list_goals`	List savings goals and progress
`list_recurring`	List detected recurring transactions
`get_investments`	List investment holdings and performance
`get_crypto`	List crypto holdings and prices
`get_metals`	List precious metals holdings and spot prices

Once configured, you can ask Claude things like "How much did I spend on groceries this month?" or "What's my net worth trend over the last 90 days?" and it will pull data from your NYX account automatically.

Developer Documentation

Authentication

Rate Limits

Errors

Accounts

Transactions

Budgets

Goals

Categories

Tags

Investments

Crypto

Metals

Real Estate

Other Assets

Recurring

Net Worth

Reports

MCP Server

Installation

Configuration for Claude Desktop

Available Tools