A type-safe CosmWasm client for interacting with Bolt’s zero slippage execution layer on Archway. Query oracle prices, inspect pool state, simulate swaps off-chain, and execute trades programmatically.
Package: @bolt-liquidity-hq/cosmwasm-clientPrerequisites
Node.js 18+ Archway-compatible wallet (Keplr, Leap, or equivalent)RPC endpoint (defaults provided for mainnet and testnet)
Network Default RPC Endpoint Mainnet https://rpc.mainnet.archway.ioTestnet https://rpc.constantine.archway.io
For production integrations, use a dedicated RPC provider. Public endpoints have rate limits that may affect high-frequency quoting.
Installation npm install @bolt-liquidity-hq/cosmwasm-client
yarn add @bolt-liquidity-hq/cosmwasm-client
pnpm add @bolt-liquidity-hq/cosmwasm-client
Quick start
Install the package
Choose your package manager above and install @bolt-liquidity-hq/cosmwasm-client.
Initialise the client
import { BoltCosmWasmClient } from "@bolt-liquidity-hq/cosmwasm-client" ; // Mainnet (default) const client = new BoltCosmWasmClient (); // Testnet const client = new BoltCosmWasmClient ({ environment: "testnet" });
Fetch oracle prices
const prices = await client . getAllPrices (); console . log ( prices );
Simulate a swap
const quote = await client . simulateSwap ({ assetIn: "ibc/usdc_denom" , amountIn: "1000000" , assetOut: "aarch" , }); console . log ( quote . amountOut , quote . totalFees );
Advanced initialization The client supports full customization for non-standard environments, custom chain configs, or pre-existing signer instances.
Custom configuration options
const client = new BoltCosmWasmClient ({ environment: "mainnet" , // or "testnet" customOverride: { chainConfig: { id: "archway-1" , name: "Archway" , rpcEndpoint: "https://your-rpc.example.com" , restEndpoint: "https://your-rest.example.com" , }, contracts: { oracle: "archway1..." , router: "archway1..." , }, nativeTokenDenom: "aarch" , assetsConfig: { // Custom asset configuration }, }, cosmWasmClient: existingClient , // Optional: pass pre-existing CosmWasmClient or ArchwayClient signer: offlineSigner , // Optional: pass OfflineSigner for transactions signingCosmWasmClient: signingClient , // Optional: pass pre-existing SigningCosmWasmClient or SigningArchwayClient });
All fields in customOverride are optional. Use them when you need to point the client at a custom deployment or pass in your own RPC/signer instances. API Reference Oracle methods The oracle is the pricing backbone of every Bolt swap. These methods give you access to the deterministic reference prices that the Outpost validates against.
getOracleConfig()
getPrice()
getAllPrices()
Returns the oracle contract configuration. const config = await client . getOracleConfig ();
Returns: OracleConfigField Type Description admin Address Oracle admin address priceThresholdRatio string Max deviation ratio before rejection priceExpireTime Duration or null Staleness window ({secs, nanos})
Fetches the current oracle price for a specific asset pair. const price = await client . getPrice ( baseDenom , quoteDenom );
Parameters: Param Type Description baseDenom string Base asset denom (e.g., IBC denom) quoteDenom string Quote asset denom
Returns: InvertiblePriceField Type Description assetPair string Format: baseDenom:quoteDenom price string Oracle reference price (decimal string) expiryTime string Expiration (Unix nanoseconds) isInverse boolean Whether pair is inverted
Fetches oracle prices for all supported asset pairs. const prices = await client . getAllPrices ();
Returns: Price[]Each Price contains assetPair, price, and expiryTime. Use getAllPrices() for batch quoting. More efficient than calling getPrice() per pair.
Asset methods Query which assets are supported on the Outpost and their oracle configurations.
getAssets()
getAllOracleAssetPairs()
Returns all supported assets with metadata. const assets = await client . getAssets ();
Returns: Asset[]Field Type Description symbol string Trading symbol (e.g., "ARCH") name string Full asset name chainId string Blockchain identifier denom string Chain-specific denomination (IBC or native) decimals number Decimal precision logo string? Optional logo URL coingeckoId string? Optional CoinGecko identifier
Returns all valid trading pairs with oracle price support. const pairs = await client . getAllOracleAssetPairs ();
Returns: OracleAssetPair[]Each pair contains base and quote objects with name, symbol, and precision. Router and pool methods Inspect the Router configuration and Outpost pool state. The Router is the entry-point contract unique to the Archway deployment.
getRouterConfig()
getAllPools()
getPoolConfig()
getPoolConfigByDenom()
Liquidity queries
Returns the Router’s default configuration. const routerConfig = await client . getRouterConfig ();
Returns: RouterConfigField Type Description admin string Router admin address defaultPriceOracleContract string Default oracle contract defaultProtocolFeeRecipient string Fee destination defaultProtocolFee string Default protocol fee rate defaultLpFee string Default LP fee rate
Returns all liquidity pools on the Outpost. const pools = await client . getAllPools ();
Returns: Pool[]Field Type Description poolAddress string On-chain contract address baseDenom string Base asset denomination quoteDenoms string[] Supported quote assets
Returns the full configuration for a specific pool. const config = await client . getPoolConfig ( contractAddress );
Returns: PoolConfigField Type Description priceOracleContract string Oracle this pool validates against protocolFeeRecipient string Protocol fee destination protocolFee string Protocol fee rate lpFee string LP fee rate allowanceMode string Pool access mode lps string[] Authorised LP addresses minBaseOut string Minimum output threshold
Looks up pool configuration by base asset denomination. const config = await client . getPoolConfigByDenom ( baseDenom );
Param Type Description baseDenom string Base asset denomination
Returns: PoolConfigTwo methods for inspecting pool liquidity: getPoolByDenom() const pool = await client . getPoolByDenom ( baseDenom );
Returns the Pool matching the given base denomination. getPoolBaseLiquidity() const liquidity = await client . getPoolBaseLiquidity ( poolContractAddress );
Returns BaseLiquidityDetails with baseLiquidity (a Coin: {amount, denom}) and totalShares. getAllBaseAssetsLiquidity() const allLiquidity = await client . getAllBaseAssetsLiquidity ();
Returns Record<Address, BaseLiquidityDetails> mapping every pool address to its current liquidity. Use getAllBaseAssetsLiquidity() when building a state indexer. One call gives you the full liquidity picture across all pools.
Swap methods Simulate swaps off-chain for quoting, then execute on-chain when ready.
Simulates a swap without executing it. Returns the expected output, fee breakdown, and settling pool address. const quote = await client . simulateSwap ({ assetIn: "ibc/usdc_denom" , amountIn: "1000000" , assetOut: "aarch" , });
Returns: SimulateSwapResultField Type Description poolAddress string Pool that would settle this trade amountOut string Expected output amount assetOut string Output asset denomination protocolFee string Protocol fee component lpFee string LP fee component dynamicFeePercentage string? Dynamic fee if applicable totalFees string Combined fees
Bolt quotes are deterministic. Given the same pool state and oracle price, simulateSwap() returns identical results whether called off-chain or on-chain.
Executes a swap transaction on the Outpost at the oracle-validated price. const result = await client . swap ( swapParams , signer );
Parameters: Param Type Description swapParams SwapParams Swap configuration (see types below) signer Signer Transaction signer
Returns: SwapResult<ExecuteResult>Field Type Description txOutput ExecuteResult Full CosmWasm execution result amountOut string Actual output amount received assetOut string Output asset denomination txHash string On-chain transaction hash
This executes a real on-chain transaction. Always call simulateSwap() first to verify the expected output, then use minimumAmountOut in your SwapParams to protect against state changes between simulation and execution.
Type definitions
type Asset = { symbol : string ; // "ARCH" name : string ; // "Archway" chainId : string ; // Chain identifier denom : string ; // Native or IBC denom decimals : number ; // 18 logo ?: string ; // Optional logo URL coingeckoId ?: string ; // Optional CoinGecko ID };
type SwapParams = { assetIn : string ; // Input asset denom amountIn : string ; // Amount in smallest units assetOut : string ; // Output asset denom minimumAmountOut ?: string ; // Slippage protection receiver ?: Address ; // Recipient (defaults to sender) };
Use minimumAmountOut rather than a slippage percentage. Calculate it from your simulateSwap() result: amountOut * (1 - tolerance).
type Pool = { poolAddress : string ; // Contract address baseDenom : string ; // Base asset denomination quoteDenoms : string []; // Supported quote assets }; type PoolConfig = { priceOracleContract : string ; protocolFeeRecipient : string ; protocolFee : string ; lpFee : string ; allowanceMode : string ; lps : string []; minBaseOut : string ; }; type BaseLiquidityDetails = { baseLiquidity : Coin ; // { amount: string, denom: string } totalShares : string ; };
type Price = { assetPair : string ; // "baseDenom:quoteDenom" price : string ; // Decimal string expiryTime : string ; // Unix nanoseconds }; type InvertiblePrice = { assetPair : string ; price : string ; expiryTime : string ; isInverse : boolean ; };
type OracleConfig = { admin : Address ; priceThresholdRatio : string ; priceExpireTime : Duration | null ; }; type Duration = { secs : number ; nanos : number ; }; type RouterConfig = { admin : string ; defaultPriceOracleContract : string ; defaultProtocolFeeRecipient : string ; defaultProtocolFee : string ; defaultLpFee : string ; }; type OracleAssetPair = { base : OracleAsset ; quote : OracleAsset ; }; type OracleAsset = { name : string ; symbol : string ; precision : number ; };
type SimulateSwapResult = { poolAddress : string ; amountOut : string ; assetOut : string ; protocolFee : string ; lpFee : string ; dynamicFeePercentage ?: string ; totalFees : string ; }; type SwapResult < ExecuteResult > = { txOutput : ExecuteResult ; amountOut : string ; assetOut : string ; txHash : string ; };
Error handling The SDK provides typed error classes for all failure modes. Wrap SDK calls in try-catch blocks and handle each type appropriately.
Error Cause Fix NotFoundError Asset, pool, or oracle not found Verify denoms and pool addresses InvalidParameterError Bad address or negative amount Validate inputs before calling InvalidObjectError Object does not exist on-chain Confirm addresses and network InvalidTypeError Type mismatch in params Ensure denoms and amounts are strings MissingParameterError Required field omitted Provide all non-optional fields TransactionFailedError On-chain execution failed Check gas, inventory, oracle freshness ParseError Failed to deserialize data Retry or switch RPC endpoint
import { NotFoundError , InvalidParameterError , TransactionFailedError , } from "@bolt-liquidity-hq/cosmwasm-client" ; try { const quote = await client . simulateSwap ({ assetIn: "ibc/usdc_denom" , amountIn: "1000000" , assetOut: "aarch" , }); } catch ( error ) { if ( error instanceof NotFoundError ) { console . error ( "Asset or pool not found:" , error . message ); } else if ( error instanceof TransactionFailedError ) { console . error ( "Transaction failed:" , error . message ); } else { throw error ; } }
Archway Outpost Addresses Contract addresses for mainnet and testnet.
Off-Chain Quoting Build price discovery using deterministic quoting.
Contract Math Understand the pricing formula behind simulateSwap().
Pool State Indexing Index pool state for real-time integration.
