Developer Documentation

Nova Net Worth API

Read-only financial data endpoints for AI agents, automation, and custom integrations. Give your tools access to your complete financial picture.

OpenAPI Spec →Get API Key →

Quick Start

1. Generate an API key in Settings → Integrations (requires SuperNova or Galaxy subscription)

2. Include your key in the Authorization header:

curl -H "Authorization: Bearer nova_your_api_key" \
  https://api.novanetworth.com/api/v1/agent/summary

3. Parse the JSON response — all money values are in cents (divide by 100 for dollars).

Authentication

All requests require a valid API key in the Authorization header using Bearer token format. Keys start with nova_.

Authorization: Bearer nova_abc123def456...

⚠️ Security

Never share your API key or commit it to source control
Use environment variables to store your key
Keys can be revoked instantly in Settings
All API access is read-only — no writes, no account linking
Account numbers are always masked (last 4 digits only)

Base URL

https://api.novanetworth.com

The API subdomain serves only API routes and documentation. You can also use https://app.novanetworth.com — both work identically.

Rate Limits

Tier	Limit	Window
SuperNova ($19.99/mo)	100 requests	per hour
Galaxy (Enterprise)	1,000 requests	per hour

Every response includes rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709125200

When rate limited (HTTP 429), check the Retry-After header for seconds to wait.

Money Values

All monetary values are returned as integers in cents to avoid floating-point precision issues. Divide by 100 for display.

"netWorth": 45840017  →  $458,400.17
"amount": 84700      →  $847.00

Always check the currency field (default: USD).

Endpoints

GET/api/v1/agent/summary

Financial Summary

Returns net worth, month-over-month change, account count, subscription tier, financial health score, and last sync timestamp.

Permission: canReadNetWorth

Example Response

{
  "success": true,
  "data": {
    "user": { "firstName": "Sarah" },
    "netWorth": { "amount": 45840017, "currency": "USD" },
    "monthOverMonthChange": { "amount": 1230000, "currency": "USD" },
    "accountCount": 8,
    "subscriptionTier": "SUPERNOVA",
    "financialHealthScore": 72,
    "lastSyncTime": "2026-02-25T12:00:00Z"
  },
  "meta": { "requestId": "req_abc123", "timestamp": "2026-02-25T12:00:00Z" }
}

GET/api/v1/agent/accounts

Accounts

Returns all financial accounts with balances, grouped by type (depository, investment, loan, credit, property, vehicle, crypto). Account numbers are masked to last 4 digits.

Permission: canReadAccounts

Example Response

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "acct_123",
        "name": "Checking Account",
        "type": "depository",
        "institution": "Chase",
        "currentBalance": 1234500,
        "currency": "USD",
        "isActive": true,
        "mask": "****4567",
        "group": "depository"
      }
    ],
    "groupedByType": {
      "depository": [ ... ],
      "investment": [ ... ]
    }
  }
}

GET/api/v1/agent/goals

Financial Goals

Returns all financial goals with target amounts, current progress percentage, target dates, and status (on_track, overdue, completed).

Permission: canReadGoals

Example Response

{
  "success": true,
  "data": {
    "goals": [
      {
        "id": "goal_123",
        "name": "Emergency Fund",
        "targetAmount": 2500000,
        "currentAmount": 1825000,
        "progressPercent": 73.0,
        "targetDate": "2026-08-01T00:00:00.000Z",
        "status": "on_track"
      }
    ]
  }
}

GET/api/v1/agent/spending

Spending Analytics

Returns spending by category for the current month (or specified number of months). Includes comparison to previous period.

Permission: canReadBudgetsParams: months (1-12, default: 1)

Example Response

{
  "success": true,
  "data": {
    "months": 1,
    "currency": "USD",
    "total": 485000,
    "byCategory": [
      { "category": "FOOD_AND_DRINK", "amount": 84700 },
      { "category": "RENT_AND_UTILITIES", "amount": 150000 }
    ],
    "comparisonToPreviousPeriod": {
      "previousTotal": 462000,
      "changeAmount": 23000,
      "changePercent": 4.98
    }
  }
}

GET/api/v1/agent/insights

AI Insights

Returns the latest AI-generated financial insights and recommendations for the user.

Permission: canReadNetWorth

Example Response

{
  "success": true,
  "data": {
    "insights": [
      {
        "id": "ins_123",
        "type": "SAVINGS_OPPORTUNITY",
        "title": "Subscription spending up 23%",
        "recommendation": "Your subscription costs increased. Consider reviewing unused services.",
        "createdAt": "2026-02-24T09:00:00.000Z"
      }
    ]
  }
}

GET/api/v1/agent/net-worth/history

Net Worth History

Returns net worth snapshots over time with assets, liabilities, and period change calculations.

Permission: canReadNetWorthParams: days (1-365, default: 30)

Example Response

{
  "success": true,
  "data": {
    "days": 30,
    "history": [
      {
        "date": "2026-02-25T00:00:00.000Z",
        "netWorth": 45840017,
        "totalAssets": 79100000,
        "totalLiabilities": 33259983,
        "currency": "USD"
      }
    ]
  }
}

GET/api/v1/agent/health-score

Financial Health Score

Returns a financial health score (0-100) with a letter grade, component breakdown (net worth growth, debt-to-asset ratio, credit utilization, emergency fund, savings rate), actionable insights, and recommendations.

Permission: canReadNetWorth

Example Response

{
  "success": true,
  "data": {
    "totalScore": 72,
    "grade": "B",
    "breakdown": {
      "netWorthGrowth": { "score": 85, "weight": 0.25 },
      "debtToAssetRatio": { "score": 65, "weight": 0.2 },
      "creditUtilization": { "score": 78, "weight": 0.15 },
      "emergencyFund": { "score": 73, "weight": 0.2 },
      "savingsRate": { "score": 57, "weight": 0.2 }
    },
    "insights": ["Your net worth grew 2.8% this month"],
    "recommendations": ["Build emergency fund to 6 months"],
    "hasBureauCreditScore": false
  }
}

GET/api/v1/agent/briefing

Complete Financial Briefing

Returns everything an agent needs in a single call: net worth with month-over-month change, current month spending vs. previous, top 10 accounts, goals, health score, and latest AI insights. Use this for "how are my finances?" queries instead of making multiple endpoint calls.

Permission: canReadNetWorth

Example Response

{
  "success": true,
  "data": {
    "user": { "firstName": "Sarah", "subscriptionTier": "SUPERNOVA", "currency": "USD" },
    "netWorth": { "current": 45840017, "previousMonth": 44610017, "change": 1230000, "currency": "USD" },
    "spending": { "currentMonth": 485000, "previousMonth": 462000, "changePercent": 4.98, "currency": "USD" },
    "topAccounts": [
      { "id": "acct_1", "name": "Brokerage", "type": "INVESTMENT", "balance": 25400000, "currency": "USD", "mask": "****1234" }
    ],
    "goals": [
      { "id": "goal_1", "name": "Emergency Fund", "targetAmount": 2500000, "currentAmount": 1825000, "progressPercent": 73.0, "status": "on_track" }
    ],
    "healthScore": { "score": 72, "grade": "B" },
    "insights": [
      { "id": "ins_1", "type": "SAVINGS_OPPORTUNITY", "title": "Subscription spending up 23%", "recommendation": "Review unused services." }
    ],
    "accountCount": 8
  }
}

GET/api/v1/agent/transactions

Transactions

Returns recent transactions with optional filtering by date range, category, and account. Supports delta polling via the "since" parameter — pass a timestamp to fetch only new transactions since your last request.

Permission: canReadBudgetsParams: days (1-90, default: 30), limit (1-100, default: 50), category, account, since (ISO date)

Example Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "txn_abc123",
        "name": "Starbucks",
        "merchant": "Starbucks",
        "amount": 575,
        "currency": "USD",
        "date": "2026-02-25T14:30:00.000Z",
        "pending": false,
        "category": "FOOD_AND_DRINK",
        "categoryDetail": "FOOD_AND_DRINK_COFFEE",
        "account": { "id": "acct_1", "name": "Checking", "type": "CHECKING" }
      }
    ],
    "count": 1,
    "filters": { "days": 30, "since": null, "limit": 50, "category": null, "account": null }
  }
}

GET/api/holdings

Investment Holdings

Returns investment holdings grouped by account with current value, cost basis, and gain/loss calculations. Supports filtering by account and aggregation by ticker.

Permission: canReadAccountsParams: accountId (filter to one account), summary=true (aggregate by ticker across accounts)

Example Response

{
  "success": true,
  "data": {
    "holdings": [
      {
        "accountId": "acct_1",
        "accountName": "Roth IRA",
        "holdings": [
          {
            "id": "h1",
            "symbol": "QQQM",
            "name": "Invesco NASDAQ 100 ETF",
            "type": "ETF",
            "quantity": 50,
            "price": 19500,
            "value": 975000,
            "costBasis": 850000,
            "accountId": "acct_1",
            "accountName": "Roth IRA"
          }
        ]
      }
    ],
    "summary": {
      "totalValue": 3884105,
      "totalCostBasis": 3250000,
      "totalGainLoss": 634105,
      "totalGainLossPercent": 19.51
    }
  }
}

GET/api/holdings/summary

Holdings Summary

Aggregated portfolio view across all accounts. Groups holdings by ticker with weighted average price, sector breakdown by investment type, and top gainers/losers.

Permission: canReadAccounts

Example Response

{
  "success": true,
  "data": {
    "holdings": [
      {
        "symbol": "QQQM",
        "name": "Invesco NASDAQ 100 ETF",
        "type": "ETF",
        "quantity": 75,
        "price": 19350,
        "value": 1451250,
        "costBasis": 1200000,
        "gain": 251250,
        "gainPercent": 20.94
      }
    ],
    "sectors": [
      {
        "type": "ETF",
        "value": 2500000,
        "valuePercent": 64.4,
        "costBasis": 2100000,
        "gain": 400000,
        "gainPercent": 19.05,
        "holdingsCount": 3
      }
    ],
    "topGainers": [ ... ],
    "topLosers": [ ... ],
    "summary": {
      "totalValue": 3884105,
      "totalCostBasis": 3250000
    }
  }
}

Error Handling

Error responses use a consistent format:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

Status	Code	Meaning
401	UNAUTHORIZED	Invalid, expired, or missing API key
403	FORBIDDEN	Key lacks permission for this endpoint
429	RATE_LIMITED	Too many requests — check Retry-After header
500	INTERNAL_SERVER_ERROR	Server error — try again later

API Key Permissions

When generating an API key, you can scope it to specific data types:

Permission	Endpoints	Default
canReadNetWorth	summary, insights, net-worth/history, health-score	✅ On
canReadAccounts	accounts, holdings, holdings/summary	✅ On
canReadGoals	goals	✅ On
canReadBudgets	spending	❌ Off

Integrations

🤖 OpenClaw Skill

Install the Nova Net Worth skill to let your AI agent query your finances directly.

View on ClawHub →

🔌 MCP Server

Model Context Protocol server for Claude Desktop, Cursor, and other MCP clients.

Coming soon

Questions? Email hello@novanetworth.com

Nova Net Worth is not a registered investment adviser. API data is for informational purposes only and does not constitute financial advice.