**Key response fields**:
- `safeToSpend` — dollars available after upcoming commitments
- `safeDays` — days of runway at current burn rate
- `stressLevel` — `low` | `medium` | `high` | `critical`
- `upcomingIncome` — `{ amount, date, source }` or null
- `nextCommitment` — `{ name, amount, dueDate }` or null
- `confidence` — 0-100 data quality score
- `explanation` — 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).

**Key response fields**:
- `safeDays` — days of remaining runway
- `burnRate` — average daily spending (last 30 days)
- `breathingRoom` — buffer after commitments
- `nextCrunchDate` — ISO date when balance goes negative (or null)
- `nextCrunchAmount` — commitments due around the crunch
- `daysUntilCrunch` — 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).

**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).

**Key response fields**:
- `alerts[]` — `{ id, type, severity, title, description, amount?, daysUntil?, evidence? }`
- `count` — total alerts
- `hasCritical` — 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.

**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.

**Key response fields**:
- `snapshot` — `{ availableBalance, breathingRoom, daysOfBreathingRoom, upcomingIncome, commitments[] }`
- `highlights` — `{ urgentActions, biggestOpportunities, recentWins }`
- `alerts[]` — same format as alerts endpoint
- `spendingInsights` — `{ 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).

**Key response fields**:
- `canAfford` — boolean
- `safeToSpendAfter` — remaining safe-to-spend after the purchase
- `impactOnRunway` — how many fewer days of runway
- `recommendation` — AI-generated advice
- `confidence` — 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.

**Key response fields**:
- `messageType` — `daily_checkin` | `alert` | `celebration` | `suggestion` | `warning`
- `headline` — short headline
- `body` — 2-4 sentences of coaching with specific numbers
- `actions[]` — `{ 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`

**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.

**Key response fields**:
- `response` — Guardian AI's natural language answer
- `confidence` — 0-100
- `relatedAlerts[]` — IDs of relevant alerts
- `limitRemaining` — 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

1. **Sign up** at [shelter.money](https://shelter.money)
2. **Connect bank accounts** via Plaid (takes ~60 seconds)
3. **Create an Agent API key** at [shelter.money/settings/api-keys](https://shelter.money/settings/api-keys)
4. **Set your environment variable**: