shelter

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

```bash
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 commitments
- `safeDays` — days of runway at curre...

# Shelter Agent Skill

**[shelter.money](https://shelter.money)** — Your AI financial advisor, connected to your real bank data.

Shelter connects your bank accounts via Plaid and gives you (and your AI agents) real-time financial health: safe-to-spend, cash forecasts, zombie subscriptions, affordability checks, and AI coaching. This skill lets Claude Code, OpenClaw, and other AI agents talk directly to your Shelter data.

## Get started

1. **Create your free account** at **[shelter.money](https://shelter.money)**
2. **Connect your bank** — takes ~60 seconds via Plaid
3. **Generate an API key** in the app under Settings > API Keys
4. **Install the skill** (pick one):

```bash
# Claude Code marketplace
/plugin marketplace add nextauralabs/shelter-skill

# npm
npm install -g @shelter/agent-skill

# ClawHub
clawhub install shelter

# Manual
# Copy SKILL.md and references/ into ~/.claude/skills/shelter/
```

5. **Set your key**:
```bash
export SHELTER_API_KEY="wv_your_key_here"
```

6. **Ask your agent anything about your money** — it handles the rest.

## What your agent can do

| Ask your agent... | What happens |
|---|---|
| "How am I doing?" | Checks safe-to-spend, stress level, upcoming income |
| "When do I run out of money?" | Calculates runway and predicts the next cash crunch |
| "What does next week look like?" | 14-day day-by-day balance forecast |
| "Any problems I should know about?" | Surfaces zombie subscriptions, spending spikes, upcoming bills |
| "Where am I wasting money?" | Finds savings opportunities with estimated annual savings |
| "Can I afford $200 headphones?" | Simulates the purchase against your real cash flow |
| "Give me today's coaching" | Personalized financial coaching with specific action items |
| Complex financial questions | Routes to Guardian AI for nuanced, contextual advice |

## Security

- **Read-only** — Shelter can see your data but can never move money
- **Scoped API keys** — you choose exactly what each key can access
- **N...