{"skill":{"slug":"shelter","displayName":"Shelter","summary":"Connect to your Shelter financial data. Check safe-to-spend, predict cash crunches, find zombie subscriptions, simulate purchases, get AI coaching, and ask G...","description":"---\nname: shelter\ndescription: >\n  Connect to your Shelter financial data. Check safe-to-spend, predict cash crunches,\n  find zombie subscriptions, simulate purchases, get AI coaching, and ask Guardian AI\n  about your money. Read-only access to real bank data via Plaid.\nversion: 1.0.0\nmetadata:\n  openclaw:\n    emoji: \"\\U0001F6E1\"\n    requires:\n      env: [SHELTER_API_KEY]\n      bins: [curl]\n    primaryEnv: SHELTER_API_KEY\n    homepage: https://shelter.money\n---\n\n# Shelter\n\nConnect 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.\n\n## Authentication\n\nEvery request needs two things:\n\n- **Header**: `X-Shelter-Key: $SHELTER_API_KEY`\n- **Base URL**: `$SHELTER_API_URL` (default: `https://api.shelter.money/agent`)\n\nAll examples below use these variables. Confirm they're set before making any call.\n\n## Decision Tree\n\nUse this to pick the right endpoint for the user's question:\n\n| User wants to know... | Endpoint | Cost |\n|------------------------|----------|------|\n| \"How am I doing?\" / \"Can I spend today?\" | `GET /v1/status` | Cheap |\n| \"When do I run out of money?\" | `GET /v1/runway` | Cheap |\n| \"What does next week look like?\" | `GET /v1/forecast` | Medium |\n| \"Any problems I should know about?\" | `GET /v1/alerts` | Medium |\n| \"Where am I wasting money?\" | `GET /v1/opportunities` | Medium |\n| \"Give me the full picture\" | `GET /v1/context` | Medium |\n| \"Can I afford X?\" | `POST /v1/affordability` | Medium |\n| \"Give me today's coaching\" | `GET /v1/coach/daily` | Medium |\n| \"Help me with [debt/savings/bills]\" | `GET /v1/coach/advice?topic=` | Medium |\n| Complex/nuanced question | `POST /v1/ask` | Expensive |\n\n**Always start with the cheapest endpoint that answers the question.** Only use `/v1/ask` when structured endpoints can't answer it.\n\n---\n\n## Endpoints\n\n### Quick Checks\n\nThese are fast, cached, and cheap. Use them first.\n\n#### GET /v1/status\n\nThe user's current financial health snapshot.\n\n**When to use**: User asks how they're doing, wants safe-to-spend, or you need a quick health check before answering.\n\n**When NOT to use**: User wants a multi-day forecast or detailed breakdown.\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/status\"\n```\n\n**Key response fields**:\n- `safeToSpend` — dollars available after upcoming commitments\n- `safeDays` — days of runway at current burn rate\n- `stressLevel` — `low` | `medium` | `high` | `critical`\n- `upcomingIncome` — `{ amount, date, source }` or null\n- `nextCommitment` — `{ name, amount, dueDate }` or null\n- `confidence` — 0-100 data quality score\n- `explanation` — human-readable summary\n\n**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.\"\n\n---\n\n#### GET /v1/runway\n\nHow long until the money runs out.\n\n**When to use**: User asks about runway, burn rate, or when they'll be broke.\n\n**When NOT to use**: User wants day-by-day detail (use forecast instead).\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/runway\"\n```\n\n**Key response fields**:\n- `safeDays` — days of remaining runway\n- `burnRate` — average daily spending (last 30 days)\n- `breathingRoom` — buffer after commitments\n- `nextCrunchDate` — ISO date when balance goes negative (or null)\n- `nextCrunchAmount` — commitments due around the crunch\n- `daysUntilCrunch` — days until the crunch (or null)\n- `explanation` — human-readable summary\n\n**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.\n\n---\n\n### Deep Analysis\n\nMore detailed endpoints. Use when quick checks aren't enough.\n\n#### GET /v1/forecast\n\n14-day day-by-day financial projection.\n\n**When to use**: User asks what the next week/two weeks look like, or wants to see when specific bills hit.\n\n**When NOT to use**: User just wants today's snapshot (use status).\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/forecast\"\n```\n\n**Key response fields**:\n- `forecast[]` — array of daily projections: `{ date, projectedBalance, events[], isCrunch, isTight }`\n- `summary` — `{ crunchDays, tightDays, lowestBalance, highestBalance }`\n\n**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).\n\n---\n\n#### GET /v1/alerts\n\nActive warnings: zombie subscriptions, spending spikes, upcoming bills.\n\n**When to use**: User asks what needs attention, or you want to proactively surface problems.\n\n**When NOT to use**: User is asking about a specific topic (use advice instead).\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/alerts\"\n```\n\n**Key response fields**:\n- `alerts[]` — `{ id, type, severity, title, description, amount?, daysUntil?, evidence? }`\n- `count` — total alerts\n- `hasCritical` — boolean\n\n**How to summarize**: Critical alerts first, then warnings, then info. Be specific about amounts and dates. If `hasCritical` is true, lead with urgency.\n\n---\n\n#### GET /v1/opportunities\n\nPlaces the user is wasting money or could save.\n\n**When to use**: User asks about saving money, zombie subscriptions, or spending optimization.\n\n**When NOT to use**: User needs a forecast or health check.\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/opportunities\"\n```\n\n**Key response fields**:\n- `opportunities[]` — `{ id, type, title, description, potentialSavings, difficulty, actionUrl? }`\n- `totalPotentialSavings` — annual savings if all opportunities are acted on\n\n**How to summarize**: Lead with total potential savings. List opportunities easiest-first. Include action URLs when available.\n\n---\n\n#### GET /v1/context\n\nFull financial overview combining status, alerts, spending insights, and upcoming events.\n\n**When to use**: User wants the big picture, or you need comprehensive context to answer a complex question.\n\n**When NOT to use**: A more specific endpoint can answer the question. This is heavy.\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/context\"\n```\n\n**Key response fields**:\n- `snapshot` — `{ availableBalance, breathingRoom, daysOfBreathingRoom, upcomingIncome, commitments[] }`\n- `highlights` — `{ urgentActions, biggestOpportunities, recentWins }`\n- `alerts[]` — same format as alerts endpoint\n- `spendingInsights` — `{ summary, byCategory, topMerchants, anomalies }`\n- `upcomingEvents[]` — `{ type, name, amount, currentDate, priority }`\n\n**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.\n\n---\n\n#### POST /v1/affordability\n\nSimulate whether the user can afford a specific purchase.\n\n**When to use**: User asks \"Can I afford X?\" with a specific dollar amount.\n\n**When NOT to use**: User is asking generally about spending (use status).\n\n```bash\ncurl -s -X POST -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"amount\": 200, \"description\": \"New headphones\"}' \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/affordability\"\n```\n\n**Key response fields**:\n- `canAfford` — boolean\n- `safeToSpendAfter` — remaining safe-to-spend after the purchase\n- `impactOnRunway` — how many fewer days of runway\n- `recommendation` — AI-generated advice\n- `confidence` — 0-100\n\n**How to summarize**: Give a clear yes/no first, then explain the impact on their runway and safe-to-spend.\n\n---\n\n### Coaching\n\nAI-generated coaching messages tailored to the user's financial situation.\n\n#### GET /v1/coach/daily\n\nToday's personalized coaching message.\n\n**When to use**: Start of a session, or user asks for their daily update.\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/coach/daily\"\n```\n\n**Key response fields**:\n- `messageType` — `daily_checkin` | `alert` | `celebration` | `suggestion` | `warning`\n- `headline` — short headline\n- `body` — 2-4 sentences of coaching with specific numbers\n- `actions[]` — `{ label, actionType, actionTarget }`\n- `tone` — `encouraging` | `urgent` | `celebratory` | `supportive`\n\n**How to summarize**: Present the headline and body naturally. Suggest the actions conversationally. Match the tone.\n\n---\n\n#### GET /v1/coach/advice?topic=\n\nDeep-dive coaching on a specific financial topic.\n\n**When to use**: User asks for help with a specific area.\n\n**Topics**: `debt`, `savings`, `bills`, `subscriptions`, `negotiation`, `general`\n\n```bash\ncurl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/coach/advice?topic=debt\"\n```\n\n**Response format**: Same as daily coaching (headline, body, actions, tone).\n\n**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`.\n\n---\n\n### Guardian AI Chat\n\n#### POST /v1/ask\n\nAsk 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.\n\n**When to use**: Nuanced questions, planning advice, or follow-ups that need reasoning.\n\n**When NOT to use**: Questions answerable by structured endpoints above. Always try those first.\n\n```bash\ncurl -s -X POST -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"question\": \"What should I prioritize right now?\"}' \\\n  \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/ask\"\n```\n\n**Key response fields**:\n- `response` — Guardian AI's natural language answer\n- `confidence` — 0-100\n- `relatedAlerts[]` — IDs of relevant alerts\n- `limitRemaining` — remaining `/ask` calls for the day\n\n**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.\n\n---\n\n## Rate Limits\n\n| Endpoint group | Free tier | Premium tier |\n|----------------|-----------|--------------|\n| Status, Runway | 60/hour | 60/hour |\n| Forecast, Alerts, Opportunities, Context, Affordability | 60/hour | 60/hour |\n| Coach (daily, advice) | 60/hour | 60/hour |\n| Ask (Guardian AI) | 5/day | 100/day |\n\n## Error Codes\n\n| Code | Meaning | What to do |\n|------|---------|------------|\n| 401 | Invalid or missing API key | Check `SHELTER_API_KEY` is set and valid |\n| 403 | Key lacks required scope | User needs to update key permissions at shelter.money |\n| 429 | Rate limit exceeded | Wait and retry. Check `Retry-After` header |\n| 500 | Server error | Wait a moment and retry |\n\nIf you get a 401, tell the user to check their API key. Don't retry auth errors.\n\n## Setup\n\n1. **Sign up** at [shelter.money](https://shelter.money)\n2. **Connect bank accounts** via Plaid (takes ~60 seconds)\n3. **Create an Agent API key** at [shelter.money/settings/api-keys](https://shelter.money/settings/api-keys)\n4. **Set your environment variable**:\n   ```bash\n   export SHELTER_API_KEY=\"wv_your_key_here\"\n   ```\n5. **Test the connection**:\n   ```bash\n   curl -s -H \"X-Shelter-Key: $SHELTER_API_KEY\" \\\n     \"${SHELTER_API_URL:-https://api.shelter.money/agent}/v1/status\"\n   ```\n\n## Security\n\n- **Read-only** — Shelter can see transactions and balances but can never move money\n- **Scoped API keys** — you choose exactly what the key can access\n- **No raw bank data** — the API returns computed insights (safe-to-spend, alerts), not raw transactions\n- **Keys are hashed** — the secret is never stored in plain text\n- **Audit logging** — every API call is logged\n- **Instant revocation** — disable any key from your settings\n\n## Data Reference\n\nFor field-by-field documentation of all response shapes, see [`references/DATA_MODEL.md`](references/DATA_MODEL.md).\n","topics":["Financial"],"tags":{"latest":"1.0.3"},"stats":{"comments":0,"downloads":859,"installsAllTime":32,"installsCurrent":0,"stars":0,"versions":4},"createdAt":1771774074259,"updatedAt":1778491608600},"latestVersion":{"version":"1.0.3","createdAt":1771775519504,"changelog":"- Changed all API base URLs from `shelterfinance.com` to `shelter.money`.\n- Updated homepage metadata to use `https://shelter.money`.\n- No changes to core endpoints or functionality; documentation and examples now reflect the new domain.","license":null},"metadata":{"setup":[{"key":"SHELTER_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"code-with-brian","userId":"s17b2xfwjmgcs9hxrnkj5rxd4d884vyt","displayName":"Brian Palmer","image":"https://avatars.githubusercontent.com/u/144558318?v=4"},"moderation":null}