# AgentKeep

> Wallet-scoped OS primitives for AI agents — memory, fetch, budget receipts, trust, and owner-bound notify. No signup, no API keys. Pay per call with x402 (USDC on Algorand Mainnet via GoPlausible).
>
> Separate product — not AgentCash / Stable*. Challenge tag: `x402-global-challenge`.

## Network (Mainnet only)

- Protocol: x402 v2
- Facilitator: https://facilitator.goplausible.xyz
- Network CAIP-2: `algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=`
- Asset: USDC ASA `31566704`
- payTo: `2VIU2N25S2TRAJ54ZTUY5CSFADU6Y5KEMKAWTRWR2ODNTPULNGHBKWEPTQ`
- Tag on every paid 402: `x402-global-challenge`

## How to pay

1. Call a paid endpoint. Without payment you get **HTTP 402** and a `PAYMENT-REQUIRED` header (base64 JSON).
2. Use any x402 client to pay the advertised `accepts[]` requirement (exact scheme, Algorand Mainnet USDC).
3. Retry the **same** request with `PAYMENT-SIGNATURE`.
4. On success: JSON body + ledger receipt + response header `X-AgentKeep-Session` (TTL 15 minutes).
5. Use that session for free Memory GET / Budget GET. Never assume anonymous free GETs.
6. Send `Idempotency-Key` on paid mutations when retrying to avoid double-charge.

## Paid endpoints

- [PUT /v1/memory/:key](https://agent-keep-3jimn6j2va-ew.a.run.app/v1/memory/:key): Store a wallet-scoped key/value (≤64KiB JSON/text). Returns key metadata plus an x402 payment receipt. Tenant = paying Algorand wallet; other wallets get 404. **$0.001 USDC**.
- [POST /v1/fetch](https://agent-keep-3jimn6j2va-ew.a.run.app/v1/fetch): Server-side HTTPS fetch of a public URL with shared SSRF denylist (no private/link-local). Returns status, content-type, and a truncated body excerpt plus payment receipt. **$0.01 USDC**.
- [GET /v1/budget/receipts](https://agent-keep-3jimn6j2va-ew.a.run.app/v1/budget/receipts): Export recent ledger rows (settled|credited|failed) for the paying wallet — spend audit for agents. **$0.002 USDC**.
- [GET /v1/trust](https://agent-keep-3jimn6j2va-ew.a.run.app/v1/trust): Probe a public URL for reachability and basic x402 Payment-Required signals (≤3s). SSRF-guarded. **$0.002 USDC**.
- [POST /v1/notify](https://agent-keep-3jimn6j2va-ew.a.run.app/v1/notify): Create an owner-bound human approval/Q&A ticket (email/Telegram already bound by owner). Returns pending ticket id — poll GET /v1/notify/{id}; never blocks on max_wait_seconds. **$0.02 USDC**.

## Free with session (not public)

- `GET https://agent-keep-3jimn6j2va-ew.a.run.app/v1/memory/{key}` — requires `X-AgentKeep-Session` or payment proof
- `GET https://agent-keep-3jimn6j2va-ew.a.run.app/v1/budget` — same

## Rules for agents

- Wallet tenancy: data is scoped to the paying Algorand address (`algo:<address>`). Cross-wallet miss → **404** (no leak).
- Hard daily cap default **$2 USDC**; on `budget_exceeded` stop — no side effects.
- Notify recipients are **owner-bound only** — never supply arbitrary recipient addresses.
- Fetch/trust/callback URLs go through SSRF guard — private IPs fail closed.
- Credits offset future spend only; no withdraw.
- Branch on `error.code` only (stable catalog).

## Discovery files

- https://agent-keep-3jimn6j2va-ew.a.run.app/.well-known/x402
- https://agent-keep-3jimn6j2va-ew.a.run.app/.well-known/agent-card.json
- https://agent-keep-3jimn6j2va-ew.a.run.app/agents.md
- https://agent-keep-3jimn6j2va-ew.a.run.app/v1/discovery
- https://agent-keep-3jimn6j2va-ew.a.run.app/health