Listing Swaps

The API keeps a persistent record of every created swap, except the expired non-executed swaps (which are purged from the database). These endpoints allow you to get either the subset of swaps which are currently pending/ongoing or a list of all swaps executed by a given wallet address. This is useful for the "Pending swaps" screen, the post-app-restart recovery flow and for simply showing the history of all the swaps the given user has completed.

Endpoint	Use for
GET /listPendingSwaps	Only swaps that are currently ongoing, might also require an action from the user to continue executions.
GET /listSwaps	Full swap history for a signer — e.g. a "Transactions" tab.

Both endpoints take the same query parameters:

Query param	Required	Notes
signer	✓	Smart-chain signer address whose swaps to return.
chainId	optional	Filter to a single chain (SOLANA, STARKNET, CITREA, …). Omit to include every chain.

They also both return the same ListSwapOutput shape (an array of swap records with the four terminal flags and with the currentAction field):

[
  {
    "swapId":     "…",
    "swapType":   "FROM_BTC",
    "state":      { "number": 3, "name": "CLAIM_COMMITED", "description": "…" },
    "quote":      { /* ... */ },
    "createdAt":  1713359700000,
    "steps":      [ /* ... */ ],
    "isFinished": false,
    "isSuccess":  false,
    "isFailed":   false,
    "isExpired":  false
  },
  /* ... */
]

List pending swaps

You can query the GET /listPendingSwaps endpoint on app startup to restore the polling loops of pending swaps.

curl "https://mainnet.swaps-api.atomiq.exchange/listPendingSwaps?signer=0x0123…"

The response is an array of ongoing swaps that still need user action. Each entry should be in a non-terminal state with isFinished: false, the currentAction field is not populated by this endpoint.

Processing pending swaps

To process the pending swaps, use the usual polling loop from the Creating & Executing a Swap section.

Because every swap record includes the full quote, state, steps, and (via GET /getSwapStatus) currentAction, the client does not need its own persistence layer — just remember the signer address and whatever pairing you have with the user account:

// on app start
const pending = await get("/listPendingSwaps", { signer });
for (const swap of pending) {
  // resume each one with the same loop you use for fresh swaps
  await pollUntilFinished(swap.swapId);
}

tip

If your wallet supports multiple accounts, call GET /listPendingSwaps per account and aggregate the results. There is no endpoint that merges across signers.

Refunds and expired quotes

The API exposes refunds through the same currentAction machinery as the happy path — you don't need a separate endpoint. When a swap enters a refundable state, the polling loop using GET /getSwapStatus will get either:

• SignSmartChainTransaction with name: "Refund" — sign the refund transaction and submit it back via POST /submitTransaction.
• Wait — if the refund is automatic (LP-settled), no client action is needed.

For expired quotes — swaps where the quote elapsed before the user paid — isExpired becomes true, isFinished becomes true, and no on-chain state was ever created. Safe to drop from the pending list and silently discard from local UI state.

List all swaps

Use GET /listSwaps to query all swaps (completed and pending) for a given signer.

curl "https://mainnet.swaps-api.atomiq.exchange/listSwaps?signer=0x0123…&chainId=STARKNET"

Uses the same signer and optional chainId query parameters as GET /listPendingSwaps. The response includes the full swap history for the signer, with the same record shape and terminal flags.

UI patterns

A few small conventions that come up in real integrations:

• Badge count — (await get("/listPendingSwaps", { signer })).length.
• Transactions list — GET /listSwaps, sorted by createdAt desc, grouped by state.name or by the first / last step.title.
• Per-swap detail screen — once the user taps an entry, switch to the per-swap polling loop (Creating & Executing) using the swapId from the list.
• Multi-chain aggregation — call without chainId; the returned records already include quote.inputAmount.chain / quote.outputAmount.chain to label which chain each one belongs to.

Next Steps

Creating & Executing

Use the same polling and action-handling loop when resuming pending swaps from a list response.

Creating & Executing a Swap →

---

Quoting Swaps

Build the token, amount, and recipient-address form before creating new swaps.

Quoting Swaps →