> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monei.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get started with Monei infrastructure in under 5 minutes

## 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:

<AccordionGroup>
  <Accordion icon="user" title="A Monei Account">
    Sign up for a free account at [monei.cc](https://monei.cc)

    You'll receive:

    * API credentials
    * Access to sandbox environment
    * Dashboard for monitoring transactions
  </Accordion>

  <Accordion icon="code" title="Development Environment">
    You'll need one of the following:

    * **Node.js** (v16 or higher)
    * **Python** (v3.8 or higher)
    * **cURL** (for command-line testing)
  </Accordion>

  <Accordion icon="wallet" title="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](https://monei.cc/api-keys).
  </Accordion>
</AccordionGroup>

***

## Step 1: Get Your API Key

<Steps>
  <Step title="Login to Dashboard">
    Navigate to [monei.cc](https://monei.cc/login) and sign in
  </Step>

  <Step title="Generate API Key">
    Go to **API Keys** → **Create New Key**

    <Warning>
      Save your API key securely. It won't be shown again after creation.
    </Warning>
  </Step>

  <Step title="Choose Environment">
    Select either:

    * **Sandbox** - For testing with fake money
    * **Production** - For real transactions

    <Info>
      Start with sandbox to avoid any real funds during development.
    </Info>
  </Step>
</Steps>

***

## Step 2: Install SDK

Choose your preferred language and install the Monei SDK:

<CodeGroup>
  ```bash Node.js theme={null}
  npm install monei-sdk
  ```

  ```bash Python theme={null}
  pip install monei-sdk
  ```

  ```bash No SDK (REST API) theme={null}
  # No installation needed use cURL or any HTTP client
  ```
</CodeGroup>

***

## Step 3: Initialize Client

Set up your Monei client with your API credentials:

<CodeGroup>
  ```javascript Node.js theme={null}
  import MoneiSDK from 'monei-sdk';

  // Initialize with API key
  const monei = new MoneiSDK({
    apiKey: process.env.MONEI_API_KEY,
  });


  ```

  ```python Python theme={null}
  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}')
  ```
</CodeGroup>

<Note>
  Always use environment variables for API keys. Never hardcode them in your source code.
</Note>

***

## Step 4: Your First API Call

Let's fetch your account information to verify everything is working:

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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);
  ```

  ```python Python theme={null}
  # 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}')
  ```

  ```bash cURL theme={null}
  curl https://api.monei.cc/api/v1/user/me \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Authorization: Bearer YOUR_AUTH_TOKEN"
  ```
</CodeGroup>

**Expected Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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);
  ```

  ```python Python theme={null}
  # 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}')
  ```

  ```bash cURL theme={null}
  curl https://api.monei.cc/api/v1/offramp/payouts/banks \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

### 5.2 Verify Bank Account

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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');
  }
  ```

  ```python Python theme={null}
  # 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')
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

### 5.3 Get Exchange Quote

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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
  ```

  ```python Python theme={null}
  # 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}')
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

### 5.4 Execute Swap

<CodeGroup>
  ```javascript Node.js theme={null}
  // 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);
  ```

  ```python Python theme={null}
  # 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}')
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

***

## Complete Example

Here's the complete flow in one script:

<CodeGroup>
  ```javascript complete.js theme={null}
  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();
  ```

  ```python complete.py theme={null}
  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()
  ```
</CodeGroup>

***

## Error Handling

Always implement proper error handling in production:

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
    }
  }
  ```

  ```python Python theme={null}
  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)}')
  ```
</CodeGroup>

***

## Next Steps

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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/introduction/authentication">
    Learn about different auth methods and security best practices
  </Card>

  <Card title="Core Concepts" icon="book" href="/core-concepts/wallets">
    Understand wallets, transactions, and network management
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/account">
    Explore all available endpoints and parameters
  </Card>

  <Card title="Webhooks" icon="webhook" href="/security/webhooks">
    Set up real-time notifications for transaction events
  </Card>
</CardGroup>

***

## Common Issues

<AccordionGroup>
  <Accordion icon="circle-xmark" title="Authentication Failed">
    **Problem:** API returns 401 Unauthorized

    **Solutions:**

    * 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
  </Accordion>

  <Accordion icon="circle-xmark" title="Network Not Supported">
    **Problem:** Error about unsupported network

    **Solutions:**

    * Check [supported networks](/core-concepts/networks)
    * Verify network name is lowercase and hyphenated (e.g., `bnb-smart-chain`)
    * Ensure token is available on specified network
  </Accordion>

  <Accordion icon="circle-xmark" title="Rate Limit Exceeded">
    **Problem:** 429 Too Many Requests

    **Solutions:**

    * Implement exponential backoff
    * Check your plan's rate limits
    * Consider upgrading your plan
    * Cache responses when possible
  </Accordion>

  <Accordion icon="circle-xmark" title="Transaction Pending Too Long">
    **Problem:** Transaction stuck in pending state

    **Solutions:**

    * Network congestion may cause delays
    * Check transaction on blockchain explorer
    * Contact support if pending for over 1 hour
    * Monitor via webhook for automatic updates
  </Accordion>
</AccordionGroup>

***

## Support

Need help? We're here for you:

<CardGroup cols={3}>
  <Card title="Documentation" icon="book" href="/support/faq">
    Browse our comprehensive guides
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/monei">
    Ask questions and share knowledge
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@monei.cc">
    Get help from our team
  </Card>
</CardGroup>