# Invoice Chaser

> Invoice tracker for freelancers paid in USDC on Sui. It learns how each client pays (Walrus Memory) and verifies every payment on Sui through Tatum's gRPC gateway.

## For paying agents (x402)
- `GET https://invoice-chaser-sigma.vercel.app/api/chaser/x402/{invoiceId}` returns `402 Payment Required` with x402 terms: scheme `exact`, network `sui:mainnet`, USDC asset, `maxAmountRequired` (base units), `payTo`, and `extra.paymentKit` (Sui Payment Kit registry + nonce).
- Pay through the Payment Kit registry (nonce = invoice id) or with a USDC transfer of the exact amount, then repeat the request with header `X-PAYMENT: <Sui transaction digest>` to receive a receipt.
- x402 v2: the same 402 also carries a base64 `PAYMENT-REQUIRED` header; send `PAYMENT-SIGNATURE` (base64 `{ x402Version: 2, accepted, payload: { signature, transaction } }`) with a signed, unexecuted Payment Kit transaction (nonce = invoice id) and the server simulates and broadcasts it through Tatum, answering with `PAYMENT-RESPONSE`.
- [Reference x402 agent](https://github.com/PugarHuda/invoice-chaser/blob/main/scripts/ap-agent.mjs): reads the 402 terms, enforces a budget, pays through Payment Kit, retries with X-PAYMENT

## For paying agents (MPP)
- `GET https://invoice-chaser-sigma.vercel.app/api/chaser/mpp/{invoiceId}` returns `402` with `WWW-Authenticate: Payment method="sui", intent="charge"` (Machine Payments Protocol, @suimpp/mpp). Pay the exact USDC amount, then retry with `Authorization: Payment <credential>` (digest + payer signature) for a 200 and a `Payment-Receipt`.
- [Reference MPP agent](https://github.com/PugarHuda/invoice-chaser/blob/main/scripts/mpp-agent.mjs)

## Discovery
- [OpenAPI with x-payment-info](https://invoice-chaser-sigma.vercel.app/openapi.json): MPP service discovery (draft-payment-discovery-01), every payable operation and its offers

## Live payment stream
- `GET https://invoice-chaser-sigma.vercel.app/api/chaser/pay/{invoiceId}/live`: Server-Sent Events (`watching`, `checkpoint`, `seen`, `paid`) fed by Tatum's Sui gRPC `SubscribeCheckpoints` stream.

## MCP
- [MCP server](https://invoice-chaser-sigma.vercel.app/api/chaser/mcp): Streamable HTTP, read-only tools over the learned memory (list_open_invoices, client_profile, plan_reminder, search_client_memory, payment_terms, learning_summary)

## Receipts and calendar
- Paid invoices can carry a PDF receipt stored on Walrus; `GET https://invoice-chaser-sigma.vercel.app/api/chaser/invoices/{invoiceId}` returns `receipt.url` (Walrus aggregator).
- [Reminder calendar](https://invoice-chaser-sigma.vercel.app/api/chaser/reminders.ics): every open invoice's reminder plan as iCalendar.

## Docs
- [README](https://github.com/PugarHuda/invoice-chaser/blob/main/README.md): how it uses Walrus Memory, Tatum and Sui Payment Kit
- [Live proof](https://invoice-chaser-sigma.vercel.app/api/chaser/proof): current Sui checkpoint via Tatum, memory counts from the Walrus relayer
- [Client pay page](https://invoice-chaser-sigma.vercel.app/?pay=inv-101): example payer-facing page (replace the invoice id)