Integration Overview
The Multiliquid Protocol on Solana can be integrated via the official TypeScript SDK, which provides a complete interface for quoting, building, and executing swaps against the on-chain program, along with liquidity-provider administration flows. The SDK is built on Solana Kit (@solana/kit) and uses native bigint values for token amounts. There is no Anchor or @solana/web3.js runtime dependency.
SDK Installation
Install and configure the TypeScript SDK
Pair Discovery
Find available trading pairs
Quoting
Get swap quotes using client-side math or simulation
Executing Swaps
Build and submit swap transactions
LP Admin
Create, update, and close pairs and manage liquidity
Ladder Pricing Model
Implement a rolling 24-hour laddered pricing model as an LP
Installation
@solana/kit@solana-program/token-2022
@solana/kit directly when importing Kit helpers such as address, createSolanaRpc, and signTransaction in application code. Node.js >=24 is required.
Client Initialization
The SDK provides aMultiliquidClient class that wraps all functionality. Addresses are Kit Address values (branded strings), created with address():
cluster selects the built-in pair registry and default program address. Both devnet and mainnet use the same swap program ID: HaWDr94LKJQT2fXuHJGsSGeQf6M7S68FXpEQLcE5RYs6. Pass programAddress to override that default. Optional registryApiUrl, registryFetchTimeoutMs, and onRegistryError configure metadata-API pair discovery.
Pair Discovery
Metadata Registry
getPairs() queries the Multiliquid metadata API and falls back to the bundled registry:
getOfflinePairs() returns the bundled registry without an HTTP call.
On-Chain Discovery (RPC)
For dynamically discovering pairs not in the registry:Checking Pair Status
Before executing a swap, verify the pair is active. Callers pass the tokens being spent and received; the SDK resolves pair ordering:pairAddress when both on-chain pair orderings exist for the same LP and mint pair.
Quoting
The SDK offers two quoting methods: client-side math replication and on-chain simulation. Callers specify the tokens spent and received. The SDK checks both possible on-chain pair orderings and translates the result to the protocol’s quote-to-base or base-to-quote direction internally. If both orderings exist for the same LP and mint pair, passpairAddress to disambiguate.
Client-Side Quote
Replicates the on-chain Rust math exactly usingbigint. Fetches current NAV prices from oracles and computes the swap result:
protocolFees is denominated in feeTokenMint and is paid from the LP fee vault. It is not deducted from the trader’s input.
The SwapQuote includes:
Simulation Quote
Builds a swap instruction with ATA creation disabled, simulates it against the validator, and parses the emitted event:computeUnitsConsumed as bigint, which is useful for setting compute-budget instructions.
Executing Swaps
The SDK is instruction-first: the primary API returns KitInstruction objects for maximum composability. A convenience method for building unsigned Kit transactions is also available.
Building a Swap Transaction
user must sign before submission.
Building Individual Instructions
For more control, build the swap instruction separately and compose it with other instructions (for example, compute budget):The SDK does not include compute-budget instructions automatically. Integrators that need priority fees or explicit compute limits can compose
@solana-program/compute-budget instructions as shown above. Use getQuoteViaSimulation() to measure actual compute units consumed.Swap Examples
Buy RWA with USDC (ExactIn) Swap exactly 1000 USDC for USTB, accepting at minimum 990 USTB:Swap Parameters Reference
Swap instruction and transaction results expose the resolved
onchainDirection (SwapDirection.QuoteToBase or SwapDirection.BaseToQuote).
LP Admin and Liquidity
Liquidity providers create, configure, and close their own pairs, and manage vault balances, using the same instruction-first API. The SDK derives PDAs, vault authorities, token program IDs, and Token-2022 transfer-hook accounts automatically. The LP signs every builder below. Forclose_pair, the global-config admin is referenced as a non-signing account; the SDK fetches it from GlobalConfig when it is not supplied via admin.
Permissioned Token Whitelisting
For every permissioned mint used by an LP, the token issuer must separately whitelist (allowlist) both of these addresses:- LP admin address — the
liquidityProviderwallet that owns and authorizes the LP’s source and recipient token accounts. - Vault authority PDA — the LP-specific PDA derived from
["vault_authority", liquidityProvider]that owns the program’s vault ATAs.
init_pair can create the vault ATA, but the Multiliquid program and SDK cannot grant issuer approval or bypass a frozen-account restriction. add_liquidity, remove_liquidity, and swaps involving that vault will fail until the required accounts are authorized and thawed.
Derive the address that must be submitted to the issuer before funding the pair. Kit PDA helpers are asynchronous:
Create a Pair
init_pair is LP-signed: the liquidity provider pays for the Pair PDA, LP-stable configs, vault ATAs, and UserVaultInfo accounts. Callers pass unordered mintA and mintB values. The builder compares the decoded 32-byte public keys, derives the canonical quote/base PDA order, and places optional LP-stable configs according to each side’s on-chain AssetType. Stable-on-base, stable-on-quote, and RWA-to-RWA pairs are supported. Fee combinations where redemptionFeeBps + discountRateBps >= 10_000 are rejected.
Update Pair Configuration
Update and close builders resolve both possible PDA mint orders and use the existing pair account’s stored quote/base layout. PasspairAddress when both orders exist.
Add and Remove Liquidity
lpTokenAccount when the liquidity provider uses a non-ATA token account. Set autoCreateAta: false if token accounts are managed externally, and use remainingAccounts only for extra accounts beyond those derived by the SDK.
Close a Pair
close_pair is LP-signed and reclaims rent for the Pair PDA, and — when the pair was the last consumer of a shared vault — the vault ATA and UserVaultInfo PDA. Any remaining vault balances are returned to the LP’s recipient token accounts. The SDK reads UserVaultInfo.used for both vaults and only resolves Token-2022 transfer-hook accounts when the shared-vault counter shows the close will transfer.
Event Parsing
ParseSwapExecuted events from transaction logs:
Error Handling
The SDK provides structured error parsing for on-chain program errors:Amount Formatting
Convert between native token amounts (with decimals) and human-readable strings. Formatting uses decimal strings andbigint; no floating-point arithmetic is involved:
Reading On-Chain State
Fetch All Swap State (Single RPC Call)
Fetch Individual Accounts
PDA Derivation
All program accounts are deterministic PDAs. Kit PDA derivation is asynchronous; every helper returnsPromise<ProgramDerivedAddress>, whose resolved value is [address, bump]:
quoteMint / baseMint. For a new pair, canonicalize the unordered mints first:
(mint, vaultAuthority), where vaultAuthority is the LP-specific PDA derived from ["vault_authority", lp]. Fee vault token accounts are ATAs for (feeMint, programAuthority), where programAuthority is the global PDA derived from ["program_authority"].
When deriving vault or fee-vault addresses manually for Token-2022 mints, pass the Token-2022 program ID as the optional tokenProgram argument. Swap and liquidity builders detect the mint owner and derive the correct ATAs automatically.
Integration Best Practices
Security
- Use Hardware Wallets: Never store private keys in code or environment variables for production
- Simulate First: Always call
getQuote()orgetQuoteViaSimulation()before executing - Set Slippage: Always provide
minAmountOutormaxAmountInfor production swaps - Check Pause State: Call
checkPauseStatus()before building transactions
Performance
- Use Client-Side Quotes:
getQuote()is faster thangetQuoteViaSimulation()for most use cases - Set Compute Budget: Use
computeUnitsConsumedfrom simulation to set appropriate compute limits - Reuse Client: Create one
MultiliquidClientinstance and reuse across operations - Use the Registry:
getPairs()uses the metadata API with a bundled fallback;getOfflinePairs()avoids network calls
Operational
- Priority Fees: Set appropriate priority fees via compute-budget instructions for time-sensitive operations
- Confirmation: Wait for
confirmedorfinalizedcommitment before treating a swap as complete - Event Monitoring: Use
parseSwapEventsFromTransaction()to verify swap results after execution - Error Recovery: Use
parseSwapError()to categorize failures and implement appropriate retry logic
Testing
Devnet
Configure the client for devnet testing:Mainnet
Support and Resources
- Protocol Website: https://www.multiliquid.xyz/
- Program IDL: See Program IDL page
- Deployment Addresses: See Deployments page