Integrate Stables
This guide walks through adding support for Mento stable assets in your application. Mento stables are ERC-20 tokens that track the value of fiat currencies.
Available Stable Assets
Mento supports a growing ecosystem of stable assets that track various fiat currencies, including USD, EUR, BRL, KES, GBP, and many more. Each stable asset is an ERC-20 token that maintains a peg to its respective fiat currency.
For the complete list of available stables and their contract addresses, see:
Mento Reserve - Live view of all supported stables with supply information
Contract Deployments - Smart contract addresses for all supported stables
Common Use Cases
DeFi Protocols
Accept Mento stables as collateral, enable lending/borrowing, or create liquidity pools with stable pairs.
Wallets
Display balances, enable transfers, and show accurate fiat values for Mento stable assets.
Payment Applications
Process merchant payments, remittances, or payroll using region-specific stable currencies.
Exchanges & Aggregators
List Mento stable pairs for spot trading or include in routing algorithms.
Integration Steps
Step 1: Add Token Contracts
Add the contract addresses for the stables you want to support:
// Example addresses (cUSD and cEUR on mainnet)
const STABLE_ADDRESSES = {
cUSD: "0x765DE816845861e75A25fCA122bb6898B8B1282a",
cEUR: "0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73",
// ... add other stables as needed
};
For the complete list of stable addresses across all networks, see Smart Contracts > Deployments.
Step 2: Configure Token Metadata
Add token symbols, decimals, and display information:
const TOKEN_CONFIG = {
cUSD: {
symbol: "cUSD",
decimals: 18,
name: "Celo Dollar",
icon: "path/to/cusd-icon.svg"
},
// ... other tokens*
};
Note: All token metadata can be read from the smart contract using standard ERC-20 metadata functions (
name()
,symbol()
,decimals()
). Token icons are available in the frontend monorepo.
Step 3: Implement Standard ERC-20 Operations
Use your existing ERC-20 handling for:
Reading balances:
balanceOf(address)
Transfers:
transfer(to, amount)
Approvals:
approve(spender, amount)
Allowances:
allowance(owner, spender)
Step 4: Handle Fiat Display Values
Mento stables maintain a peg with their respective fiat currencies under normal conditions (e.g., 1 cUSD ≈ 1 USD, 1 cEUR ≈ 1 EUR).
For precise exchange rates, especially during high volatility, query Sorted Oracles.
Step 5: Enable Cross-Stable Swaps (Optional)
If your application needs to swap between Mento stables:
import { Wallet, providers, utils } from "ethers";
import { Mento } from "@mento-protocol/mento-sdk";
// Using Mento SDK V1 & Ethers V5
const STABLE_ADDRESSES = {
cUSD: "0x765DE816845861e75A25fCA122bb6898B8B1282a",
cEUR: "0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73",
// ... add other stables as needed*
};
// Initialize SDK
const provider = new providers.JsonRpcProvider(
"https://forno.celo.org"
);
const signer = new Wallet(privateKey, provider);
const mento = await Mento.create(signer);
// Find the tradable pair path for the tokens to swap through the router
const tradablePair = await mento.findPairForTokens(
STABLE_ADDRESSES.cUSD,
STABLE_ADDRESSES.cEUR
);
// Convert 0.01 tokens to Wei (18 decimal places: 0.01 * 10^18)
const amountIn = utils.parseUnits("0.01", 18);
// Get a quote for a swap with the given amount in
const quoteAmountOut = await mento.getAmountOut(
STABLE_ADDRESSES.cUSD,
STABLE_ADDRESSES.cEUR,
amountIn,
tradablePair
);
// Increase cUSD allowance of the broker by amount in
const allowanceTxObj = await mento.increaseTradingAllowance(
cUSDTokenAddr,
amountIn,
tradablePair
);
const allowanceTx = await signer.sendTransaction(allowanceTxObj);
const allowanceReceipt = await allowanceTx.wait();
// Allow 1% slippage from quote
const expectedAmountOut = quoteAmountOut.mul(99).div(100);
// Build swap tx
const swapTxObj = await mento.swapIn(
cUSDTokenAddr,
cEURTokenAddr,
amountIn,
expectedAmountOut,
tradablePair
);
// Send swap tx
const swapTx = await signer.sendTransaction(swapTxObj);
const swapTxReceipt = await swapTx.wait();
See Integrate the Broker for detailed swap integration.
Working Examples
For complete, runnable examples of integrating Mento stables and swaps, check out the Mento SDK Examples repository. It includes:
Pair discovery queries
Swap implementations
TypeScript examples
Best Practices
Decimal Handling
All Mento stables use 18 decimals. Always use appropriate libraries for decimal math to avoid precision errors.
Gas Optimization
When supporting multiple operations, consider batching transactions or using multicall patterns.
User Experience
Show both token amounts and fiat values
Use familiar currency symbols ($, €, R$, CFA)
Network Support
Mento stables are native to Celo. For cross-chain use cases, work with official bridges:
Wormhole (cUSD)
Portal Bridge
Testing
Get testnet CELO from the Celo Faucet, then swap for your desired token on the Mento App
Use Alfajores testnet addresses for development
Test all ERC-20 operations (transfer, approve, etc.)
Verify fiat value display matches user expectations
Support
Discord: #general for any questions
Token Icons: Available in the frontend monorepo
Next Steps
For swap functionality, see Integrate the Broker
For accurate price feeds, see Integrate Oracles
For technical reference, see Smart Contracts
Last updated