# Public API v2026-07-01

All merchant API routes require signed API-key headers. Responses include `meta.request_id`; successful responses also include `meta.api_version`.

## Endpoints

- `POST /api/v1/payments` — idempotent invoice creation, persisted quote and dedicated address.
- `GET /api/v1/payments/{payment_id}` — status, paid amount, confirmations and normalized transactions.
- `GET /api/v1/payments` — filters: `status`, `order_id`, `pay_currency`, `created_from`, `created_to`, `page`, `per_page`.
- `GET /api/v1/currencies` — enabled asset/network metadata.
- `POST /api/v1/estimate` — informational quote only; never reused as payment settlement data.
- `POST /api/v1/webhooks/test` — queues a synthetic `test_mode=true` event through the production delivery/signing path.
- `POST /api/v1/payouts` — idempotent, decimal input, 2FA gate, address validation, ledger reservation, pending operator approval.

## Payment states

`waiting -> confirming -> confirmed -> finished`, with controlled branches to `expired`, `underpaid`, `overpaid`, `manual_review`, and `failed`. `PaymentStateMachine` rejects transitions outside the explicit graph.

## Security

Live callback URLs must be HTTPS and must resolve to public IP space. Metadata is limited to 8 KB and five nesting levels. Financial logic never reads merchant metadata.