Skip to main content

Quick Start – Node.js

This guide covers installing the Atomiq SDK in Node.js and its chain-specific connectors and walks you through setting up and initializing the Atomiq SDK.

Core SDK​

Install the main SDK package, and for Node.js applications, install the SQLite storage adapter:

npm install @atomiqlabs/sdk@latest
npm install @atomiqlabs/storage-sqlite@latest

Chain Connectors​

The SDK supports multiple chains. Install only the chain connectors your project needs, and mix and match them as required:

npm install @atomiqlabs/chain-solana@latest
npm install @atomiqlabs/chain-starknet@latest
npm install @atomiqlabs/chain-evm@latest

Setup​

tip

See setup.ts in the demo repo for a ready-to-use version of the setup below.

Set your RPC URLs:

const solanaRpc = "https://api.mainnet-beta.solana.com";
const starknetRpc = "https://rpc.starknet.lava.build/"; //Alternatively: https://starknet.api.onfinality.io/public or https://api.zan.top/public/starknet-mainnet
const citreaRpc = "https://rpc.mainnet.citrea.xyz";

Create a swapper factory with your desired chain support. Use as const so TypeScript can properly infer the types:

import {SolanaInitializer} from "@atomiqlabs/chain-solana";
import {StarknetInitializer} from "@atomiqlabs/chain-starknet";
import {CitreaInitializer} from "@atomiqlabs/chain-evm";

import {BitcoinNetwork, TypedSwapper, SwapperFactory, TypedTokens} from "@atomiqlabs/sdk";
import {SqliteStorageManager, SqliteUnifiedStorage} from "@atomiqlabs/storage-sqlite";

// Define chains you want to support
const chains = [SolanaInitializer, StarknetInitializer, CitreaInitializer] as const;
type SupportedChains = typeof chains;

// Create the swapper factory
const Factory = new SwapperFactory<SupportedChains>(chains);

// Get the tokens for the supported chains
const Tokens: TypedTokens<SupportedChains> = Factory.Tokens;

// Create one swapper instance for your entire app, and use that instance for all your swaps.
const swapper: TypedSwapper<SupportedChains> = Factory.newSwapper({
  chains: {
    SOLANA: {
      rpcUrl: solanaRpc // Can also pass Connection object
    },
    STARKNET: {
      rpcUrl: starknetRpc // Can also pass Provider object
    },
    CITREA: {
      rpcUrl: citreaRpc, // Can also pass JsonRpcProvider object
    }
  },
  bitcoinNetwork: BitcoinNetwork.MAINNET,
  swapStorage: chainId => new SqliteUnifiedStorage("CHAIN_MAINNET_"+chainId+".sqlite3"),
  chainStorageCtor: name => new SqliteStorageManager("STORE_MAINNET_"+name+".sqlite3"),
});

await swapper.init();
info

Initialize the swapper with await swapper.init(); once when your app starts. You should create only one swapper instance for your entire app, and use that instance for all your swaps. This checks existing in-progress swaps and does initial LP discovery.

Implement swap recovery — refunds & manual claims

If your app is interrupted mid-swap or the LP fails to deliver, user funds stay locked in the swap escrow until your app explicitly recovers them — this does not happen automatically. After swapper.init(), always check for and process:

  • Refundable swaps — failed Smart Chain → BTC swaps where the user's locked funds must be refunded via swapper.getRefundableSwaps().
  • Claimable swaps — swaps where the user still needs to claim funds on the destination chain, retrieved via swapper.getClaimableSwaps().

Run these checks on every app start and periodically while running, otherwise funds can remain locked in swaps indefinitely.

Setting Up Signers​

Atomiq's AbstractSigner object wraps around the wallet object of the respective chain and makes it easy to approve transactions via it by passing it to the swap methods. You can alternatively skip this step, obtain the transactions required to be signed and sign & send them manually.

tip

See wallets.ts in the demo repo for a ready-to-use version of the signers below.

Solana​

Using Solana wallet with private key
import {Keypair} from "@solana/web3.js";
import {SolanaKeypairWallet, SolanaSigner} from "@atomiqlabs/chain-solana";

// Generate random private key
const solanaKey: Uint8Array = Keypair.generate().secretKey;

// From private key
const solanaSigner = new SolanaSigner(
  new SolanaKeypairWallet(Keypair.fromSecretKey(solanaKey)),
  Keypair.fromSecretKey(solanaKey)
);

Starknet​

warning

On Starknet, accounts are smart contracts (account abstraction). An address is derived from the account class hash + deployment salt + constructor calldata, not from the private key alone. The same private key therefore produces a different address for every account implementation.

Using OpenZeppelin account

StarknetKeypairWallet derives its address using its own bundled OpenZeppelin account class. If you import a private key from another wallet (Argent, Braavos, or a different OpenZeppelin version), you will get a different, empty address. Your funds still sit at the address derived by the original wallet.

import {StarknetSigner, StarknetKeypairWallet} from "@atomiqlabs/chain-starknet";
import {RpcProvider} from "starknet";

// Generate random private key
const starknetKey: string = StarknetKeypairWallet.generateRandomPrivateKey();

// From private key, this uses a simple openzeppelin account class with a single public key.
const starknetProvider = new RpcProvider({nodeUrl: starknetRpc});
const starknetSigner = new StarknetSigner(
  new StarknetKeypairWallet(starknetProvider, starknetKey)
);

The account contract does not need to be deployed up front: the SDK automatically deploys it with the first swap transaction (paying the deployment fee from the account's balance).

Using an existing Starknet account

If you already have a deployed Starknet account, keep using it: don't pass its private key to StarknetKeypairWallet, wrap a plain starknet.js Account with your existing address in StarknetSigner instead:

import {StarknetSigner} from "@atomiqlabs/chain-starknet";
import {Account, RpcProvider} from "starknet";

const starknetProvider = new RpcProvider({nodeUrl: starknetRpc});
const starknetSigner = new StarknetSigner(
  new Account({
    provider: starknetProvider,
    address: "0x...", // your existing, already-deployed account address
    signer: starknetKey,
    cairoVersion: "1"
  })
);

EVM (Citrea, etc.)​

Using an EVM wallet with private key
import {BaseWallet, SigningKey, JsonRpcProvider, Wallet} from "ethers";
import {EVMSigner} from "@atomiqlabs/chain-evm";

// Generate random private key
const evmKey: string = Wallet.createRandom().privateKey;

// From private key
const evmProvider = new JsonRpcProvider(citreaRpc);
const wallet = new BaseWallet(new SigningKey(evmKey), evmProvider);
const evmWallet = new EVMSigner(wallet, wallet.address);

Your First Swap​

Here's a complete example of a Smart Chain to Bitcoin on-chain swap:

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

// Create a swap: SOL to Bitcoin on-chain
const swap = await swapper.swap(
  Tokens.SOLANA.SOL,              // From token
  Tokens.BITCOIN.BTC,             // To Bitcoin on-chain
  "0.0001",                       // Amount of BTC to receive
  SwapAmountType.EXACT_OUT,       // Specify amount in output token
  solanaSigner.getAddress(),      // Source address
  "bc1q..."                       // Bitcoin destination address
);

// Check quote details
console.log("Input:", swap.getInput().toString());
console.log("Output:", swap.getOutput().toString());
console.log("Expires:", new Date(swap.getQuoteExpiry()));

// Execute the swap
const success = await swap.execute(solanaSigner, {
  onSourceTransactionSent: (txId) => console.log("Tx sent:", txId),
  onSwapSettled: (btcTxId) => console.log("Bitcoin transaction sent: ", btcTxId)
});

// Handle failure
if (!success) {
  await swap.refund(solanaSigner);
}

Next Steps​

Creating Quotes​

Guides you through creating swap quotes.

Creating Quotes →

Swap Management​

Retrieve & query past swaps, handle swaps which require manual refund or settlement fallback.

Swap Management →

Configuration​

Explains swapper configuration parameters passed in the Factory.newSwapper() function and debug logging config.

Swapper Configuration →

Utilities​

SDK-exposed utilities allow you to parse addresses (including LNURL links), fetch token balances, list supported tokens and swap types.

Utilities →