Swap lifecycle

Sealed tokens

The quote and build steps each return a sealed token that carries the swap’s context to the next call:

POST /swap/quote → geoQuoteToken: the priced route, alongside the preview numbers (output, feeBps, expiresAt).
POST /swap/build-geo-op / build-solana-tx → geoOpToken: the built operation.

Echo each token back verbatim in the next call; there is nothing to parse or store on your side beyond the token in flight. Sealing makes the tokens tamper-proof: a modified token, or one passed to the wrong endpoint, is rejected with 401, so the swap that executes is always exactly the one that was quoted and built.

Quotes expire 30 seconds after issue (expiresAt in the response). Building with a stale quote returns 410 Gone; just request a fresh quote and rebuild. Prices move; don’t cache quotes.

Statuses

GET /swap/status/:swapId reports a submitted swap through a single status field with four values:

pending → settled | failed | refunded

Status	Meaning
`pending`	Accepted and executing: the origin transaction and cross-chain delivery are still in flight.
`settled`	Terminal. Output delivered on the destination chain.
`failed`	Terminal. Execution failed; no funds moved, or see `refunded`.
`refunded`	Terminal. The input was returned to the origin wallet.

A swap stays pending from submission until it reaches one of the three terminal states. The quote and build steps happen before submission and are not swap statuses; they either return a sealed token or an error inline.

Polling

GET /swap/status/:swapId long-polls server-side: the request holds until the swap reaches a terminal status or a ~15-second window elapses, then returns the latest known state. A typical settlement completes in seconds, so most swaps resolve within one or two polls:

let swap;
do {
  const statusResponse = await fetch(`https://api.geodesics.ai/swap/status/${swapId}`, {
    headers: { "x-api-key": apiKey },
  });
  swap = await statusResponse.json();
} while (!["settled", "failed", "refunded"].includes(swap.status));

Once known, the response carries originTxHash (origin chain) and deliveryTxHash (destination chain) so you can link both legs on their explorers; the console shows the same swaps with both legs already linked. Status reads are DB-only and cheap, but they are rate-limited like every other operation, so keep the loop as-is rather than hammering with sub-second retries.

Idempotency

POST /swap/submit and POST /swap/submit-solana are idempotent per quote. The server derives the deduplication key from the sealed quote context inside geoOpToken, so submitting the same signed submission again returns the existing swap instead of executing twice. That makes it safe to retry on timeouts or crashes: keep the geoOpToken and signature you already have and resubmit them. Requesting a fresh quote starts a fresh swap.

Get Started

Integrations

Concepts

Guides

Sealed tokens

Statuses

Polling

Idempotency

​Sealed tokens

​Statuses

​Polling

​Idempotency

Sealed tokens

Statuses

Polling

Idempotency