# DMS: skill file for a dot

DMS (Dead Man's Switch) is a dead-man's-switch vault on Solana. An owner locks SOL or USDC, names
one beneficiary and picks a silence limit of 30, 60 or 90 days. Any answer from
the owner resets the clock to the full limit. Silence past the limit passes the
vault to the beneficiary.

Every owner already has a dot inside the DMS app. This file is for another
dot that the owner wants to pass their answers through.

## What you need

A dot token. The owner creates it in the app (`/app`, "Another dot") and gives
it to you. It is shown once and the owner can revoke it at any time. Send it on
every request:

    Authorization: Bearer qd_...

All paths below are on the same origin as this file. Bodies and answers are JSON.

## What you may do

1. Read the inbox. It lists what DMS wants passed on to the owner: check-ins
   (`ask`), warnings in the last days before a limit (`warning`, `final`) and
   notices (`notice`).

       GET /api/agent/inbox
       -> { "items": [ { "id": 12, "kind": "ask", "text": "...", "vaultIds": ["..."], "at": 1790000000000 } ] }

2. Reach the owner in your own way and put the item's text to them. Then
   acknowledge it so it leaves the inbox:

       POST /api/agent/inbox/12/ack

3. When the owner has answered you, and only then, report it. This resets the
   clock on every running vault, or on one vault if you name it:

       POST /api/agent/checkin            {}
       POST /api/agent/checkin            { "vaultId": "..." }
       -> { "checkedIn": ["..."], "vaults": [ ... ] }

   Report an answer only when the owner gave one. A check-in you make up keeps
   a vault from passing on when it should.

4. Read the vaults and their time left:

       GET /api/agent/vaults
       -> { "now": 1790000000000, "vaults": [ { "id", "asset", "amount", "beneficiary", "limitDays", "status", "deadline" } ] }

## What you must hand back to the owner

You cannot lock, change or close a vault. You can prepare a request; the owner
confirms it in the app with their wallet, or dismisses it.

    POST /api/agent/drafts                        { "asset": "SOL", "amount": "1.5", "beneficiary": "<Solana address>", "limitDays": 60 }
    POST /api/agent/vaults/<id>/close-request     {}
    -> { "waitingForOwner": true, "request": { "id": "...", "kind": "lock" } }

Tell the owner the request is waiting in the app. Nothing has moved until they
confirm it there.

## Limits

- Assets: SOL, USDC. Silence limits: 30, 60 or 90 days. One beneficiary per vault.
- 60 requests a minute per token. Poll the inbox every few minutes, not faster.
- Errors come as `{ "error": "..." }` with a 4xx status. 401 means the token is
  wrong or revoked.

## With curl

    curl -H "Authorization: Bearer $DMS_TOKEN" https://<this site>/api/agent/inbox
    curl -X POST -H "Authorization: Bearer $DMS_TOKEN" https://<this site>/api/agent/inbox/12/ack
    curl -X POST -H "Authorization: Bearer $DMS_TOKEN" -H "content-type: application/json" -d '{}' https://<this site>/api/agent/checkin