1. API Overview
The RECEN API provides programmatic access to the REC Marketplace smart contracts deployed on the Ethereum Sepolia Testnet. 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 (Sepolia)
RECNFT (ERC-721): 0x491258605C385015e1E57631a1b3Ef074eE5CdfA — Issues and manages REC NFTs.
RECMarketplace: 0x83C9804A5d8818Aa40C57cC3331e24A38dF376AB — Handles listing, buying, and fee collection.
MockUSDT (ERC-20): 0x99D37484dd220C176eAb2b2F0f29e175C9550682 — Test USDT token (6 decimals).
MockRECEN (ERC-20): 0x9D1dA7F307D1afC14797F84fDd3B0A3a16C6fC46 — Test RECEN token (18 decimals).
3. RECNFT Contract API
mintREC(name, energyType, recAmount, co2Saved, imageURI) — Mint a new REC certificate. Anyone can call this function.
recData(tokenId) — Returns on-chain metadata: name, energyType, recAmount, co2Saved, imageURI, issuer, issuedAt.
tokensOfOwner(address) — Returns all token IDs owned by a specific address.
totalSupply() — Returns the total number of REC NFTs issued.
tokenURI(tokenId) — Returns on-chain JSON metadata compatible with NFT marketplaces.
safeTransferFrom(from, to, tokenId) — Transfer a REC to another address.
4. Marketplace Contract API
listREC(tokenId, recAmount) — List a REC for sale. Requires prior approval of the marketplace contract.
delistREC(tokenId) — Remove a listing. Only the seller can delist.
buyWithUSDT(tokenId) — Purchase a listed REC with USDT. Requires prior USDT approval.
buyWithRECEN(tokenId) — Purchase a listed REC with RECEN. Requires prior RECEN approval.
getActiveListings() — Returns all active listings (tokenIds and listing data).
calcCostUSDT(tokenId) / calcCostRECEN(tokenId) — Calculate subtotal, fee, and total cost for a listing.
priceUSDT() / priceRECEN() — Current price per REC unit.
feeUSDT() / feeRECEN() — Current fee in basis points (300 = 3%, 150 = 1.5%).
5. Test Token API
mint(to, amount) — Mint test tokens to any address. Available on both MockUSDT and MockRECEN contracts.
approve(spender, amount) — Approve the marketplace contract to spend tokens on your behalf. Required before buying.
balanceOf(address) — Check token balance.
Note: MockUSDT uses 6 decimals (1 USDT = 1000000). MockRECEN uses 18 decimals (1 RECEN = 1e18).
6. Quick Start Example
Using ethers.js: (1) Connect to Sepolia RPC; (2) Create contract instance with ABI and address; (3) Call mintREC() to issue a certificate; (4) Call tokensOfOwner() to list your RECs; (5) Approve marketplace + call listREC() 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.
7. Rate Limits & Best Practices
Public RPC endpoints may have rate limits. For production use, consider Infura or Alchemy with dedicated API keys.
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.