Idempotency Guide

OpenXSwitch | Safe Retry Mechanism: Idempotency Guide

Idempotency

To ensure safe retries and prevent duplicate processing, OpenXSwitch supports idempotency using unique identifiers across various endpoints.

Operation	Idempotency Key Used	Description
Withdrawal	clientTxId	Unique per withdrawal request. Prevents duplicate transactions.
Transfer	clientTxId	Must be unique per transfer. Enables safe retries without duplicating.
Trade	clientTxId	Used to identify and deduplicate trade orders.
Instant Swap	extId	Unique external ID provided by the client system for tracking swap actions.
Webhooks	event.params.id	Unique identifier for each event. Use to ensure an event is processed once.
Webhooks (alt)	requestId	Unique per webhook request. Can be used to prevent duplicate handling when retrying delivery.

Best Practices

• Always generate a unique idempotency key (clientTxId, extId, etc.) from your system when making requests.
• Store and check this key on your side before retrying any failed or timed-out requests.
• For webhooks, track event.params.id or requestId to avoid processing the same event multiple times.