Tracking a swap

Three ways to follow a swap, suited to different situations.

Method	Best for
Polling	Scripts and quick checks
WebSocket	A browser showing live progress
Webhooks	A server that must not miss an event

Polling

Endpoint	Returns
GET /api/swap/:id	Full swap detail
GET /api/swap/:id/status	Status, transaction hashes, error message
GET /api/swap/:id/events	Complete lifecycle, chronological

curl -s https://bridge.testnet.kriptonyx.com/api/swap/<id>/status

{ "id": "…", "status": "pending_deposit",
  "deposit_tx_hash": null, "payout_tx_hash": null, "error_message": null }

GET /api/swap/:id/events is the one to use after a disconnection — it returns the whole history, so nothing is lost.

Poll considerately

A swap takes a minute or two. Polling every few seconds is fine; polling every 200 ms is not, and gains you nothing since the monitor itself runs on a 20-second cycle.

Statuses

Status	Meaning
pending_deposit	Waiting for you to send funds
deposit_detected	Seen, awaiting confirmations
deposit_confirmed	Confirmed
rate_locked	Exchange rate fixed
gathering · gathered	Funds being collected into the vault
vault_locking · vault_locked	Vault handling
payout_processing	Payout submitted
completed	Done. payout_tx_hash is set
failed	Could not complete. error_message says why
expired	The deposit window closed without a deposit
simpleswap_*	External SimpleSwap leg in progress

WebSocket

const ws = new WebSocket('wss://bridge.testnet.kriptonyx.com/ws');

ws.onopen = () => ws.send(JSON.stringify({ type: 'subscribe', swap_id: swapId }));

ws.onmessage = ({ data }) => {
  const msg = JSON.parse(data);
  if (msg.type === 'swap_update') {
    console.log(msg.event, msg.tx_hash ?? '');
  }
};

Low latency, but a dropped connection means missed messages. Reconcile with GET /api/swap/:id/events on reconnect. See WebSocket.

Webhooks

Register an endpoint once and receive every swap's events, signed and retried. This is the right choice for a server — see Webhooks.

Recording evidence

For a completed swap, the two hashes that matter are the deposit on the source chain and the payout on the target chain. Both appear in GET /api/swap/:id, and the payout is verifiable in the explorer when the target is KriptoNyx.

If a swap fails

Read error_message from the status endpoint. Common causes:

Cause	Meaning
Insufficient funds	The payout wallet lacked gas or reserves on the target chain
Route unavailable	No liquidity or route for that pair at that moment
Expired	The deposit arrived after the window closed

Funds return to refund_address where one was supplied. If a swap is stuck, quote the swap ID — every state transition is recorded against it.