# Locus Heartbeat

> **You are on:** `https://paywithlocus.com/` · `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt)
>
> Locus has three environments. Make sure every URL you call matches your expected environment:
> - **Production**: paywithlocus.com (landing) / {api}.paywithlocus.com (API)
> - **Beta**: {beta}.paywithlocus.com (landing) / {beta-api}.paywithlocus.com (API)
> - **Stage**: {stage}.paywithlocus.com (landing) / {stage-api}.paywithlocus.com (API)
>
> If the URLs above don't match your expected environment, re-fetch this file from the correct domain.

*Run this every 30 minutes. You can also check anytime you want!*

Time to check in on your Locus account and apps.

---

## First: Check for Skill Updates

Check if there's a new version (once a day is plenty):

```bash
curl -s https://paywithlocus.com/wallet/skill.json | grep '"version"'
```

Compare with your saved version. If there's a new version, re-fetch the skill files:

```bash
curl -s https://paywithlocus.com/wallet/skill.md > ~/.locus/skills/SKILL.md
curl -s https://paywithlocus.com/wallet/onboarding.md > ~/.locus/skills/ONBOARDING.md
curl -s https://paywithlocus.com/wallet/heartbeat.md > ~/.locus/skills/HEARTBEAT.md
curl -s https://paywithlocus.com/wallet/skill.json > ~/.locus/skills/skill.json
```

Update `lastSkillUpdate` in `~/.config/locus/state.json` so you don't re-check every heartbeat.

---

## Check Apps

If your human has enabled any apps (e.g. Hire with Locus), follow the app-specific heartbeat instructions from your APPS.md file. Fetch it if you haven't recently:

```bash
curl -s https://api.paywithlocus.com/api/apps/md \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -o APPS.md
```

If no apps are enabled, skip this step.

---

## Daily Feedback (Once Every 24 Hours)

During one heartbeat per day, submit a feedback summary. Check `lastFeedbackSubmission` in `~/.config/locus/state.json` to avoid sending more than once per 24h.

```bash
curl -X POST https://api.paywithlocus.com/api/feedback \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "general",
    "message": "Daily summary: Used pay/send 3 times (all succeeded). Wrapped API firecrawl/scrape timed out once. No other issues.",
    "source": "heartbeat"
  }'
```

After submitting, update `lastFeedbackSubmission` in your state file.

Also submit feedback **immediately** whenever you receive an error response from any Locus API:

```bash
curl -X POST https://api.paywithlocus.com/api/feedback \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "error",
    "endpoint": "/api/pay/send",
    "message": "500 Internal Server Error when sending 10 USDC",
    "context": {"status_code": 500, "error_body": "..."},
    "source": "error"
  }'
```

---

## When to Tell Your Human

**Do tell them:**
- A skill update is available
- You hit a policy limit (403) on any action
- An app-specific event needs their attention (see APPS.md)

**Don't bother them:**
- Routine heartbeat with no changes
- Normal in-progress statuses

---

## Response Format

If nothing changed:
```
HEARTBEAT_OK — No Locus updates.
```

If a skill update is available:
```
Locus: Skill files updated to v1.4.0.
```

If something needs human attention:
```
Locus: [description of what needs attention]
```