Historical Swaps

The SDK persists all swaps locally, allowing you to retrieve them later by ID.

Runnable Example

See the complete working example: utils/pastSwaps.ts

Retrieving Swap by ID

Every swap has a unique ID accessible with the swap.getId() getter that can be used for later retrieval:

const swap = await swapper.swap(/* ... */);

// Get the swap ID
const swapId = swap.getId();
console.log("Swap ID:", swapId);

// Store this ID for later (e.g., in your database, returned data, URL, etc.)

info

Swaps are by default only persisted after they are initiated (i.e. commit(), execute() or waitForPayment() being called), if you want to serve uninitialized quotes from e.g. a REST API endpoint, you need to set the saveUninitializedSwaps flag in the Swapper Configuration, to make sure you can later retrieve these uninitialized quotes.

Unexecuted expired quotes are automatically purged from the persistent storage.

You can then retrieve the swap from storage based on this ID:

• use the getTypedSwapById() function to get the properly-typed swap (e.g. ToBTCSwap, ToBTCLNSwap, FromBTCLNAutoSwap, etc.) if you know the type upfront.
• use the getSwapById() function to get the abstract ISwap swap type, which you can then narrow with the isSwapType() type-guard.

getTypedSwapById()

If you know the expected swap type:

import {SwapType} from "@atomiqlabs/sdk";

// Retrieve with specific type - returns correctly typed swap or undefined if the type doesn't match
const typedSwap = await swapper.getTypedSwapById(
  swapId,
  "SOLANA",              // Chain ID
  SwapType.TO_BTC        // Expected swap type
);

if (typedSwap) {
  // typedSwap is properly typed as ToBTCSwap<SolanaChainType>
  console.log("Output address:", typedSwap.getOutputAddress());
}

getSwapById()

If you don't know the swap type:

import {isSwapType, SwapType} from "@atomiqlabs/sdk";

// Get base swap
const swap = await swapper.getSwapById(swapId);

if (swap) {
  // Use type guards to narrow the type
  if (isSwapType(swap, SwapType.TO_BTC)) {
    // Now typed as ToBTCSwap
    console.log("This is a TO_BTC swap");
  } else if (isSwapType(swap, SwapType.FROM_BTCLN_AUTO)) {
    // Now typed as FromBTCLNAutoSwap
    console.log("This is a Lightning to smart chain swap");
  }
}

info

Both variations for getting the swap return undefined in case the swap wasn't found in the persistent storage.

Swap Type Guards

To help narrowing types of the abstract ISwap class, the SDK provides SwapType-based type-guards which help you properly narrow down the exact type of the swap. For the overview of swap types and their respective swap classes see the Swap Types page.

import {
  isSwapType,
  SwapType,
  ToBTCSwap,
  ToBTCLNSwap,
  FromBTCSwap,
  SpvFromBTCSwap,
  FromBTCLNSwap,
  FromBTCLNAutoSwap
} from "@atomiqlabs/sdk";

const swap = await swapper.getSwapById(swapId);

if (isSwapType(swap, SwapType.TO_BTC)) {
  const toBtcSwap: ToBTCSwap = swap; // Smart chain → Bitcoin swap
}

if (isSwapType(swap, SwapType.TO_BTCLN)) {
  const toBtcLnSwap: ToBTCLNSwap = swap; // Smart chain → Lightning swap
}

if (isSwapType(swap, SwapType.SPV_FROM_BTC)) {
  const spvFromBtcSwap: SpvFromBTCSwap = swap; // Bitcoin → Smart chain swap
}

if (isSwapType(swap, SwapType.FROM_BTCLN_AUTO)) {
  const fromBtcLnAutoSwap: FromBTCLNAutoSwap = swap; // Lightning → Smart chain swap
}

if (isSwapType(swap, SwapType.FROM_BTC)) {
  const fromBtcSwap: FromBTCSwap = swap; // Legacy Bitcoin → Solana swap
}

if (isSwapType(swap, SwapType.FROM_BTCLN)) {
  const fromBtcLnSwap: FromBTCLNSwap = swap; // Legacy Lightning → Solana swap
}

Retrieving All Swaps

The getAllSwaps() function allows you to retrieve all existing swaps from the storage, swaps only for a specific chain or swaps created by a specific smart chain signer.

All

import {ISwap, isSwapType, SwapType, ToBTCSwap} from "@atomiqlabs/sdk";

// Returns all existing swaps from storage if no argument is passed
const allSwaps: ISwap[] = await swapper.getAllSwaps();
// You can further narrow down the type of the swap with the type-guards and check the respective swap's chain
for (let swap of allSwaps) {
  if (isSwapType(swap, SwapType.TO_BTC)) {
    const typedSwap: ToBTCSwap = swap; // Properly narrowed down type
    const chainId = swap.chainIdentifier; // Retrieves smart chain type of the swap, e.g.: SOLANA, STARKNET, CITREA, ...
  }
}

Single chain

import {ISwap, isSwapType, SwapType, ToBTCSwap} from "@atomiqlabs/sdk";
import {StarknetChainType} from "@atomiqlabs/chain-starknet";

// Returns all swaps for a given smart chain (returns all swaps between BTC and the given smart chain)
const starknetSwaps: ISwap<StarknetChainType>[] = await swapper.getAllSwaps("STARKNET");
// You can further narrow down the type of the swap with the type-guards and check the respective swap's chain
for (let swap of starknetSwaps) {
  if (isSwapType(swap, SwapType.TO_BTC)) {
    const typedSwap: ToBTCSwap = swap; // Properly narrowed down type
  }
}

Specific signer

import {ISwap, isSwapType, SwapType, ToBTCSwap} from "@atomiqlabs/sdk";
import {StarknetChainType} from "@atomiqlabs/chain-starknet";

// Returns all swaps created with a specific signer address
const signerSwaps: ISwap<StarknetChainType>[] = await swapper.getAllSwaps("STARKNET", starknetSigner.getAddress());
// You can further narrow down the type of the swap with the type-guards and check the respective swap's chain
for (let swap of signerSwaps) {
  if (isSwapType(swap, SwapType.TO_BTC)) {
    const typedSwap: ToBTCSwap = swap; // Properly narrowed down type
  }
}

API Reference

• getId - Get the persistent ID of a swap
• getSwapById - Get swap by ID (base type)
• getTypedSwapById - Get swap by ID with type
• getAllSwaps - Get all swaps from storage
• isSwapType - Type guard for swap types

Next Steps

Refunding Swaps

Retrieving & processing swaps that were not executed by the LPs and can be refunded, returning funds to the user.

Refunds →

---

Claiming Swaps

Retrieving & processing swaps that didn't get automatically settled and need to be claimed manually.

Claiming →

---