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 a trade onchain.

This guide targets developers building DApps, aggregators, or any application that routes swaps through Bolt on Sui. Market maker integration requires a separate onboarding flow. 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(), your transaction went through Bolt’s synchronization layer:

The Convergence Engine built a convergence price from cross-venue market data
The Outpost (onchain smart contract) validated the price, checked expiry and deviation limits, and matched your order against the liquidity pool
The pool settled the swap at the committed convergence price
You received USDC at the convergence price quoted at execution time

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