🌱

Celo Integration Guide

EVM-Compatible β€’ Mobile-First β€’ Carbon Negative Blockchain

Celo Mainnet Alfajores Testnet Native: CELO Explorer: Celoscan

This guide shows you how to integrate Celo networks (Celo Mainnet and Alfajores testnet) into your Bicrypto Ecosystem. You'll add Celo credentials in .env, acquire API/RPC endpoints, then set up wallets and tokens in the admin panelβ€”similar to how it's done for other EVM-compatible chains like Ethereum, BSC, or Polygon.

1

Configure Environment Variables

Add to .env file
# Celo Networks (mainnet, alfajores)
CELO_EXPLORER_API_KEY="YOUR_CELO_EXPLORER_API_KEY"  # e.g., ZZSQAPGRGS5Q2UENI...
CELO_NETWORK="alfajores"
CELO_MAINNET_RPC="https://YOUR_MAINNET_RPC_PLACEHOLDER"
CELO_MAINNET_RPC_WSS=""
CELO_ALFAJORES_RPC="https://YOUR_ALFAJORES_RPC_PLACEHOLDER"
CELO_ALFAJORES_RPC_WSS=""

πŸ”‘ Environment Variables

  • CELO_EXPLORER_API_KEY: Your block explorer API key from Celoscan
  • CELO_NETWORK: Active chain (mainnet or alfajores)
  • CELO_MAINNET_RPC: Mainnet HTTP endpoint
  • CELO_ALFAJORES_RPC: Alfajores testnet HTTP endpoint
2

Acquire API Keys and RPC Endpoints

πŸ” Celo Explorer API Key

If you're using a specific Celo explorer, create an account and generate an API key:

  • Visit Celoscan.io
  • Create an account and navigate to API section
  • Generate a new API key
  • Insert it into CELO_EXPLORER_API_KEY
Celo explorer showing how to create an API key

🌐 RPC/WSS Provider

By default, Celo provides:

  • Mainnet: forno.celo.org
  • Alfajores: alfajores-forno.celo-testnet.org

If you use another provider (e.g., GetBlock), replace the placeholder URLs with your provider's endpoints.

⚠️ Network Selection: Set CELO_NETWORK to alfajores for testing or mainnet for production use.
3

Apply Environment Updates

4

Configure Master Wallet

Generate a New Master Wallet for the enabled Celo network (mainnet or Alfajores). This wallet handles native fees (CELO) and any tokens that allow "permit" features on Celo.

5

Enable Tokens and Configure Fees

Enable tokens you plan to use for markets on Celo (e.g., cUSD, cEUR, etc.) and configure their fees and limits appropriately.

6

Custodial Wallets (For Non-Permit Tokens)

Some tokens don't support the PERMIT feature (where fees can be deducted from the user's own wallet). In this case, the platform uses a Custodial Wallet:

1

Deposit Balance to Master Wallet

Ensure the master wallet has sufficient CELO to cover gas fees and deployments.

2

Deploy Custodial Wallet

Go to Admin β†’ Extensions β†’ Ecosystem β†’ Custodial Wallets to deploy a new custodial wallet specifically for Celo.

3

Process Transactions

Users' token deposits/withdrawals are processed via this custodial wallet, with CELO as the native fee currency.

πŸͺ™ Token Types Overview

Native

The main coin on the Celo network is CELO. Required to pay network fees on standard transactions.

Permit

A token with advanced smart contract features allowing the user's own wallet to let the platform pay fees from that same wallet. The user doesn't need CELO for each transaction.

No Permit

Tokens lacking these features require a custodial wallet. The master wallet pays gas fees for withdrawals.

βœ…

Final Notes & Best Practices

β›½ Gas Price Monitoring

Celo gas fees are typically low, but can still vary. Adjust your minimum fees accordingly to ensure profitable operations.

πŸ§ͺ Testnet Usage

For testing, set CELO_NETWORK to alfajores and provide testnet RPC endpoints. You can get test CELO from an Alfajores faucet.

πŸ”— Future Chains

If adding other chains, follow a similar pattern with environment variables and network settings.

By configuring Celo environment variables, generating a master wallet, and handling tokens via PERMIT or custodial wallets, you can effectively manage deposits and withdrawals on the Celo network within your Bicrypto Ecosystem.