Skip to main content

​
Overview

This guide will walk you through making your first API call to Monei infrastructure. By the end, you’ll have executed a complete crypto-to-fiat transaction. What you’ll learn:
  • Setting up authentication
  • Making your first API call
  • Executing an offramp transaction
  • Handling responses and errors
Time to complete: 5 minutes

​
Prerequisites

Before you begin, make sure you have:
Sign up for a free account at monei.ccYou’ll receive:
  • API credentials
  • Access to sandbox environment
  • Dashboard for monitoring transactions
You’ll need one of the following:
  • Node.js (v16 or higher)
  • Python (v3.8 or higher)
  • cURL (for command-line testing)
For testing, you can use sandbox mode which doesn’t require real crypto or bank accounts.Get sandbox credentials from your dashboard.

​
Step 1: Get Your API Key

1

Login to Dashboard

Navigate to monei.cc and sign in
2

Generate API Key

Go to API Keys → Create New Key
Save your API key securely. It won’t be shown again after creation.
3

Choose Environment

Select either:
  • Sandbox - For testing with fake money
  • Production - For real transactions
Start with sandbox to avoid any real funds during development.

​
Step 2: Install SDK

Choose your preferred language and install the Monei SDK: 
npm install monei-sdk

​
Step 3: Initialize Client

Set up your Monei client with your API credentials: 
import MoneiSDK from 'monei-sdk';

// Initialize with API key
const monei = new MoneiSDK({
  apiKey: process.env.MONEI_API_KEY,
});
Always use environment variables for API keys. Never hardcode them in your source code.

​
Step 4: Your First API Call

Let’s fetch your account information to verify everything is working: 
// Get account info
const account = await monei.user.getCurrentUser();

console.log('Account ID:', account.id);
console.log('KYC Tier:', account.kycInfo.currentTier);
console.log('Daily Limit:', account.kycInfo.limits.dailyTransactionLimit);
Expected Response: 
{
  "statusCode": 200,
  "message": "User retrieved successfully",
  "data": {
    "id": "uuid-here",
    "email": "you@example.com",
    "kycInfo": {
      "currentTier": "tier_1",
      "limits": {
        "dailyTransactionLimit": 200000,
        "cryptoAllowed": true
      }
    }
  }
}

​
Step 5: Complete Transaction Flow

Now let’s execute a complete offramp transaction. selling crypto for Naira:

​
5.1 Get Available Banks

// Fetch all supported banks for offramp
const banks = await monei.offrampPayouts.getBanks();

console.log('Available banks:', banks.length);

// Find a specific bank
const gtbank = banks.find(b => b.name.includes('GTBank'));
console.log('GTBank Code:', gtbank.code);

​
5.2 Verify Bank Account

// Verify the recipient's bank account
const verification = await monei.offrampPayouts.verifyBankAccount({
  accountNumber: '0123456789',
  bankCode: 'GTBINGLA'
});

console.log('Account Name:', verification.accountName);

// Confirm with user before proceeding
if (verification.accountName !== 'EXPECTED NAME') {
  throw new Error('Account verification failed');
}

​
5.3 Get Exchange Quote

// Get current exchange rate
const quote = await monei.offrampExchange.getQuote({
  token: 'USDC',
  amount: 100,
  network: 'polygon',
  fiatCurrency: 'NGN'
});

console.log('Exchange Rate:', quote.rate);
console.log('You will receive:', quote.fiatAmount, 'NGN');
console.log('Fee:', quote.fee);

// Quote is valid for 30 seconds

​
5.4 Execute Swap

// Execute the offramp swap
const swap = await monei.offrampExchange.swap({
  token: 'USDC',
  amount: 100,
  network: 'polygon',
  fiatCurrency: 'NGN',
  bankCode: 'GTBINGLA',
  accountNumber: '0123456789',
  accountName: verification.accountName
});

console.log('Transaction ID:', swap.transactionId);
console.log('Status:', swap.status);

// Monitor transaction status
const status = await monei.offramp.trackOrder(swap.transactionId);
console.log('Current Status:', status.state);

​
Complete Example

Here’s the complete flow in one script: 
import MoneiSDK from 'monei-sdk';

async function completeOfframp() {
  // 1. Initialize client
  const monei = new MoneiSDK({
    apiKey: process.env.MONEI_API_KEY,
  });

  try {
    // 2. Get available banks
    const banks = await monei.offrampPayouts.getBanks();
    const gtbank = banks.find(b => b.name.includes('GTBank'));
    
    // 3. Verify bank account
    const verification = await monei.offrampPayouts.verifyAccount({
      accountNumber: '0123456789',
      bankCode: gtbank.code
    });
    
    console.log(`Verified account: ${verification.accountName}`);
    
    // 4. Get exchange quote
    const quote = await monei.offrampExchange.getQuote({
      token: 'USDC',
      amount: 100,
      network: 'polygon',
      fiatCurrency: 'NGN'
    });
    
    console.log(`Rate: ₦${quote.rate} per USDC`);
    console.log(`You'll receive: ₦${quote.fiatAmount}`);
    
    // 5. Execute swap
    const swap = await monei.offrampExchange.swap({
      token: 'USDC',
      amount: 100,
      network: 'polygon',
      fiatCurrency: 'NGN',
      bankCode: gtbank.code,
      accountNumber: '0123456789',
      accountName: verification.accountName
    });
    
    console.log(`Transaction successful! ID: ${swap.transactionId}`);
    
    // 6. Monitor status
    const checkStatus = async () => {
      const status = await monei.offrampLedger.trackOrder(swap.transactionId);
      console.log(`Status: ${status.state}`);
      
      if (status.state === 'completed') {
        console.log('Naira successfully sent to bank account!');
      } else if (status.state === 'failed') {
        console.error('Transaction failed:', status.error);
      } else {
        // Check again in 5 seconds
        setTimeout(checkStatus, 5000);
      }
    };
    
    checkStatus();
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

completeOfframp();

​
Error Handling

Always implement proper error handling in production: 
try {
  const result = await monei.offramp.swap({...});
} catch (error) {
  if (error.code === 'INSUFFICIENT_BALANCE') {
    console.error('Not enough crypto in wallet');
  } else if (error.code === 'INVALID_ACCOUNT') {
    console.error('Bank account verification failed');
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    console.error('Too many requests, please wait');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

​
Next Steps

Congratulations! You’ve successfully completed your first Monei transaction. Here’s what to explore next:

Authentication

Learn about different auth methods and security best practices

Core Concepts

Understand wallets, transactions, and network management

API Reference

Explore all available endpoints and parameters

Webhooks

Set up real-time notifications for transaction events

​
Common Issues

Problem: API returns 401 UnauthorizedSolutions:
  • Verify your API key is correct
  • Check you’re using the right environment (sandbox vs production)
  • Ensure API key hasn’t expired
  • Confirm API key has necessary permissions
Problem: Error about unsupported networkSolutions:
  • Check supported networks
  • Verify network name is lowercase and hyphenated (e.g., bnb-smart-chain)
  • Ensure token is available on specified network
Problem: 429 Too Many RequestsSolutions:
  • Implement exponential backoff
  • Check your plan’s rate limits
  • Consider upgrading your plan
  • Cache responses when possible
Problem: Transaction stuck in pending stateSolutions:
  • Network congestion may cause delays
  • Check transaction on blockchain explorer
  • Contact support if pending for over 1 hour
  • Monitor via webhook for automatic updates

​
Support

Need help? We’re here for you:

Documentation

Browse our comprehensive guides

Discord Community

Ask questions and share knowledge

Email Support

Get help from our team