# simplesplit

> A bill splitter for trips and events. No built-in assistant -- users connect their own AI agent (Claude, ChatGPT, Gemini, or anything that can call HTTP) with a scoped API key and a short setup prompt. The agent adds expenses, checks splits, logs payments, and asks or answers open questions through the API below; it always acts as the user, narrowed by the key's scopes and event restrictions.

## API

- Base URL: https://simplesplit.omarsjunk.com/v1
- Auth: `Authorization: Bearer ss_live_...`
- OpenAPI spec: https://simplesplit.omarsjunk.com/openapi.json
- Human docs: https://simplesplit.omarsjunk.com/docs/agents
- Amounts are integer cents in the event's currency. Every write accepts an `Idempotency-Key` header and replays the original response on retry.

## Key endpoints

- `GET /me` -- who this key acts as, its scopes, and events
- `GET /events?active_on=YYYY-MM-DD` -- events covering that date (match a card charge)
- `POST /events` -- create an event (`name`, optional `currency`, `starts_on`, `ends_on`); the user becomes its owner
- `GET /events/{id}` -- members, bills, payments, balances
- `GET /events/{id}/settle-plan` -- suggested transfers to zero everyone out
- `POST /events/{id}/bills` -- add a bill (`description`, `amount`, `payer`, `spent_on`, `split: {mode, members, weights|amounts}`; payer and members accept membership ids, names, or "me" -- an unknown or ambiguous name returns 422 with `candidates`, so ask the user, `source`, `external_ref`)
- `GET /me/confirmations` -- shares the user was added to that need an answer
- `POST /shares/{id}/confirm` / `POST /shares/{id}/dispute` -- answer on the user's behalf
- `POST /events/{id}/members` -- add a person (`email` required, `name`, optional `note`); they're emailed a sign-in link into the event. Same email again returns the existing member
- `POST /events/{id}/payments` -- log a payment where the user sent or received it
- `GET /events/{id}/questions` -- notes and open questions on the event, with answers
- `POST /events/{id}/questions` -- post a question or note (don't guess -- ask)
- `POST /questions/{id}/answers` -- answer a question someone left
- `POST /questions/{id}/resolve` -- mark a question resolved

## Joining as an invited person's agent (no key yet)

If a person was added to an event, their invitation email contains an agent invite code. With their go-ahead, an agent can act for them without them copying a key:

1. `POST /agent_signup` with `{"invite_code": "...", "agent": "<your name>"}` (no auth). The person gets an approval email; you get a `poll_secret`.
2. Tell the person to open the email and approve you. You can't approve yourself.
3. Poll `POST /agent_signup/claim` with `{"poll_secret": "..."}` every few seconds. It returns 202 while pending and, once approved, the `api_key` exactly once. Store it; use it as the Bearer key.

## Rules

- Before adding anyone to an event, confirm with the user who and which email. Afterwards, tell the user to let those people know to check their email (check spam), since the invitation comes from simplesplit.

- Errors are JSON `{"message": "...", "code": "..."}` written to relay to the user verbatim.
- Always check with the user before creating, changing, or disputing anything, even when the key would allow it.