Quickstart Guide

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:

A Monei Account

API credentials
Access to sandbox environment
Dashboard for monitoring transactions

Development Environment

You’ll need one of the following:

Node.js (v16 or higher)
Python (v3.8 or higher)
cURL (for command-line testing)

Test Credentials (Optional)

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

Navigate to monei.cc and sign in

Generate API Key

Go to API Keys → Create New Key

Save your API key securely. It won’t be shown again after creation.

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

pip install monei-sdk

# No installation needed use cURL or any HTTP client

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,
});

from monei import MoneiClient
import os

# Initialize with API key
monei = Monei(
    api_key=os.getenv('MONEI_API_KEY'),
)

# Verify connection
print(f'Connected: {status}')

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);

# Get account info
account = monei.user.get_current_user()

print(f'Account ID: {account.id}')
print(f'KYC Tier: {account.kyc_info.current_tier}')
print(f'Daily Limit: {account.kyc_info.limits.daily_transaction_limit}')

curl https://api.monei.cc/api/v1/user/me \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

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);

# Fetch all supported banks
banks = monei.offramp_payouts.get_banks()

print(f'Available banks: {len(banks)}')

# Find a specific bank
gtbank = next(b for b in banks if 'GTBank' in b.name)
print(f'GTBank Code: {gtbank.code}')

curl https://api.monei.cc/api/v1/offramp/payouts/banks \
  -H "x-api-key: YOUR_API_KEY"

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');
}

# Verify the recipient's bank account
verification = monei.offramp_payouts.verify_bank_account(
    account_number='0123456789',
    bank_code='GTBINGLA'
)

print(f'Account Name: {verification.account_name}')

# Confirm before proceeding
if verification.account_name != 'EXPECTED NAME':
    raise ValueError('Account verification failed')

curl -X POST https://api.monei.cc/api/v1/offramp/payouts/verify \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "0123456789",
    "bankCode": "GTBINGLA"
  }'

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

# Get current exchange rate
quote = monei.offramp_exchange.get_quote(
    token='USDC',
    amount=100,
    network='polygon',
    fiat_currency='NGN'
)

print(f'Exchange Rate: {quote.rate}')
print(f'You will receive: {quote.fiat_amount} NGN')
print(f'Fee: {quote.fee}')

curl -X POST https://api.monei.cc/api/v1/offramp/exchange/quote \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "amount": 100,
    "network": "polygon",
    "fiatCurrency": "NGN"
  }'

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);

# Execute the offramp swap
swap = monei.offrampExchange.initiateSwap(
    token='USDC',
    amount=100,
    network='polygon',
    fiat_currency='NGN',
    bank_code='GTBINGLA',
    account_number='0123456789',
    account_name=verification.account_name
)

print(f'Transaction ID: {swap.transaction_id}')
print(f'Status: {swap.status}')

# Monitor transaction status
status = monei.offramp.get_status(swap.transaction_id)
print(f'Current Status: {status.state}')

curl -X POST https://api.monei.cc/api/v1/offramp/exchange/swap \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "USDC",
    "amount": 100,
    "network": "polygon",
    "fiatCurrency": "NGN",
    "bankCode": "GTBINGLA",
    "accountNumber": "0123456789",
    "accountName": "John Doe"
  }'

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();

from monei import MoneiClient
import os
import time

def complete_offramp():
    # 1. Initialize client
    monei = MoneiClient(
        api_key=os.getenv('MONEI_API_KEY'),
        environment='sandbox'
    )
    
    try:
        # 2. Get available banks
        banks = monei.offramp_payouts.get_banks()
        gtbank = next(b for b in banks if 'GTBank' in b.name)
        
        # 3. Verify bank account
        verification = monei.offramp_payouts.verify_account(
            account_number='0123456789',
            bank_code=gtbank.code
        )
        
        print(f'Verified account: {verification.account_name}')
        
        # 4. Get exchange quote
        quote = monei.offramp_exchange.get_quote(
            token='USDC',
            amount=100,
            network='polygon',
            fiat_currency='NGN'
        )
        
        print(f'Rate: ₦{quote.rate} per USDC')
        print(f"You'll receive: ₦{quote.fiat_amount}")
        
        # 5. Execute swap
        swap = monei.offramp_exchange.initiate_swap(
            token='USDC',
            amount=100,
            network='polygon',
            fiat_currency='NGN',
            bank_code=gtbank.code,
            account_number='0123456789',
            account_name=verification.account_name
        )
        
        print(f'Transaction successful! ID: {swap.transaction_id}')
        
        # 6. Monitor status
        while True:
            status = monei.offrampp_ledger.track_order(swap.transaction_id)
            print(f'Status: {status.state}')
            
            if status.state == 'completed':
                print('Naira successfully sent to bank account!')
                break
            elif status.state == 'failed':
                print(f'Transaction failed: {status.error}')
                break
            
            time.sleep(5)
            
    except Exception as error:
        print(f'Error: {str(error)}')

if __name__ == '__main__':
    complete_offramp()

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);
  }
}

try:
    result = monei.offramp.swap(...)
except InsufficientBalanceError:
    print('Not enough crypto in wallet')
except InvalidAccountError:
    print('Bank account verification failed')
except RateLimitError:
    print('Too many requests, please wait')
except Exception as error:
    print(f'Unexpected error: {str(error)}')

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

Authentication Failed

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

Network Not Supported

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

Rate Limit Exceeded

Problem: 429 Too Many RequestsSolutions:

Implement exponential backoff
Check your plan’s rate limits
Consider upgrading your plan
Cache responses when possible

Transaction Pending Too Long

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

Introduction

Core Concepts

Account Management

Naira Wallet

EVM Blockchain

Solana

Offramp (Crypto to Fiat)

Bill Payments

Transactions

Security

Testing

Overview

Prerequisites

Step 1: Get Your API Key

Step 2: Install SDK

Step 3: Initialize Client

Step 4: Your First API Call

Step 5: Complete Transaction Flow

5.1 Get Available Banks

5.2 Verify Bank Account

5.3 Get Exchange Quote

5.4 Execute Swap

Complete Example

Error Handling

Next Steps

Authentication

Core Concepts

API Reference

Webhooks

Common Issues

Support

Documentation

Discord Community

Email Support

​Overview

​Prerequisites

​Step 1: Get Your API Key

​Step 2: Install SDK

​Step 3: Initialize Client

​Step 4: Your First API Call

​Step 5: Complete Transaction Flow

​5.1 Get Available Banks

​5.2 Verify Bank Account

​5.3 Get Exchange Quote

​5.4 Execute Swap

​Complete Example

​Error Handling

​Next Steps

Authentication

Core Concepts

API Reference

Webhooks

​Common Issues

​Support

Documentation

Discord Community

Email Support

Overview

Prerequisites

Step 1: Get Your API Key

Step 2: Install SDK

Step 3: Initialize Client

Step 4: Your First API Call

Step 5: Complete Transaction Flow

5.1 Get Available Banks

5.2 Verify Bank Account

5.3 Get Exchange Quote

5.4 Execute Swap

Complete Example

Error Handling

Next Steps

Common Issues

Support