Documentation Index
Fetch the complete documentation index at: https://docs.privataswap.com/llms.txt
Use this file to discover all available pages before exploring further.
States
| Status | Meaning | Terminal |
|---|
waiting_deposit | Order created, deposit address shown, awaiting user funds. | no |
confirming | Deposit detected on-chain, awaiting block confirmations. | no |
exchanging | Provider received funds and is converting. | no |
sending | Provider broadcasts the payout transaction. | no |
completed | Payout confirmed. amount_to_actual and tx_out_hash are set. | yes |
failed | Permanent failure. Inspect failed_reason_code. | yes |
expired | User never sent funds before expires_at. | yes |
refund_required | Manual intervention needed (overpayment / underpayment / KYT / rate change). | no |
refunded | Refund executed back to refund_address or converted to stable. | yes |
manual_review | Provider needs human review or refund without consent surface. | no |
Allowed transitions
waiting_deposit ──→ confirming ──→ exchanging ──→ sending ──→ completed
│ │ │
↓ ↓ ↓
expired refund_required ←──── (any non-terminal)
│
├──→ refunded
└──→ manual_review
failed is reachable from any non-terminal state.
failed_reason_code enum
| Code | What it means | Suggested UX |
|---|
kyt_block | Receive or refund address hit a sanctions/KYT list. | ”Address rejected by compliance check. Try another address.” |
amount_out_of_range | Provider’s min/max changed after quote. | ”Amount no longer supported. Get a new quote.” |
rate_changed | Rate moved beyond slippage tolerance. | ”Rate moved. Confirm a new quote.” |
provider_timeout | Upstream provider unresponsive. | ”Provider didn’t respond. Picking another.” |
provider_internal | Provider returned 5xx during execution. | Same. |
underpayment | User sent less than expected. | Triggers refund_required instead in most cases. |
overpayment | User sent more than expected. | Same. |
network_congestion | Blockchain fees spiked and order can’t proceed. | ”Network congestion, please retry later.” |
unknown | Anything else. | Show failed_reason_message. |
Event timing expectations
| Pair class | confirming → completed p95 |
|---|
| EVM → EVM (same chain) | ~3 min |
| BTC → anything | ~25 min |
| anything → XMR | ~12 min |
| Lightning → anything | ~1 min |
