How to integrate Madhouse

Integrate Madhouse swap functionality into your application in 3 simple steps: request a quote, approve tokens (if needed), and execute the swap.

Step 1: Request a Quote

To get a swap quote, send a GET request to the Madhouse API with the required parameters.

Endpoint:

GET https://api.madhouse.ag/swap/v1/quote

Required Parameters:

Parameter	Type	Description	Example
chain	string	Chain ID	10143 (Monad Testnet)
tokenIn	string	Address of input token (token to sell)	0x760AfE86e5de5fa0Ee542fc7B7B713e1c5425701
tokenOut	string	Address of output token (token to buy)	0xf817257fed379853cDe0fa4F97AB987181B1E5Ea
amountIn	string	Amount of input token in smallest unit	1000000000000000000 (1 token with 18 decimals)
slippage	number	Maximum acceptable slippage as decimal	0.005 (0.5%)

Optional Parameters:

Parameter	Type	Description	Example
protocols	string	Comma-separated list of protocols for routing	uniswap-v2,uniswap-v3
includeTokenInfo	boolean	Include detailed token information	true
includePoolInfo	boolean	Include pool information	true
integratorAddress	string	Your wallet address to receive integration fees	0xYourAddress...
integratorFee	number	Your fee percentage (required if integratorAddress is set) Format: Decimal number between 0 and 0.05 Range: 0% to 5%	0.01 = 1% 0.025 = 2.5% 0.05 = 5% Defined in src/api/types.ts:41-42: export const MIN_INTEGRATOR_FEE = 0; // 0% export const MAX_INTEGRATOR_FEE = 0.05; // 5%

Understanding Integrator Fees:

As an integrator, you can earn fees on every swap executed through your application:

• integratorFee is specified in decimal format:

  • 0.01 = 1%

  • 0.025 = 2.5%

  • 0.05 = 5%

• The fee is deducted from amountIn before the swap

• Example: User wants to swap 100 USDC with integratorFee= 0.01 (1%):

  • You receive: 1 USDC (sent to your integratorAddress)

  • Swap amount: 99 USDC actually gets swapped for tokenOut

  • User receives: Whatever 99 USDC swaps to in tokenOut

• integratorAddress is required when integratorFee > 0

Fee Calculation Examples:

// 1% fee
integratorFee: '0.01'     // You get 1% of amountIn

// 0.5% fee  
integratorFee: '0.005'     // You get 0.5% of amountIn

// 0.3% fee
integratorFee: '0.003'     // You get 0.3% of amountIn

// 0.1% fee
integratorFee: '0.001'     // You get 0.1% of amountIn

Important Notes:

• Token Amounts: Always use smallest unit (e.g., 1 USDC with 6 decimals = 1000000, 1 WMON with 18 decimals = 1000000000000000000)

• Slippage: Specified as decimal (e.g., 0.005 = 0.5%, 0.01 = 1%)

• Fee Scale: Use decimal number for fees (e.g., 0.01 = 1%, 0.005 = 0.5%)

Example Request:

const params = new URLSearchParams({
  chain: '10143',                                                 // Monad Testnet
  tokenIn: '0xf817257fed379853cDe0fa4F97AB987181B1E5Ea',         // USDC
  tokenOut: '0x760AfE86e5de5fa0Ee542fc7B7B713e1c5425701',        // WMON
  amountIn: '1000000',                                            // 1 USDC (6 decimals)
  slippage: '0.005',                                              // 0.5% slippage
  integratorAddress: '0xYourIntegratorAddress',                   // Your address (optional)
  integratorFee: '0.01'                                           // 1% fee (optional)
});

const quoteResponse = await fetch(
  `https://api.madhouse.ag/swap/v1/quote?${params}`
);

const quote = await quoteResponse.json();
console.log(quote);

---

Step 2: Understanding the Response

The API returns transaction data and swap details:

{
  "tokenIn": {
    "address": "0xf817257fed379853cde0fa4f97ab987181b1e5ea",
    "symbol": "USDC",
    "decimals": 6
  },
  "tokenOut": {
    "address": "0x760afe86e5de5fa0ee542fc7b7b713e1c5425701",
    "symbol": "WMON",
    "decimals": 18
  },
  "amountOut": "2361968908884443399",
  "routes": [...],
  "tx": {
    "to": "0x9a5362f481A6c3e309f31b65f9F7Ad0d7e8A7B7D",
    "data": "0xafeb8bfe000000000000000000000000f817257fed379853cde0fa4f97ab987181b1e5ea...",
    "value": "0"
  }
}

Key Fields:

• tx.to - Contract address to send the transaction to

• tx.data - Encoded swap instructions

• tx.value - Native token amount to send (usually "0" for ERC-20 swaps)

• amountOut - Estimated tokens you'll receive (in smallest unit)

• routes - Array of DEX protocols and pools used for the swap

---

Step 3: Set Token Allowance (ERC-20 Only)

For ERC-20 token swaps, approve the Madhouse contract to spend your tokens. Skip this step for native token swaps.

import { ethers } from 'ethers';

const erc20Abi = [
  "function approve(address spender, uint256 amount) returns (bool)"
];

const tokenContract = new ethers.Contract(tokenInAddress, erc20Abi, signer);

const approveTx = await tokenContract.approve(
  quote.tx.to,  // Madhouse contract
  amountIn      // Amount to approve
);

await approveTx.wait();

---

Step 4: Execute the Swap

Once you have the quote and approval (if needed), send the transaction to execute the swap.

Using ethers.js:

import { ethers } from 'ethers';

// Assuming you have a connected wallet/signer
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

try {
  // Estimate gas for the transaction
  const gasEstimate = await provider.estimateGas({
    to: quote.tx.to,
    data: quote.tx.data,
    value: quote.tx.value,
  });

  // Send the swap transaction with 20% gas buffer
  const txResponse = await signer.sendTransaction({
    to: quote.tx.to,
    data: quote.tx.data,
    value: quote.tx.value,
    gasLimit: gasEstimate * 120n / 100n, // Add 20% buffer
  });

  console.log('Transaction sent:', txResponse.hash);
  
  // Wait for confirmation
  const receipt = await txResponse.wait();
  console.log('Swap completed!', receipt);
  
  return receipt;
} catch (error) {
  console.error('Swap failed:', error);
  throw error;
}

Using web3.js:

import Web3 from 'web3';

const web3 = new Web3(window.ethereum);

try {
  const accounts = await web3.eth.getAccounts();
  
  // Estimate gas
  const gasEstimate = await web3.eth.estimateGas({
    from: accounts[0],
    to: quote.tx.to,
    data: quote.tx.data,
    value: quote.tx.value,
  });

  const txResponse = await web3.eth.sendTransaction({
    from: accounts[0],
    to: quote.tx.to,
    data: quote.tx.data,
    value: quote.tx.value,
    gas: Math.floor(gasEstimate * 1.2), // Add 20% buffer
  });

  console.log('Swap completed!', txResponse);
  return txResponse;
} catch (error) {
  console.error('Swap failed:', error);
  throw error;
}

Using viem:

import { createWalletClient, custom } from 'viem';
import { monadTestnet } from 'viem/chains'; // Use appropriate chain

const walletClient = createWalletClient({
  chain: monadTestnet,
  transport: custom(window.ethereum)
});

const [account] = await walletClient.getAddresses();

// Estimate gas
const gasEstimate = await walletClient.estimateGas({
  account,
  to: quote.tx.to,
  data: quote.tx.data,
  value: BigInt(quote.tx.value),
});

const hash = await walletClient.sendTransaction({
  account,
  to: quote.tx.to,
  data: quote.tx.data,
  value: BigInt(quote.tx.value),
  gas: gasEstimate * 120n / 100n, // Add 20% buffer
});

console.log('Transaction hash:', hash);

---

Complete Integration Example

import { ethers } from 'ethers';

async function executeSwap(
  chain,
  tokenIn,
  tokenOut,
  amountIn,
  integratorAddress,  // Optional
  integratorFee = '0.01' // Optional: 1%
) {
  // Step 1: Get quote
  const params = new URLSearchParams({
    chain,
    tokenIn,
    tokenOut,
    amountIn,
    slippage: '0.005', // 0.5%
  });

  // Add integrator parameters if provided
  if (integratorAddress) {
    params.append('integratorAddress', integratorAddress);
    params.append('integratorFee', integratorFee);
  }

  const quoteResponse = await fetch(
    `https://api.madhouse.ag/swap/v1/quote?${params}`
  );
  const quote = await quoteResponse.json();

  // Step 2: Setup provider and signer
  const provider = new ethers.BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();

  // Step 3: Approve token if needed (skip for native tokens)
  const isNativeToken = tokenIn.toLowerCase() === '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
  
  if (!isNativeToken) {
    const tokenContract = new ethers.Contract(
      tokenIn,
      ['function approve(address spender, uint256 amount) returns (bool)'],
      signer
    );
    const approveTx = await tokenContract.approve(quote.tx.to, amountIn);
    await approveTx.wait();
  }

  // Step 4: Execute swap
  const gasEstimate = await provider.estimateGas({
    to: quote.tx.to,
    data: quote.tx.data,
    value: quote.tx.value,
  });

  const txResponse = await signer.sendTransaction({
    to: quote.tx.to,
    data: quote.tx.data,
    value: quote.tx.value,
    gasLimit: gasEstimate * 120n / 100n, // Add 20% buffer
  });

  // Step 5: Wait for confirmation
  const receipt = await txResponse.wait();
  return receipt;
}

// Usage example:
executeSwap(
  '10143',                                              // Monad Testnet
  '0xf817257fed379853cDe0fa4F97AB987181B1E5Ea',        // USDC
  '0x760AfE86e5de5fa0Ee542fc7B7B713e1c5425701',       // WMON
  '1000000',                                            // 1 USDC
  '0xYourIntegratorAddress',                           // Optional
  '0.01'                                                // Optional: 1% fee
);

---

Error Handling

Common API errors and their meanings:

Status Code	Error	Solution
400	Invalid parameters	Check token addresses and amounts
404	No route found	Try different token pair or smaller amount
429	Rate limit exceeded	Wait and retry
500	Server error	Retry after a short delay

async function getQuote(params) {
  const response = await fetch(`https://api.madhouse.ag/swap/v1/quote?${params}`);
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Quote request failed');
  }
  
  return await response.json();
}