@mania-labs/mania-sdk

Official SDK for interacting with Mania Fun - an EVM-based token launchpad using bonding curves.

Overview

Mania Protocol enables anyone to create and trade tokens on a bonding curve. When a token's bonding curve reaches the migration threshold, liquidity is automatically migrated to Uniswap V3, providing deep liquidity for the token.

The SDK supports Robinhood Chain, Arc, and Stable deployments:

| | Robinhood Chain (standard) | Arc (native USDC) | Stable (native USDT0) | |---|---|---|---| | Factory contract | ManiaFactoryUpgradeable | ManiaFactoryArc | ManiaFactoryArc | | Native gas token | ETH | USDC (18 decimals at native level) | USDT0 (18 decimals at native level) | | Migration threshold | 4 ETH | 9,310 USDC (configured per deployment) | 9,310 USDT (configured per deployment) | | First-buy fee | 0.001 ETH | 1 USDC | 1 USDT | | Migrated pools quote in | WETH | Canonical USDC interface (6 decimals) | Canonical USDT0 interface (6 decimals) |

The SDK picks the right contract ABI and semantics automatically from the chain ID (or an explicit variant in the config). All amounts in the SDK API are native wei (18 decimals) on every chain — on Arc and Stable, parseEther("1") is 1 USDC/USDT0; the 6-decimal stablecoin ERC-20 view is only used internally for the Uniswap pool leg.

Key Features

• Bonding Curve Trading: Buy and sell tokens on a constant product AMM
• Fair Launch: Every token starts with the same bonding curve parameters
• Automatic Migration: Liquidity migrates to Uniswap V3 when threshold is reached
• Creator Rewards: Token creators earn 0.30% of all trading fees

Important Notes

Tokens will be non-transferrable until migration. This is a critical security feature to prevent pre-initialisation of Uniswap pools at unfavourable prices. This ensures all tokens on a deployment migrate with equal reserves (the configured migration threshold : 206.9M tokens).

The Mania Factory contract is upgradeable via a UUPS proxy pattern. Updates will be pushed sparingly, with significant notice for all integrators and SDK users. To stay informed about any upcoming updates, please join our Telegram channel at https://t.me/maniaFunDevelopers

Installation

npm install @mania-labs/mania-sdk viem
# or
yarn add @mania-labs/mania-sdk viem
# or
pnpm add @mania-labs/mania-sdk viem

Quick Start

import { ManiaSDK } from "@mania-labs/mania-sdk";
import { parseEther } from "viem";
import { arcTestnet } from "viem/chains";

// Arc Testnet: bundled factory address, chain ID, and RPC
const sdk = ManiaSDK.fromChainId(5042002);

// Connect a wallet for transactions
sdk.connectWallet(process.env.PRIVATE_KEY!, arcTestnet);

// Get token information
const tokenInfo = await sdk.getTokenInfo("0x...");
console.log("Current Price:", tokenInfo.currentPrice);
console.log("Migration Progress:", tokenInfo.migrationProgress, "%");

Usage

Creating a Token

// Create a new token
const result = await sdk.create({
  name: "My Token",
  symbol: "MTK",
  uri: "ipfs://...", // Metadata URI (see Token Metadata below)
  creator: "0x...", // Creator address (receives fees)
});

console.log("Token created:", result.tokenAddress);
console.log("Transaction:", result.hash);

Token Metadata

The uri parameter should point to an IPFS URL containing a JSON metadata file. You must upload your metadata JSON to IPFS first, then pass the resulting IPFS URL to the uri field.

Metadata Structure:

{
  "name": "HOMER",
  "symbol": "HOMER",
  "description": "A description of your token",
  "image": "ipfs://bafybeigpul3iw2yok735e7ozc5siwg7l3gcmuovcsawkzelsq7kwbtexxu",
  "attributes": {
    "twitter": "https://x.com/yourproject",
    "website": "https://yourproject.com",
    "github": "https://github.com/yourproject",
    "discord": "https://discord.gg/yourproject"
  }
}

Fields:

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Token display name | | symbol | Yes | Token symbol (ticker) | | description | No | Description of the token | | image | No | IPFS URL to token image (e.g., ipfs://bafy...) | | attributes | No | Social links and additional metadata |

Adding an Image:

1. Upload your image to IPFS (using Pinata, NFT.Storage, or any IPFS pinning service)
2. Get the resulting CID (e.g., bafybeigpul3iw2yok735e7ozc5siwg7l3gcmuovcsawkzelsq7kwbtexxu)
3. Use the ipfs:// protocol prefix: ipfs://<CID>
4. Include this URL in the image field of your metadata JSON
5. Upload the complete metadata JSON to IPFS
6. Pass the metadata IPFS URL as the uri parameter when creating the token

Example:

// After uploading metadata.json to IPFS and getting the CID
const metadataUri = "ipfs://bafkreihdwdcef3fksy7ygjxwfxjfujdi4mfg6rn4m5jqnz3gyvhqorvnrm";

const result = await sdk.create({
  name: "HOMER",
  symbol: "HOMER",
  uri: metadataUri,
  creator: "0x...",
});

Create and Buy in One Transaction

// Create token and buy in a single transaction
const result = await sdk.createAndBuy({
  name: "My Token",
  symbol: "MTK",
  uri: "ipfs://...",
  creator: "0x...",
  buyAmountEth: parseEther("0.1"), // Buy with 0.1 ETH
  minTokensOut: 0n, // Set minimum for slippage protection
});

Buying Tokens

import { parseEther } from "viem";

// Buy with manual slippage
const quote = await sdk.getBuyQuote(tokenAddress, parseEther("0.1"));
const minTokensOut = (quote * 99n) / 100n; // 1% slippage

await sdk.buy({
  token: tokenAddress,
  amountEth: parseEther("0.1"),
  minTokensOut,
});

// Or use built-in slippage calculation
await sdk.buyWithSlippage(
  tokenAddress,
  parseEther("0.1"),
  100 // 1% slippage in basis points
);

Selling Tokens

// Sell tokens
const tokenAmount = parseEther("1000"); // 1000 tokens
const quote = await sdk.getSellQuote(tokenAddress, tokenAmount);
const minEthOut = (quote * 99n) / 100n; // 1% slippage

await sdk.sell({
  token: tokenAddress,
  amountTokens: tokenAmount,
  minEthOut,
});

// Or use built-in slippage calculation
await sdk.sellWithSlippage(tokenAddress, tokenAmount, 100);

Working with Bonding Curves

import { BondingCurve } from "@mania-labs/mania-sdk";

// Get bonding curve instance for calculations
const curve = await sdk.getBondingCurveInstance(tokenAddress);

// Get current state
const state = curve.getState();
console.log("Virtual Token Reserves:", state.virtualTokenReserves);
console.log("Virtual ETH Reserves:", state.virtualEthReserves);

// Check status
console.log("Is Complete:", curve.isComplete());
console.log("Is Migrated:", curve.isMigrated());

// Get quotes locally (no RPC call)
const buyQuote = curve.getBuyQuote(parseEther("0.1"));
console.log("Tokens Out:", buyQuote.tokensOut);
console.log("Fee:", buyQuote.fee);
console.log("Price per Token:", buyQuote.pricePerToken);

// Calculate price impact
const priceImpact = curve.calculateBuyPriceImpact(parseEther("1"));
console.log("Price Impact:", priceImpact, "%");

// Get migration progress
console.log("Migration Progress:", curve.getMigrationProgress(), "%");
console.log("ETH Until Migration:", curve.getEthUntilMigration());

Migration to Uniswap V3

// Check if curve is complete
const isComplete = await sdk.isComplete(tokenAddress);

if (isComplete) {
  // Migrate liquidity to Uniswap V3
  // Note: Caller pays the migration fee (poolMigrationFee)
  const result = await sdk.migrate({ token: tokenAddress });
  console.log("Pool Address:", result.poolAddress);
}

Watching Events

// Watch for new token creations
const unwatch = sdk.watchCreateEvents((event) => {
  console.log("New token created:", event.mint);
  console.log("Name:", event.name);
  console.log("Symbol:", event.symbol);
  console.log("Creator:", event.creator);
});

// Watch trades on a specific token
sdk.watchTradeEvents(tokenAddress, (event) => {
  console.log(event.isBuy ? "Buy" : "Sell");
  console.log("ETH Amount:", event.ethAmount);
  console.log("Token Amount:", event.tokenAmount);
  console.log("User:", event.user);
});

// Watch for curve completions
sdk.watchCompleteEvents((event) => {
  console.log("Curve complete:", event.mint);
});

// Watch for migrations
sdk.watchMigrationEvents((event) => {
  console.log("Token migrated:", event.mint);
  console.log("Pool:", event.pool);
});

// Stop watching
unwatch();

Reading Token Metadata

// Get token name and symbol
const { name, symbol } = await sdk.getTokenMetadata(tokenAddress);
console.log("Name:", name);
console.log("Symbol:", symbol);

Reading Global State

const globalState = await sdk.getGlobalState();

console.log("Fee Basis Points:", globalState.feeBasisPoints); // 100 = 1%
console.log("Migration Enabled:", globalState.enableMigrate);
console.log("Pool Migration Fee:", globalState.poolMigrationFee);
console.log("Token Total Supply:", globalState.tokenTotalSupply);
// Always populated: configurable factory values on Arc/Stable, fixed factory values elsewhere
console.log("Migration Threshold:", globalState.migrationThreshold);
console.log("First Buy Fee:", globalState.firstBuyFee);

Using the SDK on Arc and Stable (native-stablecoin chains)

Arc and Stable are EVM chains whose native gas token is a stablecoin — USDC on Arc, USDT0 on Stable — with 18 decimals at the native level (1 USDC/USDT0 = 1e18 wei, so parseEther/formatEther work as usual). The SDK targets the ManiaFactoryArc contract there, which has a different ABI and chain-configured economics.

import { ManiaSDK, nativeToUsdc, usdcToNative } from "@mania-labs/mania-sdk";
import { parseEther } from "viem";

// Arc Testnet (5042002) or Stable Mainnet (988) — bundled factory address and RPC
const sdk = ManiaSDK.fromChainId(988);
console.log(sdk.variant); // "arc"

// Amounts are native wei: this buys with 5 USDT0
await sdk.buyWithSlippage(tokenAddress, parseEther("5"), 100);

// The SDK returns the deployed economics
const globalState = await sdk.getGlobalState();
console.log(globalState.migrationThreshold); // e.g. 9310000000000000000000n (9,310 USDT)
console.log(globalState.firstBuyFee); // e.g. 1000000000000000000n (1 USDT)

// Pull-based fees: creator fee shares (and fee pushes that fail, e.g. a
// blocklisted recipient) accrue and are claimable. Also available on standard
// chains running the pull-fee factory (Robinhood chains).
const pending = await sdk.getPendingFees(myAddress);
if (pending > 0n) {
  await sdk.claimPendingFees(); // or claimPendingFees(otherAddress) to route elsewhere
}

// The canonical stablecoin ERC-20 interface (a 6-decimal view over the same
// native balance): USDC 0x3600...0000 on Arc, USDT0 0x779D...3736 on Stable
const stable = await sdk.getUsdcAddress();

// Converting between native wei and 6-decimal stablecoin ERC-20 units
nativeToUsdc(parseEther("1")); // 1000000n  (1 USDC/USDT0 in 6-decimal units)
usdcToNative(1_000_000n); // 1000000000000000000n

Notes for Arc and Stable:

• First-buy fee matters for quotes: the first buy on a curve pays a fixed fee (1 USDC/USDT) on top of the 1% trading fee. BondingCurve.getBuyQuote and buyWithSlippage account for it automatically whenever realEthReserves == 0.
• Migrated pools quote in the stablecoin, not WETH. getMigratedBuyQuote/getMigratedSellQuote still take and return native 18-decimal amounts — the SDK converts to/from the pool's 6-decimal leg internally.
• No QuoterV2 on Arc testnet: migrated-pool quotes there are computed locally from pool state (slot0 + liquidity). This is exact for the migration-minted full-range liquidity and an estimate if third parties add concentrated liquidity. Stable has the canonical QuoterV2, which the SDK uses.
• The pendingEthFees/claimPendingFees mechanism exists because these chains enforce the stablecoin issuer's blocklist at the protocol level — a value transfer to a blocklisted address reverts, and fees for such recipients accrue instead of blocking trading.

Creator fees are pull-based (Robinhood mainnet + testnet, Arc testnet, Stable mainnet)

Factories running the pull-based creator-fee implementation (the 2026-07-19 upgrade — currently Robinhood Chain mainnet, Robinhood Chain testnet, Arc testnet, and Stable mainnet) no longer push the creator's 30% share of each 1% trading fee. Instead it accrues to pendingEthFees[creator] (watch CreatorFeeAccrued via watchCreatorFeeEvents) and the creator claims it with claimPendingFees(to?):

const sdk = ManiaSDK.fromChainId(46630); // Robinhood Chain Testnet

const unwatch = sdk.watchCreatorFeeEvents(creatorAddress, (e) => {
  console.log(`accrued ${e.amount} wei from token ${e.mint}`);
});

const pending = await sdk.getPendingFees(creatorAddress);
if (pending > 0n) await sdk.claimPendingFees();

Trading Migrated Tokens

After a token migrates to Uniswap V3, use these methods to get quotes:

import { parseEther } from "viem";

// Check if token has migrated
const isMigrated = await sdk.isMigrated(tokenAddress);

if (isMigrated) {
  // Get Uniswap V3 pool address
  const poolAddress = await sdk.getPoolAddress(tokenAddress);
  console.log("Pool:", poolAddress);

  // Get buy quote (ETH -> Token)
  const tokensOut = await sdk.getMigratedBuyQuote(tokenAddress, parseEther("1"));
  console.log("Tokens for 1 ETH:", tokensOut);

  // Get sell quote (Token -> ETH)
  const ethOut = await sdk.getMigratedSellQuote(tokenAddress, parseEther("1000"));
  console.log("ETH for 1000 tokens:", ethOut);
}

Utility Functions

import {
  formatEthValue,
  formatTokenAmount,
  parseEthValue,
  calculateWithSlippage,
  formatPrice,
  formatMarketCap,
  truncateAddress,
  bpsToPercent,
} from "@mania-labs/mania-sdk";

// Format values for display
console.log(formatEthValue(parseEther("1.234567"))); // "1.2346"
console.log(formatTokenAmount(parseEther("1234567890"))); // "1.23B"
console.log(formatPrice(1234567890123456n)); // "0.0012"
console.log(formatMarketCap(parseEther("1500"))); // "1.50K ETH"

// Calculate slippage
const minOut = calculateWithSlippage(parseEther("100"), 100); // 1% slippage

// Format addresses
console.log(truncateAddress("0x1234...5678")); // "0x1234...5678"

// Convert basis points
console.log(bpsToPercent(100)); // 1

Constants

import {
  MIGRATION_THRESHOLD,
  TOKENS_FOR_LP,
  PROTOCOL_FEE_BASIS_POINTS,
  CREATOR_FEE_BASIS_POINTS,
  DEFAULT_SLIPPAGE_BPS,
  UNISWAP_FEE_TIER,
} from "@mania-labs/mania-sdk";

// Migration threshold: 4 ETH
console.log(MIGRATION_THRESHOLD); // 4000000000000000000n

// Tokens allocated for LP: 206.9M
console.log(TOKENS_FOR_LP);

// Fee breakdown
console.log(PROTOCOL_FEE_BASIS_POINTS); // 70 (0.70%)
console.log(CREATOR_FEE_BASIS_POINTS); // 30 (0.30%)

// Default slippage: 1%
console.log(DEFAULT_SLIPPAGE_BPS); // 100

// Uniswap V3 fee tier: 0.3%
console.log(UNISWAP_FEE_TIER); // 3000

Chain Configuration

import { getChainConfig, CHAIN_CONFIGS } from "@mania-labs/mania-sdk";

// Get config for a specific chain
const config = getChainConfig(5042002);
console.log(config?.factoryAddress);
console.log(config?.factoryVariant); // "standard" | "arc"
console.log(config?.quoteTokenAddress); // WETH on Robinhood Chain, USDC on Arc, USDT0 on Stable
console.log(config?.nativeCurrency.symbol); // "ETH", "USDC", or "USDT0"

// Or create SDK from chain ID
const sdk = ManiaSDK.fromChainId(5042002);

Bundled deployments:

| Chain | Chain ID | Factory | RPC | Explorer | |---|---:|---|---|---| | Arc Testnet | 5042002 | 0x9274745B9Ee36c9D69fC95FA03B29CaD7D9f1179 | https://rpc.testnet.arc.network | https://testnet.arcscan.app | | Robinhood Chain Testnet | 46630 | 0x9274745B9Ee36c9D69fC95FA03B29CaD7D9f1179 | https://rpc.testnet.chain.robinhood.com | https://explorer.testnet.chain.robinhood.com | | Robinhood Chain | 4663 | 0x2Db865C736c46CB17EB9E603777a9569464a09b1 | https://rpc.mainnet.chain.robinhood.com | https://robinhoodchain.blockscout.com | | Stable | 988 | 0x0c56FCEf5F226361C389b7722351e41aC1d8e853 | https://rpc.stable.xyz | https://stablescan.xyz |

Arc Testnet contract configuration:

| Contract | Address | |---|---| | Mania Factory | 0x9274745B9Ee36c9D69fC95FA03B29CaD7D9f1179 | | Canonical USDC interface | 0x3600000000000000000000000000000000000000 | | Uniswap V3 Factory | 0xBa27C71bF06AB69723d9bd7c96F13d591Fd53A93 | | Nonfungible Position Manager | 0x2Db865C736c46CB17EB9E603777a9569464a09b1 |

Stable Mainnet contract configuration:

| Contract | Address | |---|---| | Mania Factory | 0x0c56FCEf5F226361C389b7722351e41aC1d8e853 | | Canonical USDT0 interface | 0x779Ded0c9e1022225f8E0630b35a9b54bE713736 | | Uniswap V3 Factory | 0x88F0a512eF09175D456bc9547f914f48C013E4aA | | Nonfungible Position Manager | 0x3BdC3437405f7D801b6036532713fc1F179136a6 | | QuoterV2 | 0xb070179E7032CdA868b53e6C1742F80c9e940d1A |

Advanced Usage

Custom Viem Clients

import { createPublicClient, createWalletClient, defineChain, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const arcTestnet = defineChain({
  id: 5042002,
  name: "Arc Testnet",
  nativeCurrency: { name: "USD Coin", symbol: "USDC", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.testnet.arc.network"] } },
});

const publicClient = createPublicClient({
  chain: arcTestnet,
  transport: http("https://rpc.testnet.arc.network"),
});

const walletClient = createWalletClient({
  account: privateKeyToAccount("0x..."),
  chain: arcTestnet,
  transport: http("https://rpc.testnet.arc.network"),
});

const sdk = new ManiaSDK({
  factoryAddress: "0x9274745B9Ee36c9D69fC95FA03B29CaD7D9f1179",
  chainId: 5042002,
  variant: "arc",
});

sdk.setPublicClient(publicClient);
sdk.setWalletClient(walletClient);

Direct ABI Access

import { MANIA_FACTORY_ABI, MANIA_FACTORY_ARC_ABI, ERC20_ABI } from "@mania-labs/mania-sdk";
import { getContract } from "viem";

// Use ABIs directly with viem
// (use MANIA_FACTORY_ARC_ABI on Arc — the two factories are ABI-incompatible)
const contract = getContract({
  address: factoryAddress,
  abi: MANIA_FACTORY_ABI,
  client: publicClient,
});

Protocol Details

Bonding Curve Formula

The protocol uses a constant product formula with virtual reserves:

tokensOut = (virtualTokenReserves * netEth) / (virtualEthReserves + netEth)
ethOut = (tokenAmount * virtualEthReserves) / (virtualTokenReserves + tokenAmount)

Fee Structure

• Total Trading Fee: 1.00% (100 basis points)
  • Protocol Fee: 0.70%
  • Creator Fee: 0.30%

Migration

When realEthReserves reaches the deployment's migration threshold:

1. Bonding curve is marked as complete
2. Anyone can call migrate() (paying poolMigrationFee)
3. Token trading is enabled (unlocked)
4. Liquidity (206.9M tokens + the full raised amount) is added to Uniswap V3 (paired with WETH on Robinhood Chain, the canonical USDC interface on Arc, or the canonical USDT0 interface on Stable)
5. LP NFT is sent to dead address (locked forever)

TypeScript Support

This package is written in TypeScript and includes full type definitions.

import type {
  BondingCurveState,
  GlobalState,
  CreateTokenParams,
  BuyParams,
  SellParams,
  TokenInfo,
  TransactionResult,
} from "@mania-labs/mania-sdk";

Error Handling

try {
  await sdk.buy({
    token: tokenAddress,
    amountEth: parseEther("10"), // Too much ETH
    minTokensOut: 0n,
  });
} catch (error) {
  // Common errors:
  // - BuyExceedsMigrationThreshold: Buy would exceed 4 ETH threshold
  // - BondingCurveComplete: Trading has ended
  // - TooLittleTokensReceived: Slippage exceeded
  console.error("Transaction failed:", error);
}

License

MIT