1. API Overview
The RECEN API provides programmatic access to the REC Marketplace smart contracts deployed on BSC Mainnet (Chain ID 56). Developers can interact with the contracts directly using any Web3 library (ethers.js, viem, web3.js).
All contract ABIs are available in the project's artifacts directory after compilation with Hardhat.
2. Contract Addresses (BSC Mainnet)
RECNFT1155 (ERC-1155): 0x836DC77B1772b0ba2607975F935E0C51639a50eb — Issues and manages REC NFTs.
RECMarketplace1155: 0xc9afB07c0893db0144Ba0ccAd39e177E2e4CCdD5 — Handles listing, buying, and fee collection.
USDT (BEP-20): 0x55d398326f99059fF775485246999027B3197955 — Tether USD on BSC (18 decimals, not 6).
RECEN (BEP-20): 0x3CB7C92853A46c7FA603ea67Ee8dD1aCa556CB94 — RECEN token (18 decimals, 1B total supply).
3. RECNFT1155 Contract API
mintREC(name, energyType, amount, co2PerUnit, imageURI) — Mint a new REC batch as a fresh ERC-1155 token id. Anyone can call this function; caller becomes both creator and initial owner.
recData(tokenId) — Returns on-chain metadata: name, energyType, co2PerUnit, imageURI, issuer, issuedAt.
tokensOfOwner(address) — Returns (ids[], balances[]) owned by a specific address.
totalSupply() — Returns the next unused token id (i.e., total distinct token types ever minted).
uri(tokenId) — Returns an on-chain data URI (JSON metadata) compatible with NFT marketplaces.
mergeRECs(tokenIds[]) — Burn multiple same-energy-type batches the caller owns and mint a single consolidated token; CO₂/unit becomes a balance-weighted average.
safeTransferFrom(from, to, id, amount, data) — Transfer part or all of an ERC-1155 balance.
4. Marketplace Contract API
listREC(tokenId, quantity, pricePerUnit) — List a REC batch for sale at a seller-chosen USDT price (18 decimals). Requires setApprovalForAll on the NFT.
delistREC(listingId) — Remove a listing. Only the seller can delist.
buyWithUSDT(listingId, quantity) — Purchase part or all of a listing with USDT. Requires prior USDT approval.
buyWithRECEN(listingId, quantity) — Purchase with RECEN. Price converts via usdtToRecen() at the active ratio. Requires prior RECEN approval.
getActiveListings() — Returns (ids[], listings[]) of all currently active listings.
usdtToRecen(usdtAmount) — View that converts a USDT amount to RECEN at the live rate.
buyerFeeUSDT() / sellerFeeUSDT() / buyerFeeRECEN() / sellerFeeRECEN() — Current fees in parts-per-million (30,000 = 3%; 15,000 = 1.5%).
getFeeSummary() — Aggregate fee totals plus admin wallet balances.
5. Payment Token API (USDT / RECEN)
USDT and RECEN are standard BEP-20 tokens on BSC Mainnet. They are external contracts, not deployed by RECEN.
approve(spender, amount) — Approve the marketplace contract to spend tokens on your behalf. Required before buyWithUSDT / buyWithRECEN.
balanceOf(address) — Check token balance.
Note: BSC USDT uses 18 decimals (1 USDT = 1e18 wei). This is different from Ethereum USDT which uses 6. RECEN is also 18 decimals.
6. Quick Start Example
Using ethers.js: (1) Connect to a BSC Mainnet RPC (e.g. https://bsc-rpc.publicnode.com); (2) Create a contract instance with the ABI and address; (3) Call mintREC() to issue a certificate; (4) Call tokensOfOwner() to list your RECs; (5) setApprovalForAll on the NFT contract, then call listREC() on the marketplace to sell.
Using wagmi/viem (recommended for Next.js): Import the ABI from src/lib/contract.ts, use useReadContract/useWriteContract hooks for seamless React integration. Chain: bsc from wagmi/chains.
7. Rate Limits & Best Practices
Public RPC endpoints may have rate limits. For production use, consider a dedicated BSC node provider (Ankr, QuickNode, NodeReal) with your own API key.
Public BSC RPCs typically cap eth_getLogs at 50,000 blocks per call. Chunk historical queries or use a server-side indexer.
Best practices: batch read calls with useReadContracts/multicall, cache frequently-read data (totalSupply, recData), listen to contract events (RECMinted, Listed, Sold) for real-time updates.