# 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`](https://docs.atomiq.exchange/rest-api-reference/list-pending-swaps) | Only swaps that are currently ongoing, might also require an action from the user to continue executions. |
| [`GET /listSwaps`](https://docs.atomiq.exchange/rest-api-reference/list-swaps)                | 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`](https://docs.atomiq.exchange/rest-api-reference/schemas/listswapsoutput) 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`](https://docs.atomiq.exchange/rest-api-reference/list-pending-swaps) 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](https://docs.atomiq.exchange/rest-api-guide/creating-and-executing.md#poll-for-the-current-action) from the **Creating & Executing a Swap** section.

Because every swap record includes the full `quote`, `state`, `steps`, and (via [`GET /getSwapStatus`](https://docs.atomiq.exchange/rest-api-reference/get-swap-status)) `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`](https://docs.atomiq.exchange/rest-api-reference/list-pending-swaps) **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`](https://docs.atomiq.exchange/rest-api-reference/get-swap-status) will get either:

* **`SignSmartChainTransaction`** with `name: "Refund"` — sign the refund transaction and submit it back via [`POST /submitTransaction`](https://docs.atomiq.exchange/rest-api-reference/submit-transaction).
* **`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`](https://docs.atomiq.exchange/rest-api-reference/list-swaps) 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`](https://docs.atomiq.exchange/rest-api-reference/list-pending-swaps). 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`](https://docs.atomiq.exchange/rest-api-reference/list-swaps), 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](https://docs.atomiq.exchange/rest-api-guide/creating-and-executing.md)) 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 →](https://docs.atomiq.exchange/rest-api-guide/creating-and-executing.md)**

***

### Quoting Swaps

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

**[Quoting Swaps →](https://docs.atomiq.exchange/rest-api-guide/quoting.md)**