> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multiliquid.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Every module, method, constant, and error class of the Multiliquid EVM SDK.

`@uniformlabs/multiliquid-evm-sdk` is the TypeScript SDK for the Multiliquid contracts, built on [viem](https://viem.sh). It wraps quoting, swapping, delegated authorization, asset and delegate reads, capital provider administration, \$TSY yield, and events, with typed inputs and decoded errors. For a walkthrough, start with [Swap on-chain](https://docs.multiliquid.xyz/evm/guides/integration.md).

## Install

```bash theme={null}
npm install @uniformlabs/multiliquid-evm-sdk viem
```

The package needs Node.js 22.23.4 or later on 22.x, 24.22.1 or later on 24.x, or 26.12.1 or later. It ships ES module and CommonJS builds with type declarations.

## Create a client

```typescript theme={null}
import { createPublicClient, createWalletClient, http } from "viem";
import { mainnet as mainnetChain } from "viem/chains";
import { createMultiliquidClient, loadEvmDeployment } from "@uniformlabs/multiliquid-evm-sdk";

const publicClient = createPublicClient({ chain: mainnetChain, transport: http(rpcUrl) });
const walletClient = createWalletClient({ account, chain: mainnetChain, transport: http(rpcUrl) });

const ml = createMultiliquidClient({
  deployment: await loadEvmDeployment({ chain: "mainnet" }),
  publicClient,
  walletClient, // optional: needed only for transactions and signatures
});
```

| Option | Required | Meaning |
| - | - | - |
| `deployment` | Yes | The contracts and asset IDs to use: a preset, a loaded deployment, or your own `ChainDeployment` |
| `publicClient` | Yes | A viem public client for reads, quotes, and simulation |
| `walletClient` | No | A viem wallet client with an account. Write and signing methods throw `NoWalletClientError` without it. |
| `apiBaseUrl`, `apiFetch` | No | Overrides for the Multiliquid API host and the `fetch` used to call it |

The client also exposes `ml.deployment`, `ml.publicClient`, and `ml.walletClient`. Write methods return the transaction hash without waiting for a receipt.

## Deployments

| Export | What it is |
| - | - |
| `mainnet`, `sepolia` | Presets bundled with the package: the `MultiliquidSwap` address, delegates, price adapters, tokens, and named asset IDs |
| `loadEvmDeployment({ chain, apiBaseUrl?, fetch? })` | Reads the current deployment from `GET /v1/info/evm` and merges it into the preset for `"mainnet"` or `"sepolia"`. Throws `EvmDeploymentMetadataError` on a malformed response or a chain ID mismatch. |
| `ChainDeployment` | The type of a deployment: `chainId`, `addresses`, and `assetIds` |

Asset IDs are under `deployment.assetIds.rwa` and `deployment.assetIds.stablecoin`, keyed by name, such as `assetIds.stablecoin.USDC`. A loaded deployment keeps the preset's names and adds the API's tokens under their symbols.

## Modules

### `ml.quote`

| Method | Does |
| - | - |
| `quoteSwap({ user, input, simulate?, operator?, receiver?, permit? })` | Calls `quoteSwap` for one leg. Returns `tokenInAmount`, `tokenOutAmount`, `issuerFee`, `spreadFee`, `lpFee`, `routeFamily`, `direction`, and `timestamp`. With `simulate: true`, it also runs `swap` as an `eth_call` from `operator` (default `user`) and adds `simulation: { success, error?, gasEstimate? }`. |

### `ml.swap`

| Method | Does |
| - | - |
| `swap({ inputs, user?, receiver?, permit? })` | Sends `swap`. `user` defaults to the wallet's account, `receiver` to `user`, and `permit` to an empty permit. |
| `buildSwapCalldata({ user, inputs, receiver?, permit? })` | Encodes `swap` calldata without sending it, for multisigs and relayers |
| `adjustSwapInputAllowance({ operator, assetInID, amount, increase })` | Changes the wallet's standing allowance for an operator |
| `getSwapInputAllowance(user, operator, assetInID)` | Reads a standing allowance |
| `signSwapApproval({ operator, inputs, deadline, user?, receiver?, nonce?, unordered? })` | Signs a permit with the wallet, which must be `user`. Reads the ordered nonce when `nonce` is omitted; an unordered permit needs an explicit `nonce`. Returns `{ deadline, signature, nonce, unordered }`. |
| `buildSwapApprovalTypedData({ user, operator, inputs, nonce, deadline, receiver?, unordered?, chainId? })` | Builds the permit's EIP-712 typed data for an external signer |
| `getSwapNonce(user)` | Reads `nonces(user)` |
| `isUnorderedNonceUsed(user, nonce)` | Reads `usedUnorderedNonces(user, nonce)` |
| `invalidateUnorderedNonce({ nonce })` | Cancels the wallet's unordered nonce |
| `getDomainSeparator()` | Reads `DOMAIN_SEPARATOR()` |
| `getAutoLiquidityStablecoinID(stablecoinID)` | Reads a delegate's auto-liquidity stablecoin |
| `getAutoLiquidityPreview({ user, input })` | Previews whether a leg would trigger a capital provider's prefund or sweep, with the vault's balances, allowances, and credits |

### `ml.assets`

| Method | Does |
| - | - |
| `getRWAInfo(rwaID)`, `getStablecoinInfo(stablecoinID)` | Read one registration, including its token `assetAddress` and `delegate` |
| `getAllRWAInfo(rwaIDs?)`, `getAllStablecoinInfo(stablecoinIDs?)` | Read several registrations, by default every one in the deployment |
| `getRWAPrice(rwaID)`, `getStablecoinUSDValue(stablecoinID)` | Read a USD price with 18 decimals |
| `getAllPrices({ rwaIDs?, stablecoinIDs? }?)` | Read several prices, each marked `adapter` or `manual` |
| `getProtocolFeeConfig(stablecoinID)` | Read the exemption, the protocol fee rate, the spread take rate, and their effective values |
| `isProtocolFeeExempt(stablecoinID)`, `getIssuerPaidProtocolFeeRate(stablecoinID)`, `getSpreadProtocolTakeRate()` | Read the protocol fee settings one by one |
| `getDiscountRate(stablecoinID, rwaID)`, `getRedemptionFee(stablecoinID, rwaID)` | Read a capital provider's RWA fees |
| `getStablecoinAcceptanceFee(stablecoinOutID, stablecoinInAddress)`, `getStablecoinRedemptionFee(stablecoinOutID, stablecoinInAddress)` | Read a capital provider's stablecoin fees |
| `isWhitelistedForRWA(rwaID, from, to, amount)` | Run the RWA's whitelist adapter check |
| `isBlacklisted(user)`, `isPaused()` | Read the protocol blacklist and pause state |

### `ml.delegates`

| Method | Does |
| - | - |
| `getDelegateAddress(stablecoinID)` | Resolves a registration's delegate, from the deployment or on-chain |
| `getDelegateInfo(stablecoinID)` | Reads the delegate's address, type (`balanceSheet` or `yield`), stablecoin, custody, and cold-storage addresses |
| `getRWACustodyAddress(stablecoinID)`, `getStablecoinCustodyAddress(stablecoinID)` | Read the custody wallets |
| `getRWAColdStorageAddresses(stablecoinID)`, `getStablecoinColdStorageAddresses(stablecoinID)` | Read the disclosed reserve wallets |
| `isRWAWhitelisted(stablecoinID, rwaAddress)`, `isStablecoinWhitelisted(stablecoinID, backingStablecoinAddress)` | Read the delegate's asset whitelists |

### `ml.issuerAdmin`

The capital provider admin module. It keeps the contracts' `issuerAdmin` name. Every write takes `stablecoinID` to resolve the delegate, plus the function's arguments:

| Method | Arguments besides `stablecoinID` |
| - | - |
| `whitelistRWA` | `rwa`, `accepted` |
| `whitelistStablecoin` | `stablecoin`, `accepted` |
| `setRWADiscountRate`, `setRWARedemptionFee` | `rwaID`, `rate` |
| `setStablecoinAcceptanceFee`, `setStablecoinRedemptionFee` | `stablecoin`, `rate` |
| `setAutoLiquidityStablecoinID` | `autoLiquidityStablecoinID` |
| `setRWACustodyAddress`, `setStablecoinCustodyAddress` | `custodyAddress` |
| `setBlacklist` | `account`, `blacklisted` |
| `addRWAColdStorageAddress`, `removeRWAColdStorageAddress`, `addStablecoinColdStorageAddress`, `removeStablecoinColdStorageAddress` | `coldStorageAddress` |
| `addIssuerAdmin`, `removeIssuerAdmin` | `issuerAdmin` |
| `pause`, `unpause` | None |

`isIssuerAdmin(stablecoinID, account)` reads the admin set. For a multisig, `buildIssuerAdminCalldata(method, params)` encodes the call, and `buildIssuerAdminTransaction(stablecoinID, method, params)` returns `{ to, data }` with the delegate resolved:

```typescript theme={null}
const tx = await ml.issuerAdmin.buildIssuerAdminTransaction(stablecoinID, "whitelistRWA", {
  rwa: rwaTokenAddress,
  accepted: true,
});
```

### `ml.yield`

For yield-bearing registrations such as \$TSY. Each method takes the registration's `stablecoinID` and throws `NotYieldBearingError` for any other.

| Method | Does |
| - | - |
| `getCredits(stablecoinID, user)`, `getTotalWithheldCredits(stablecoinID, user)`, `getWithheldCredits(stablecoinID, user)` | Read a user's main and withheld credits |
| `getYieldMultiplier(stablecoinID, user)`, `getLastAccrualDay(stablecoinID, user)` | Read a user's yield state |
| `getCurrentDay(stablecoinID)`, `getDailyRate(stablecoinID, dayNumber)`, `getDailyRates(stablecoinID, fromDay, toDay)` | Read days and posted net rates |
| `getYieldAmount({ stablecoinID, user, redeemValue, stablecoinWithdrawal })` | Value a withdrawal of `redeemValue` |
| `getAmountForTargetValue({ stablecoinID, user, targetDollars, stablecoinWithdrawal })` | Size a withdrawal for a target value |
| `accrueInterest(stablecoinID, user, maxDays?, maxRecords?)` | Accrues one user. Omitting the limits accrues without bounds. |
| `batchAccrueInterest(stablecoinID, users)` | Accrues several users |

### `ml.events`

| Method | Does |
| - | - |
| `getEvents({ user?, rwaID?, stablecoinID?, eventTypes?, fromBlock?, toBlock? })` | Reads past `Swap` events. `rwaID` matches either side of a leg, and `stablecoinID` also matches its `stablecoinDelegateID`. |
| `watchEvents(filter, callback)` | Watches new `Swap` events, and returns a function that stops watching |
| `parseLog(log)` | Decodes a raw log into a `SwapEvent`, or returns `undefined` |

A `SwapEvent` carries the event's fields, with the fees named `issuerFee`, `spreadFee`, and `lpFee`, and the raw `log`.

### `ml.multicall`

`read(calls)` batches any view calls through Multicall3, with each result typed from its ABI. It uses the deployment's `multicall3` address, or `CANONICAL_MULTICALL3_ADDRESS`.

## Constants and ABIs

| Export | Value |
| - | - |
| `ROUTE_IDS` | Route IDs `0n` to `11n`, such as `ROUTE_IDS.STABLE_TO_RWA_EXACT_IN` |
| `WAD` | `10n ** 18n` |
| `ROLES` | `DEFAULT_ADMIN`, `OPERATOR`, and `BLACKLISTER` role identifiers |
| `CANONICAL_MULTICALL3_ADDRESS`, `DEFAULT_EVM_INFO_API_BASE_URL` | Defaults the SDK falls back to |
| `multiliquidSwapAbi`, `stablecoinDelegateBaseAbi`, `balanceSheetDelegateAbi`, `treasuryDelegateAbi`, `yieldBearingDelegateAbi`, `priceAdapterAbi`, `whitelistAdapterAbi`, `erc20Abi` | `as const` ABIs for direct use with viem |

The package also exports the types it uses, such as `SwapInputs`, `ApprovalPermit`, `SwapResolved`, `SwapEvent`, and `ChainDeployment`.

## Errors

Every SDK error extends `MultiliquidError`.

| Class | Thrown when |
| - | - |
| `MultiliquidContractError` | A contract reverted. `errorName` and `args` hold the decoded custom error. |
| A subclass per known error, such as `UserNotWhitelistedError`, `InsufficientRWAOutputError`, or `StablecoinPriceOutsideBandError` | That custom error was raised by `MultiliquidSwap` or a stablecoin delegate |
| `ContractPausedError` | A contract raised `EnforcedPause` |
| `NoWalletClientError` | A write or signing method ran without a wallet client |
| `SignerMismatchError` | `signSwapApproval` was asked to sign for a `user` other than the wallet |
| `NotYieldBearingError` | A yield method was called for a registration that is not yield-bearing |
| `StablecoinDelegateNotSetError` | An `ml.issuerAdmin` method targets a registration with no delegate |
| `EvmDeploymentMetadataError` | `loadEvmDeployment` received an invalid deployment |

A revert from a contract the SDK has no ABI for, such as a price adapter or a token, becomes a `MultiliquidContractError` with `errorName` set to `UnknownContractError`. `decodeMultiliquidError(data)` decodes raw revert data the same way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.