# MDPay API — LLM digest (v1.0.0)

Self-hosted TON payment service provider — anonymous by design.

## Servers
- https://tonpay.y7v.lol (Production)
- http://localhost:4100 (Local development)

## Auth
- `X-Account-Key: TON-...` — account key (owner)
- `Authorization: Bearer tp_live_...` — API key
- `Authorization: Bearer admin <ADMIN_BOOTSTRAP_TOKEN>` — first-admin bootstrap

## Conventions
- All `*_nanoton` fields are **strings** (BigInt-safe).
- All errors: `{ "error": { "code", "message", "details"? } }`.
- Path params: UUIDs use the standard 8-4-4-4-12 pattern; `public_id` is `[0-9A-Z]{10}`.

## Accounts
- `POST /v1/accounts` — Create a new account
- `GET /v1/me` — Get current user profile
- `PATCH /v1/me` — Update current user profile
- `POST /v1/auth/session` — Exchange an account key for a browser session cookie
- `POST /v1/auth/logout` — Destroy the current browser session
- `POST /v1/recover` — Recover account key via wallet mnemonic
- `GET /v1/wallet` — Read-only view of the receive wallet

## Invoices
- `POST /v1/invoices` — Create an invoice
- `GET /v1/invoices` — List invoices
- `GET /v1/invoices/{id}` — Fetch one invoice
- `POST /v1/invoices/{id}/cancel` — Cancel a pending invoice
- `GET /v1/invoices/{id}/public` — Public checkout view of an invoice
- `GET /v1/invoices/{id}/qr.svg` — Invoice QR code (SVG)
- `GET /v1/invoices/{id}/qr.png` — Invoice QR code (PNG)
- `GET /v1/invoices/{public_id}/events` — Server-Sent Events stream for invoice updates

## Webhooks
- `POST /v1/webhooks` — Register a webhook endpoint
- `GET /v1/webhooks` — List webhook endpoints
- `GET /v1/webhooks/{id}` — Fetch one webhook
- `PATCH /v1/webhooks/{id}` — Update webhook URL / events / enabled state
- `DELETE /v1/webhooks/{id}` — Delete a webhook
- `POST /v1/webhooks/{id}/test` — Enqueue a synthetic delivery
- `GET /v1/webhooks/{id}/attempts` — Delivery attempts for one webhook
- `POST /v1/webhooks/rotate` — Rotate a webhook signing secret

## ApiKeys
- `POST /v1/api-keys` — Issue an API key
- `GET /v1/api-keys` — List API keys
- `DELETE /v1/api-keys/{id}` — Revoke an API key
- `POST /v1/api-keys/rotate` — Rotate an API key

## Balance
- `GET /v1/balance` — Get current balance

## Withdrawals
- `POST /v1/withdrawals` — Request a withdrawal
- `GET /v1/withdrawals` — List withdrawals
- `GET /v1/withdrawals/{id}` — Fetch one withdrawal

## Admin
- `GET /admin/users` — List all users
- `PATCH /admin/users/{id}` — Patch a user (disabled, is_admin, note)
- `POST /admin/users/{id}/disable` — Disable a user
- `POST /admin/users/{id}/enable` — Re-enable a user
- `PATCH /admin/users/{id}/commission` — Override commission for one user
- `GET /admin/wallets` — List configured wallets
- `POST /admin/wallets` — Configure the receive wallet from a mnemonic
- `POST /admin/wallets/generate` — Generate a brand-new wallet on the server
- `POST /admin/wallets/{id}/disclose` — Reveal a wallet mnemonic (once)
- `GET /admin/wallets/{id}/balance` — Live on-chain wallet balance
- `GET /admin/invoices` — List all invoices (any user)
- `POST /admin/invoices/{id}/cancel` — Force-cancel an invoice
- `GET /admin/withdrawals` — List all withdrawals (any user)
- `POST /admin/withdrawals/{id}/force-fail` — Force a withdrawal into the `failed` state
- `GET /admin/webhooks/attempts` — Recent webhook delivery attempts
- `POST /admin/webhooks/attempts/{id}/replay` — Re-enqueue a webhook attempt
- `GET /admin/audit-logs` — Read audit logs
- `GET /admin/settings` — Read all system settings
- `PATCH /admin/settings` — Upsert a system setting
- `POST /admin/settings` — Upsert a system setting (POST alias)
- `GET /admin/health` — Detailed health (admin)
- `GET /admin/overview` — Composite admin dashboard overview
- `GET /admin/analytics` — Daily analytics (1–90 days)
- `GET /admin/audit` — Alias for /admin/audit-logs
- `GET /admin/webhook-attempts` — Alias for /admin/webhooks/attempts (also supports webhook_id filter)
- `POST /admin/webhook-attempts/{id}/replay` — Alias for /admin/webhooks/attempts/{id}/replay

## Health
- `GET /health` — Liveness probe
- `GET /ready` — Readiness probe

## Example: create an invoice
```bash
curl -X POST https://tonpay.y7v.lol/v1/invoices \
  -H 'X-Account-Key: TON-A8K4M6N9P3-QXW2Y7Z5R8' \
  -H 'content-type: application/json' \
  -d '{"amount_ton":"2.5","description":"Order #42"}'
```

## Example: paid-event webhook payload
```json
{
  "id": "evt_11111111-2222-3333-4444-555555555555",
  "type": "invoice.paid",
  "data": {
    "id": "7a4a4ec0-3b5d-4a1d-9e2a-2c2c2c2c2c2c",
    "amount_nanoton": "2500000000",
    "paid_tx_hash": "0xabc..."
  }
}
```