Mento SDK

A TypeScript SDK for interacting with the Mento Protocol. Provides a simple interface for token swaps, liquidity management, borrowing, and trading status queries.

Installation

npm install @mento-protocol/mento-sdk viem
# or
pnpm add @mento-protocol/mento-sdk viem

viem is a peer dependency required for blockchain interactions.

Quick Start

import { Mento, ChainId, deadlineFromMinutes } from '@mento-protocol/mento-sdk'
import { parseUnits } from 'viem'

// Initialize the SDK (uses default public RPC)
const mento = await Mento.create(ChainId.CELO)

// Or with a custom RPC URL
const mento = await Mento.create(ChainId.CELO, 'https://your-rpc-url.com')

// Or with an existing viem PublicClient
const mento = await Mento.create(ChainId.CELO, yourPublicClient)

Services

The SDK is organized into service namespaces:

Service	Description
mento.tokens	Query stable tokens and collateral assets
mento.pools	Discover and inspect liquidity pools
mento.routes	Find trading routes (direct and multi-hop)
mento.quotes	Get expected swap output amounts
mento.swap	Build swap transactions with approvals
mento.trading	Check circuit breakers and trading limits
mento.liquidity	Add/remove liquidity, zap in/out
mento.borrow	Open, adjust, and close troves

Token Queries

// Get all Mento stable tokens
const stableTokens = await mento.tokens.getStableTokens()

// Get all collateral assets
const collateral = await mento.tokens.getCollateralAssets()

Swaps

const USDm = '0x765DE816845861e75A25fCA122bb6898B8B1282a'
const CELO = '0x471EcE3750Da237f93B8E339c536989b8978a438'

// Get a quote
const amountIn = parseUnits('100', 18)
const expectedOut = await mento.quotes.getAmountOut(USDm, CELO, amountIn)

// Build a swap transaction (includes approval if needed)
const { approval, swap } = await mento.swap.buildSwapTransaction(
  USDm,
  CELO,
  amountIn,
  recipientAddress,
  ownerAddress,
  { slippageTolerance: 0.5, deadline: deadlineFromMinutes(5) }
)

// Execute with any viem wallet client
if (approval) {
  await walletClient.sendTransaction(approval)
}
await walletClient.sendTransaction(swap.params)

Routes

// Find a route between two tokens
const route = await mento.routes.findRoute(USDm, CELO)
console.log(`Hops: ${route.path.length}`)

// Get all tradable routes (uses pre-generated cache by default)
const routes = await mento.routes.getRoutes()

// Generate fresh routes from blockchain
const freshRoutes = await mento.routes.getRoutes({ cached: false })

Trading Status

// Check if a pair is tradable (circuit breaker check)
const isTradable = await mento.trading.isPairTradable(USDm, CELO)

// Get full tradability status for a pool
const pools = await mento.pools.getPools()
const status = await mento.trading.getPoolTradabilityStatus(pools[0])

if (!status.circuitBreakerOk) {
  console.log('Trading suspended by circuit breaker')
} else if (!status.limitsOk) {
  console.log('Trading limit reached')
}

Liquidity

// Add liquidity to a pool
const addTx = await mento.liquidity.buildAddLiquidityTransaction(
  poolAddress, tokenA, amountA, tokenB, amountB,
  recipient, owner,
  { slippageTolerance: 0.5, deadline: deadlineFromMinutes(5) }
)

// Zap in with a single token
const zapTx = await mento.liquidity.buildZapInTransaction(
  poolAddress, tokenIn, amountIn, 0.5, // split ratio
  recipient, owner,
  { slippageTolerance: 0.5, deadline: deadlineFromMinutes(5) }
)

// Get LP token balance
const balance = await mento.liquidity.getLPTokenBalance(poolAddress, owner)

Borrowing

import { parseUnits } from 'viem'

// Find a safe ownerIndex for the account that will submit the transaction
const ownerIndex = await mento.borrow.findNextAvailableOwnerIndex('USDm', ownerAddress, ownerAddress)

// Open a trove (borrow against collateral)
const openTx = await mento.borrow.buildOpenTroveTransaction('USDm', {
  owner: ownerAddress,
  ownerIndex,
  collAmount: parseUnits('10', 18),
  boldAmount: parseUnits('1000', 18),
  annualInterestRate: parseUnits('0.05', 18), // 5%
  maxUpfrontFee: parseUnits('100', 18),
})

// For smart accounts, pass the smart account address as the third argument above.

// Get trove data
const trove = await mento.borrow.getTroveData('USDm', troveId)

// Get troves currently owned by an address via the Trove NFT
const troves = await mento.borrow.getUserTroves('USDm', ownerAddress)

// Zombie troves are still-open troves whose debt fell below the branch minimum debt,
// typically after redemption. They can still hold collateral, and may even have 0 debt.
if (trove.status === 'zombie') {
  // Reactivate by adjusting the zombie trove, or close it to withdraw remaining collateral.
  const closeTx = await mento.borrow.buildCloseTroveTransaction('USDm', trove.troveId)
}

// Get system parameters
const params = await mento.borrow.getSystemParams('USDm')

// Predict upfront fee before opening
const fee = await mento.borrow.predictOpenTroveUpfrontFee(
  'USDm',
  parseUnits('1000', 18),
  parseUnits('0.05', 18)
)

Notes:

• getUserTroves() reflects current Trove NFT ownership. It includes zombie troves still owned by the address, even though zombie troves are removed from SortedTroves.
• status === 'zombie' does not mean liquidated. Zombie troves can still exist with collateral remaining on-chain, including the case where debt === 0.
• Use buildClaimCollateralTransaction() for collateral surplus after liquidation. For zombie troves with remaining collateral, use buildCloseTroveTransaction() to withdraw it, or buildAdjustZombieTroveTransaction() to reactivate the trove.

Supported Chains

Chain	Chain ID	Constant
Celo Mainnet	42220	ChainId.CELO
Celo Sepolia	11142220	ChainId.CELO_SEPOLIA

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

Cache Generation

The SDK ships with pre-generated route and token caches for fast startup:

pnpm cacheRoutes
pnpm cacheTokens

Override RPC URLs via environment variables:

CELO_RPC_URL=https://your-rpc.com pnpm cacheRoutes
CELO_SEPOLIA_RPC_URL=https://your-sepolia-rpc.com pnpm cacheTokens

License

MIT