Skip to content

Tracking a swap ​

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

MethodBest for
PollingScripts and quick checks
WebSocketA browser showing live progress
WebhooksA server that must not miss an event

Polling ​

EndpointReturns
GET /api/swap/:idFull swap detail
GET /api/swap/:id/statusStatus, transaction hashes, error message
GET /api/swap/:id/eventsComplete lifecycle, chronological
bash
curl -s https://bridge.testnet.kriptonyx.com/api/swap/<id>/status
json
{ "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 ​

StatusMeaning
pending_depositWaiting for you to send funds
deposit_detectedSeen, awaiting confirmations
deposit_confirmedConfirmed
rate_lockedExchange rate fixed
gathering · gatheredFunds being collected into the vault
vault_locking · vault_lockedVault handling
payout_processingPayout submitted
completedDone. payout_tx_hash is set
failedCould not complete. error_message says why
expiredThe deposit window closed without a deposit
simpleswap_*External SimpleSwap leg in progress

WebSocket ​

js
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:

CauseMeaning
Insufficient fundsThe payout wallet lacked gas or reserves on the target chain
Route unavailableNo liquidity or route for that pair at that moment
ExpiredThe 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.

KriptoNyx testnet — chain ID 3009 (kriptonyx_3009-1)