Track a Mayan bridge swap by persisting its source transaction identifier, polling the Explorer API, and treating only the API’s terminal client statuses as final.
Which identifier should your integration persist?
Persist the value returned when the source-side submission succeeds. For ordinary EVM and Solana swaps, that is the source transaction hash or signature; for a gasless Swift EVM swap, the SDK returns an order hash as a string instead of a transaction response. Both identifiers go to the same tracking endpoint: GET mayan.finance.
Do not use the destination transaction hash as the lookup key. It may not exist yet when the user submits, and the source identifier is what the API accepts to find the order. The Mayan Swap SDK README documents the gasless return-value distinction; the Track Transactions guide documents the endpoint and status fields.
How should you interpret the lifecycle?
Use clientStatus as the application state: INPROGRESS means keep waiting, while COMPLETED and REFUNDED are terminal. The response’s granular status is useful for diagnostics, but the docs direct integrators to branch on clientStatus.
When a user is deciding between routes or wants the mechanics behind an order, how Mayan bridge routes swaps gives that context; once signed, this tracking flow applies regardless of route. On completion, display toAmount, the actual delivered amount, rather than the quote’s expectedAmountOut. For a refund, explain that the input was returned and show the refunded amount and asset; it may differ from the original token.
What polling pattern works in production?
Poll every 2 seconds, as Mayan’s tracking guide recommends, and stop on either terminal status. Make the poller resilient to temporary network errors: retain the identifier, retry with backoff after failures, and keep the user’s state pending rather than treating a timeout or missing response as a refund.
For example, suppose a user swaps 250 USDC from Arbitrum to Solana. Save the source hash after submission, query the endpoint every 2 seconds, and continue while it reports INPROGRESS. If it returns COMPLETED, show the actual toAmount and destination transaction hash when present. If it returns REFUNDED, show the returned asset and amount.
How do you build the integration step by step?
Keep transaction submission and cross-chain settlement as separate states in your application. A wallet response tells you the source submission result; it does not establish that destination delivery is complete.
- Submit the source transaction. Wait for the SDK call to return successfully, then extract the source hash or gasless order hash. If submission fails, present that source-side error instead of starting settlement tracking.
- Persist the identifier immediately. Store it with the user’s route, source and destination chains, token addresses, and submission time. This lets the UI resume tracking after refresh or device changes.
- Poll the tracking endpoint every 2 seconds. Treat transient HTTP or network errors as unknown and retry with backoff; do not invent a terminal state. At production scale, Mayan recommends requesting an API key for polling volume and passing it as apiKey.
- Branch on clientStatus. Keep polling on INPROGRESS; stop on COMPLETED or REFUNDED. Use toAmount for delivery, and show the refund’s actual asset and amount if returned.
- Expose both chain transactions when available. Use sourceTxHash and destTxHash to provide explorer links, and completedAt to display settlement time or measure your own latency.
Common questions about swap tracking
Does a successful wallet signature mean the swap completed?
No. It means the user approved or submitted the source-chain transaction; the cross-chain order can still be live. Keep showing a pending state until the Explorer API reports COMPLETED or REFUNDED. A source-chain confirmation alone does not prove destination delivery.
Which amount should the completion screen display?
Display toAmount from the completed tracking response, because it records what arrived. A quote’s expected output is a pre-execution estimate, so retaining it as the final amount can misstate the result. If the order is refunded, show the refunded amount and token instead.
What should happen if polling stops temporarily?
Keep the order pending and retain its identifier so polling can resume. A timeout, browser close, or API error does not change the order’s on-chain outcome. Retry failed requests with backoff; once connectivity returns, resume querying until the API reports one of its terminal client statuses.
- Save the source transaction hash or gasless order hash.
- Poll every 2 seconds and branch on clientStatus.
- On completion, show toAmount; on refund, show what was returned.