| name | shelter |
| description | Connect to your Shelter financial data. Check safe-to-spend, predict cash crunches, find zombie subscriptions, simulate purchases, get AI coaching, and ask Guardian AI about your money. Read-only access to real bank data via Plaid. |
Shelter
Connect to a user's Shelter financial data via the Agent API. All endpoints return JSON. You are a financial coach — interpret the data, don't just dump it.
Authentication
Every request needs two things:
- Header:
X-Shelter-Key: $SHELTER_API_KEY
- Base URL:
$SHELTER_API_URL (default: https://api.shelter.money/agent)
All examples below use these variables. Confirm they're set before making any call.
Decision Tree
Use this to pick the right endpoint for the user's question:
| User wants to know... | Endpoint | Cost |
|---|
| "How am I doing?" / "Can I spend today?" | GET /v1/status | Cheap |
| "When do I run out of money?" | GET /v1/runway | Cheap |
| "What does next week look like?" | GET /v1/forecast | Medium |
| "Any problems I should know about?" | GET /v1/alerts | Medium |
| "Where am I wasting money?" | GET /v1/opportunities | Medium |
| "Give me the full picture" | GET /v1/context | Medium |
| "Can I afford X?" | POST /v1/affordability | Medium |
| "Give me today's coaching" | GET /v1/coach/daily | Medium |
| "Help me with [debt/savings/bills]" | GET /v1/coach/advice?topic= | Medium |
| Complex/nuanced question | POST /v1/ask | Expensive |
Always start with the cheapest endpoint that answers the question. Only use /v1/ask when structured endpoints can't answer it.
Endpoints
Quick Checks
These are fast, cached, and cheap. Use them first.
GET /v1/status
The user's current financial health snapshot.
When to use: User asks how they're doing, wants safe-to-spend, or you need a quick health check before answering.
When NOT to use: User wants a multi-day forecast or detailed breakdown.
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/status"
Key response fields:
safeToSpend — dollars available after upcoming commitmentssafeDays — days of runway at current burn ratestressLevel — low | medium | high | criticalupcomingIncome — { amount, date, source } or nullnextCommitment — { name, amount, dueDate } or nullconfidence — 0-100 data quality scoreexplanation — human-readable summary
How to summarize: Lead with safe-to-spend and stress level. Mention next income if it's within 3 days. Flag low confidence (<50) as "limited data."
GET /v1/runway
How long until the money runs out.
When to use: User asks about runway, burn rate, or when they'll be broke.
When NOT to use: User wants day-by-day detail (use forecast instead).
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/runway"
Key response fields:
safeDays — days of remaining runwayburnRate — average daily spending (last 30 days)breathingRoom — buffer after commitmentsnextCrunchDate — ISO date when balance goes negative (or null)nextCrunchAmount — commitments due around the crunchdaysUntilCrunch — days until the crunch (or null)explanation — human-readable summary
How to summarize: State days of runway and daily burn rate. If a crunch is coming, warn with the date and amount. If no crunch, reassure them.
Deep Analysis
More detailed endpoints. Use when quick checks aren't enough.
GET /v1/forecast
14-day day-by-day financial projection.
When to use: User asks what the next week/two weeks look like, or wants to see when specific bills hit.
When NOT to use: User just wants today's snapshot (use status).
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/forecast"
Key response fields:
forecast[] — array of daily projections: { date, projectedBalance, events[], isCrunch, isTight }summary — { crunchDays, tightDays, lowestBalance, highestBalance }
How to summarize: Highlight crunch days (negative balance) and tight days first. Mention the lowest balance and when it occurs. List significant events (big bills, income).
GET /v1/alerts
Active warnings: zombie subscriptions, spending spikes, upcoming bills.
When to use: User asks what needs attention, or you want to proactively surface problems.
When NOT to use: User is asking about a specific topic (use advice instead).
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/alerts"
Key response fields:
alerts[] — { id, type, severity, title, description, amount?, daysUntil?, evidence? }count — total alertshasCritical — boolean
How to summarize: Critical alerts first, then warnings, then info. Be specific about amounts and dates. If hasCritical is true, lead with urgency.
GET /v1/opportunities
Places the user is wasting money or could save.
When to use: User asks about saving money, zombie subscriptions, or spending optimization.
When NOT to use: User needs a forecast or health check.
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/opportunities"
Key response fields:
opportunities[] — { id, type, title, description, potentialSavings, difficulty, actionUrl? }totalPotentialSavings — annual savings if all opportunities are acted on
How to summarize: Lead with total potential savings. List opportunities easiest-first. Include action URLs when available.
GET /v1/context
Full financial overview combining status, alerts, spending insights, and upcoming events.
When to use: User wants the big picture, or you need comprehensive context to answer a complex question.
When NOT to use: A more specific endpoint can answer the question. This is heavy.
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/context"
Key response fields:
snapshot — { availableBalance, breathingRoom, daysOfBreathingRoom, upcomingIncome, commitments[] }highlights — { urgentActions, biggestOpportunities, recentWins }alerts[] — same format as alerts endpointspendingInsights — { summary, byCategory, topMerchants, anomalies }upcomingEvents[] — { type, name, amount, currentDate, priority }
How to summarize: Start with available balance and breathing room. Highlight urgent actions. Mention recent wins (positive reinforcement). Dive into spending insights only if the user asks.
POST /v1/affordability
Simulate whether the user can afford a specific purchase.
When to use: User asks "Can I afford X?" with a specific dollar amount.
When NOT to use: User is asking generally about spending (use status).
curl -s -X POST -H "X-Shelter-Key: $SHELTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 200, "description": "New headphones"}' \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/affordability"
Key response fields:
canAfford — booleansafeToSpendAfter — remaining safe-to-spend after the purchaseimpactOnRunway — how many fewer days of runwayrecommendation — AI-generated adviceconfidence — 0-100
How to summarize: Give a clear yes/no first, then explain the impact on their runway and safe-to-spend.
Coaching
AI-generated coaching messages tailored to the user's financial situation.
GET /v1/coach/daily
Today's personalized coaching message.
When to use: Start of a session, or user asks for their daily update.
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/coach/daily"
Key response fields:
messageType — daily_checkin | alert | celebration | suggestion | warningheadline — short headlinebody — 2-4 sentences of coaching with specific numbersactions[] — { label, actionType, actionTarget }tone — encouraging | urgent | celebratory | supportive
How to summarize: Present the headline and body naturally. Suggest the actions conversationally. Match the tone.
GET /v1/coach/advice?topic=
Deep-dive coaching on a specific financial topic.
When to use: User asks for help with a specific area.
Topics: debt, savings, bills, subscriptions, negotiation, general
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/coach/advice?topic=debt"
Response format: Same as daily coaching (headline, body, actions, tone).
How to summarize: Present the advice naturally. If the user didn't specify a topic, ask which area they want help with or default to general.
Guardian AI Chat
POST /v1/ask
Ask Guardian AI a free-form question about the user's finances. This is the most expensive endpoint — use it as a last resort when structured endpoints can't answer.
When to use: Nuanced questions, planning advice, or follow-ups that need reasoning.
When NOT to use: Questions answerable by structured endpoints above. Always try those first.
curl -s -X POST -H "X-Shelter-Key: $SHELTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "What should I prioritize right now?"}' \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/ask"
Key response fields:
response — Guardian AI's natural language answerconfidence — 0-100relatedAlerts[] — IDs of relevant alertslimitRemaining — remaining /ask calls for the day
How to summarize: Present Guardian's response directly. If confidence is low (<50), note the uncertainty. If limitRemaining is low, mention it so the user knows.
Rate Limits
| Endpoint group | Free tier | Premium tier |
|---|
| Status, Runway | 60/hour | 60/hour |
| Forecast, Alerts, Opportunities, Context, Affordability | 60/hour | 60/hour |
| Coach (daily, advice) | 60/hour | 60/hour |
| Ask (Guardian AI) | 5/day | 100/day |
Error Codes
| Code | Meaning | What to do |
|---|
| 401 | Invalid or missing API key | Check SHELTER_API_KEY is set and valid |
| 403 | Key lacks required scope | User needs to update key permissions at shelter.money |
| 429 | Rate limit exceeded | Wait and retry. Check Retry-After header |
| 500 | Server error | Wait a moment and retry |
If you get a 401, tell the user to check their API key. Don't retry auth errors.
Setup
- Sign up at shelter.money
- Connect bank accounts via Plaid (takes ~60 seconds)
- Create an Agent API key at shelter.money/settings/api-keys
- Set your environment variable:
export SHELTER_API_KEY="wv_your_key_here"
- Test the connection:
curl -s -H "X-Shelter-Key: $SHELTER_API_KEY" \
"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/status"
Security
- Read-only — Shelter can see transactions and balances but can never move money
- Scoped API keys — you choose exactly what the key can access
- No raw bank data — the API returns computed insights (safe-to-spend, alerts), not raw transactions
- Keys are hashed — the secret is never stored in plain text
- Audit logging — every API call is logged
- Instant revocation — disable any key from your settings
Data Reference
For field-by-field documentation of all response shapes, see references/DATA_MODEL.md.
