MoneySignals Documentation

Use market context, source records and dated model outcomes to inform your own research. Inspect the published event-signal record, including losses and missing outcomes, through our REST API or MCP server. Daily accuracy and historical studies do not establish profitable weekly or monthly portfolios.

Overview

Public data tools are available through two interfaces:

• REST API — https://api.moneysignals.us. JSON over HTTPS, one API key.
• MCP server — a thin Model Context Protocol wrapper over that API, so Claude Desktop, Claude Code, or any MCP client can call it as tools.

Our focus is research evidence for independent decisions. The daily brief provides context and aggregate diagnostics. Longer-horizon research asks whether a frozen basket earns a positive return after costs and improves on buying and holding the market or comparable random baskets. Qualified 5–10/20–60-session findings are not yet established in this research product. See Evidence & holding periods for what the existing records can support.

Quick start

1. Inspect the track record — no key needed

The event-signal record is public. Check its dates, counts and limitations before interpreting its rates:

# live win rate, avg return, resolved-call count for the event signals
curl https://api.moneysignals.us/track-record

2. Get a free API key — it comes with the free email signup

Join the free daily email and confirm your address — your API key arrives in the welcome email, no card required. It unlocks the ML predictions and every market-context endpoint. Pass it as the X-API-Key header (or Authorization: Bearer <key>, whichever your client prefers):

curl -H "X-API-Key: at_sk_your_key" \
  https://api.moneysignals.us/api/v1/market/regime

Paid plans (from $29/mo) add the aggregate research brief and recorded event diagnostics plus alt-data and higher limits — every paid plan includes both the daily email and API access.

3. Or connect an agent in one command — hosted MCP, nothing to install

claude mcp add --transport http moneysignals https://api.moneysignals.us/mcp \
  --header "X-API-Key: at_sk_your_key"

Then ask your agent: “What’s the market regime, and how accurate were MoneySignals’ recent predictions?” — see Connect via MCP.

Authentication, tiers & limits

• Header: X-API-Key: at_sk_… — or Authorization: Bearer at_sk_… — on every request except the public ones below.
• Public (no key): GET /track-record and GET /demo/snapshot — so you can connect and verify immediately.
• Free key: included with the free email signup — confirm your email and the key is in the welcome email. Lost it? Sign up again with the same address and confirm: the old key is revoked and a fresh one is emailed to you.
• Your key’s status: GET /api/v1/account/me works on every key and returns your tier, rate limits, and total usage. (Detailed 30-day analytics via GET /api/v1/account/usage is API Pro.) Every response carries X-RateLimit-Remaining and X-RateLimit-Reset headers (plus …-Day variants) so you can pace yourself; a 429 adds Retry-After and means slow down or upgrade.
• Errors come back as JSON — {"detail": "…", "code": "…"}. The detail is a sentence written for you and gets reworded; code is stable, so branch on that: missing_api_key, invalid_api_key, api_key_deactivated, api_key_expired, tier_required, and rate_limited_minute vs rate_limited_day — pause a moment, or come back tomorrow. The 401 and 403 messages point you to pricing; the closed list is the ErrorCode enum in the OpenAPI spec.

Keys report their internal tier name (api_starter / api_pro) in GET /api/v1/account/me — existing API Starter ($49) and API Pro ($199) keys keep working unchanged and map to Premium and Professional.

Connect an AI agent (MCP)

MCP clients (Claude Code, Claude Desktop, your own agent) can access the documented data tools — no SDK to learn, no endpoints to wire up. Two ways to connect to the available tools: the hosted server (recommended — one command, nothing to install) or a downloadable one-file stdio server.

Hosted — one command, nothing to install

claude mcp add --transport http moneysignals https://api.moneysignals.us/mcp \
  --header "X-API-Key: at_sk_your_key"

No Python, no download, always the latest tools. Your key rides on the connection as an HTTP header — leave the --header off to connect keyless and try get_track_record first. Any client that speaks MCP Streamable HTTP works the same way: point it at https://api.moneysignals.us/mcp and send X-API-Key (or Authorization: Bearer) on each request. Building your own agent? It’s plain JSON-RPC:

curl -X POST https://api.moneysignals.us/mcp \
  -H "Content-Type: application/json" -H "X-API-Key: at_sk_your_key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_market_regime","arguments":{}}}'

Or run it locally (stdio)

Prefer a local process — or your client can’t send custom headers (Claude Desktop’s config, for one)? Download the one-file server:

pip install "mcp>=1.2" httpx
# download the one-file server (always the latest)
curl -O https://api.moneysignals.us/mcp/server.py

Claude Code — local stdio variant

claude mcp add moneysignals \
  --env MONEYSIGNALS_API_KEY=at_sk_your_key \
  -- python /path/to/server.py

Claude Desktop — config

Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "moneysignals": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": { "MONEYSIGNALS_API_KEY": "at_sk_your_key" }
    }
  }
}

Restart the client. Without a key, only get_track_record works — enough to confirm the connection. The free key unlocks predictions, market context and the ETF pullback signal; paid keys add the event signals. Override the base URL with MONEYSIGNALS_API_BASE if needed.

Available tools

Use MCP tools/list for the current tool inventory and schemas.

Open the intelligence workspace for the human view. Agent evidence tools read the same global observations; they cannot access private portfolios. Source configuration does not imply collected coverage: check status, source clocks and stale flags.

no key public. free key works with the free key from the email signup. premium / professional need a paid plan (from $29/mo — email + API together).

Research workflow

Start with source dates and coverage, then inspect the complete measured record and its benchmark. Separate a model's direction score from a portfolio's attainable return. An event date alone does not establish a profitable exit or re-entry rule.

REST API reference

Base URL https://api.moneysignals.us. All endpoints below are prefixed /api/v1 unless noted, return JSON, and need the X-API-Key header. Try them live in the interactive API reference (or ReDoc).

Signals

Premium and up (key tier api_starter) — except /track-record (public) and /signals/etf-pullback + /signals/youtube-scoreboard (free key).

Predictions

Works with the free key (/predictions/batch is Professional).

Market context

Works with the free key.

Global evidence is also available at GET /intelligence/events and GET /intelligence/status under the same /api/v1 prefix. Event filters: source=usgs|eia|worldmonitor|osiris, category=earthquake|energy_inventory, limit=1..50 (default 20), and the returned cursor (maximum 1,000 characters). A registered provider may be unavailable or not configured. Unknown coverage is not a quiet-world conclusion.

Social, alt-data & account

Social is Professional; alternative data is Premium and up. /account/me works on any key (/account/usage is Professional).

Evidence & holding periods

Daily hit rate is not buy-and-hold performance. Below 50% warrants investigation, but does not alone establish worse-than-random performance or profitable inversion. Compare sample size, bullish and bearish results, gain/loss sizes and the market's own direction rate. Stocks on the same day and overlapping holding periods are not independent observations.

Our proposed weekly and monthly scorecards freeze a basket before an eligible market open and hold it until the next scheduled rebalance. They require net total return, drawdown, cash, costs and comparisons against SPY and eligible random baskets using the same dates and capital. Calendar weeks/months differ from fixed 5/20-session windows. This is a research design; audited production results are not yet available.

Tariffs, interest-rate decisions and inflation releases belong in the dated context for every period, including quiet periods. Compare what was known before the decision with what changed afterward. Any event-driven exit and re-entry strategy needs a separate, predeclared comparison with unchanged buy-and-hold.

Conviction is a ranking score, not a calibrated probability of profit. Shrinking a small sample's win rate does not eliminate selection bias, dependence or the effects of testing many rules.

Honesty & limits

• Inspect the population, dates and resolved, pending and missing counts. Published records are not an independent audit; original forecast availability and source revisions need their own evidence.
• Legacy aggregate returns use direction-signed price changes. They do not represent an executed account, short-sale or inverse-fund returns, costs or compounding. Ledger rows can show raw price changes.
• A weekly review of daily predictions is not a weekly holding return. A daily prediction cannot earn an entry price from before publication. Longer holding periods alone do not repair an uninformative model.
• Win rates on small samples are noisy and can decay; treat any single number as evidence, not a guarantee.
• Some feeds lag (e.g. options-derived PCR carries a stale flag); the API tells you when.
• Nothing here is financial advice. Predictions and signals are automated, uncertain, and frequently wrong. See the Terms.