getGaslessRequest

Fetch one stored GaslessQ relayer request — the poll target of every gasless workflow. A relay submit returns 202 immediately; this record is the only source of truth afterwards.

import { getGaslessRequest, GaslessRequestStatus, isGaslessRequestTerminal } from "@symmio/trading-core";
 
const request = await getGaslessRequest(config, { requestId });
 
if (request.status === GaslessRequestStatus.SUBMITTED && request.txHash) {
  showExplorerLink(request.txHash);
}
if (isGaslessRequestTerminal(request.status)) stopPolling();

One GET {base}/{request_id} against the chain’s gasless service. Operation relays live on the "operations" sub-service (the default); deposit settlements on "deposits" — the two are separate databases, so a request id polled against the wrong one is NOT_FOUND.

The query factory polls on its own. A relay request is a workflow, not a value: fetching it once answers queued and freezes there, which reads as a stalled UI even though the relayer finished seconds later. So the factory ships the service-recommended cadence — a jittered 1–2 s while queued, 3–5 s after submitted, and stop once terminal, because a terminal record is immutable and polling one forever bills the service for an answer that cannot change.

// Polls to a terminal status, then stops. No cadence to hand-write.
const request = useQuery(getGaslessRequestQueryOptions(config, { requestId }));

It also absorbs the two failures that are not answers — the accept-vs-record 404 right after a 202 (up to three), and transient transport failures (429, 503, a dropped connection) which are retried with the gateway’s Retry-After when it sent one and a jittered 1 s → 30 s backoff otherwise. A definitive answer (401, 403, 422, a service error code) is surfaced immediately, and a terminal record is treated as permanently fresh so a remount does not refetch it. Every default applies only where you supplied nothing, so query.refetchInterval, query.retry and query.staleTime still win.

The factory’s queryFn also forwards TanStack’s own AbortSignal, so a query that unmounts or is cancelled stops its poll in flight instead of finishing into a discarded result. Pass signal yourself outside React.

Polling helpers

gaslessPollDelay(status, random?)

The cadence the query factory uses, exported so a hand-rolled loop can share it: a jittered delay inside the service’s recommended band (1–2 s while queued, 3–5 s after submitted), or false once the status is terminal. The jitter is load-bearing on the anonymous gateway — every workflow a page opened at the same moment would otherwise poll in lockstep and spend the shared per-IP budget in bursts.

import { gaslessPollDelay } from "@symmio/trading-core";
 
const delay = gaslessPollDelay(request.status);
if (delay !== false) setTimeout(poll, delay);

isNewerGaslessRequest(prev, next)

The stale-response guard for anything that writes a polled record somewhere shared — a query cache, a progress state, a stored row. Status reads are concurrent by construction: a poll, a retry after a transient failure and a relay’s own wait can all be in flight at once, and they do not answer in the order they were sent. Without this guard a slow queued response that lands after the succeeded one repaints a finished workflow as pending, which is exactly the “it looks stuck, submit it again” bug the lifecycle contract forbids.

The order is the lifecycle first — queued < submitted < terminal, with terminal sticky, because a terminal record is immutable — then updatedAt within one rank. When either record carries no usable timestamp the newer fetch wins, since a record with no timestamp cannot be proven stale.

import { isNewerGaslessRequest } from "@symmio/trading-core";
 
queryClient.setQueryData<GaslessRequest>(key, (previous) =>
  isNewerGaslessRequest(previous, incoming) ? incoming : previous,
);

Parameters

Returns

GaslessRequest is a per-service union: the two services are separate databases with different columns, so the shared fields live on the base shape and each service’s own fields on its variant. Narrow on service before reading a variant field.

const request = await getGaslessRequest(config, { requestId, service: "deposits" });
if (request.service === "deposits") {
  showSweep(request.depositAddress, request.walletId, request.creditedRaw);
}

service: "operations"

service: "deposits"

Throws

• SymmError("config", "GASLESS_NOT_CONFIGURED") / ("config", "GASLESS_UNSUPPORTED_CONTRACTS_VERSION") — the chain has no usable gasless service.
• SymmApiError with code GASLESS_STATUS_FETCH_FAILED — HTTP failure, including the post-submit 404 race.
• SymmError("api", "GASLESS_INSTANCE_MISMATCH") — a successful response came from a different protocol instance than the config expects (protocolInstance, or the instance the url path pins): a staging/production cross-wire. A gateway url also fails when the X-GasLessQ-Protocol-Instance header is missing; behind a proxy root, only a forwarded header is checked. See URL forms.
• SymmError("api", "GASLESS_STATUS_UNKNOWN") — the service returned a status outside the documented lifecycle.