waitForGaslessRequest

Poll one gasless request until it broadcasts or reaches a terminal status — the framework-agnostic awaited form of the getGaslessRequest poll loop.

This is the raw driver: it reports whatever terminal it reaches. To assert an outcome — resolve only on succeeded, optionally after the receipt lands on your own client — use confirmGaslessRequest instead. Reach for this one when you want until: "broadcast", or when a non-succeeded terminal is a normal branch rather than an error.

import { waitForGaslessRequest, GaslessRequestStatus } from "@symmio/trading-core";
 
const record = await waitForGaslessRequest(config, { requestId, until: "broadcast" });
if (record.txHash) {
  await config.getClient().waitForTransactionReceipt({ hash: record.txHash });
}

The cadence follows the service recommendation — GASLESS_QUEUED_POLL_MS (1 500 ms) while queued, GASLESS_SUBMITTED_POLL_MS (3 000 ms) after submitted — bounded by an overall timeoutMs budget (GASLESS_WAIT_TIMEOUT_MS, 120 000 ms). Up to three consecutive 404s are tolerated right after a submit (the accepted record may not be readable yet); a fourth is rethrown.

Every cadence and window below falls back to the deployment’s gasless.execution block before its constant, so a gateway’s own tuning reaches every wait — including the ones you never call directly, like the one a relayed write runs in its receipt tail.

The stream leads; HTTP is the fallback

Where the deployment serves a status stream, the wait subscribes to it and polls only while it is not delivering. A healthy workflow therefore costs no status reads at all: the stream carries the same records the reads return, so a caller cannot tell which transport produced one.

The stale window is not redundant with the socket’s own liveness check: heartbeats arrive about every 20 s and prove the socket is alive, saying nothing about whether this workflow is still being reported. Without it a live-but-silent stream could blind a wait until the socket’s 60 s liveness timer fired.

The settle window is deliberately shorter than the poll cadence it defers, so a stream that never answers costs one delayed read rather than an extra one.

A failed read is not a failed request

Once the service has returned a 202 the workflow is running whether or not you can see it, so the loop absorbs every transient transport failure instead of reporting one:

Every retry is capped by whatever is left of timeoutMs, so a 30-second backoff can never hide a 5-second budget. Use onTransportIssue to render “status unavailable, still running” — never a failure, and never a reason to re-submit an intent that is already executing.

const record = await waitForGaslessRequest(config, {
  requestId,
  onTransportIssue: () => setDegraded(true),
  onUpdate: () => setDegraded(false),
});

When the budget does run out, the thrown timeout carries the last transient failure as its cause, which is how you tell “the relayer is slow” from “we went blind”:

try {
  await waitForGaslessRequest(config, { requestId });
} catch (err) {
  if (err instanceof SymmError && err.code === "GASLESS_TERMINAL_TIMEOUT") {
    const wentBlind = err.cause !== undefined;
  }
}

Parameters

Returns

Throws

• SymmError("api", "GASLESS_BROADCAST_TIMEOUT" | "GASLESS_TERMINAL_TIMEOUT") — the budget ran out before the wait target. cause is the last transient read failure, when the budget was spent going blind rather than waiting.
• SymmError("api", "GASLESS_WAIT_ABORTED") — signal aborted.
• Everything getGaslessRequest throws for a definitive answer, and after the 404 tolerance is exhausted. Transient transport failures are absorbed rather than thrown.