Quick Start: Your First Swap - Bolt Liquidity Documentation

This guide walks you through installing the Bolt Sui SDK, connecting to the network, and executing your first swap. By the end, you will have a working integration that queries prices, simulates output, and submits an onchain trade.

This guide targets developers building DApps, aggregators, or any application that routes swaps through Bolt on Sui.Contact the team if that is your use case.

Install, connect, and swap

Prerequisites

Before you start, make sure you have:

Node.js 18+ installed
A Sui-compatible wallet (Sui Wallet, Suiet, etc.) for signing transactions
Access to Sui RPC endpoints (the SDK uses https://fullnode.mainnet.sui.io:443 for mainnet and https://fullnode.testnet.sui.io:443 for testnet by default)

Install the SDK

NPM
YARN
PNPM

npm install @bolt-liquidity-hq/sui-client

yarn add @bolt-liquidity-hq/sui-client

pnpm install @bolt-liquidity-hq/sui-client

Initialize the client

The SDK connects to mainnet by default. Pass environment: 'testnet' to use testnet instead.

type Environment = 'mainnet' | 'testnet';

Mainnet
Testnet

import { BoltSuiClient } from '@bolt-liquidity-hq/sui-client';

const client = new BoltSuiClient();

import { BoltSuiClient } from '@bolt-liquidity-hq/sui-client';

const client = new BoltSuiClient({
  environment: 'testnet',
});

Need a custom RPC endpoint or advanced overrides? See the full client initialization options in the SDK reference.

Query supported assets

Fetch all assets available on Bolt and find the denominations you need for your swap.

// Get all supported assets
const assets = await client.getAssets();
assets.forEach((asset) => {
  console.log(`${asset.symbol} (${asset.name}): ${asset.denom}`);
  console.log(`  Decimals: ${asset.decimals}`);
});

// Find a specific asset
const suiAsset = assets.find((a) => a.symbol === 'SUI');
console.log(`SUI type: ${suiAsset?.denom}`); // "0x2::sui::SUI"

Simulate the swap

Before committing onchain, simulate the swap to preview the expected output, fees, and pool routing. This is a dry run with no gas cost.

const simulation = await client.simulateSwap({
  assetIn: '0x2::sui::SUI',
  amountIn: '1000000000', // 1 SUI (9 decimals)
  assetOut: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
});

console.log(`Expected output: ${simulation.amountOut} USDC`);
console.log(`Protocol fee: ${simulation.protocolFee}`);
console.log(`LP fee: ${simulation.lpFee}`);
console.log(`Total fees: ${simulation.totalFees}`);

simulateSwap() uses current prices and pool state. The output reflects exactly what the onchain swap will return, because Bolt uses deterministic convergence pricing, not a bonding curve.

Execute the swap

Submit the swap onchain. The Execution Rail settles at the convergence price committed by the Convergence Engine.

// Get signer from wallet (implementation depends on wallet)
const signer: Signer = await getSuiWalletSigner();

// Execute a swap: exactly 1 SUI for USDC
const result = await client.swap({
  assetIn: '0x2::sui::SUI',
  amountIn: '1000000000', // 1 SUI (9 decimals)
  assetOut: '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC',
  minimumAmountOut: '1900000', // Minimum 1.9 USDC (6 decimals)
}, signer);

console.log(`Swapped 1 SUI for ${result.amountOut} USDC`);
console.log(`Transaction digest: ${result.txHash}`);
console.log(`Gas cost: ${result.txOutput.effects.gasUsed.computationCost}`);
console.log(`Status: ${result.txOutput.effects.status.status}`);

Always set minimumAmountOut in production. This protects against edge cases where oracle prices update between simulation and execution. See slippage protection best practices for a helper function.

What just happened

When you called client.swap(), Bolt used the latest executable onchain quote and settled your trade atomically against available pool inventory.

Bolt formed the quote from broader market data
The offchain Pricing Engine derives the executable price from the venues driving broader market price discovery.
The quote was published onchain
Bolt’s onchain Oracle receives the quote and enforces the contract-level publication bounds.
Your swap checked available inventory
The pool and router contracts read the valid price and confirm that sufficient inventory is available for the trade.
The trade executed and settled atomically
If the trade fits within the available capacity, the swap settles in a single transaction at the quoted output.

This is the same flow that powers swaps on Cetus, FlowX, and Aftermath Finance today.

What’s next

Sui TypeScript SDK

Full API reference: oracle queries, pool inspection, advanced client configuration, and best practices.

Sui Outpost Addresses

Contract addresses for mainnet and testnet deployments.

Offchain Quoting

Simulate swaps offchain using deterministic pricing for your own UI.

Contract Math

Understand the pricing formula behind simulateSwap().

Need integration support or want to discuss your use case? Book a call with the team.

​Install, connect, and swap

​What just happened

​What’s next

Sui TypeScript SDK

Sui Outpost Addresses

Offchain Quoting

Contract Math

Install, connect, and swap

What just happened

What’s next