Forem: Carter

I Built a Free Public REST API for Kenya Data Counties, Banks, M-Pesa Paybills and More

Carter — Sun, 03 May 2026 15:25:34 +0000

Every developer building a Kenyan app runs into the same problem. You need a list of all 47 counties. Or all Kenyan banks with their codes. Or M-Pesa paybill numbers for KPLC, NHIF, KRA. And every time you end up manually copying data from Wikipedia or a PDF.

I fixed that. I built a free public REST API that serves all of this data in one place.

No authentication. No sign up. Just call the endpoint and get your data.

Live API: https://kenya-api-90wq.onrender.com
GitHub: https://github.com/Carter254g/kenya-api

What the API Serves

Four datasets available right now:

All 47 Kenya counties with region and capital city
All Kenyan banks with codes and SWIFT numbers
M-Pesa paybill numbers by category
Kenya public holidays

How to Use It

Get all 47 counties

const res = await fetch('https://kenya-api-90wq.onrender.com/api/counties');
const data = await res.json();
console.log(data);

Response:

{
  "count": 47,
  "data": [
    { "code": 1, "name": "Mombasa", "capital": "Mombasa", "region": "Coast" },
    { "code": 47, "name": "Nairobi", "capital": "Nairobi", "region": "Nairobi" }
  ]
}

Filter counties by region

GET /api/counties?region=Coast
GET /api/counties?region=Rift Valley
GET /api/counties?region=Nyanza

Search for a bank

const res = await fetch('https://kenya-api-90wq.onrender.com/api/banks?search=equity');
const data = await res.json();

Response:

{
  "count": 1,
  "data": [
    {
      "code": "49",
      "name": "Equity Bank Kenya",
      "shortname": "Equity",
      "swift": "EQBLKENX"
    }
  ]
}

Get M-Pesa paybills by category

GET /api/mpesa/paybills?category=Government
GET /api/mpesa/paybills?category=Banking
GET /api/mpesa/paybills?category=Utilities
Government paybills include KRA iTax, NHIF, NSSF, and eCitizen.

Get all public holidays

Government paybills include KRA iTax, NHIF, NSSF, and eCitizen.

Get all public holidays

How I Built It

The API is built with Node.js and Express. The data lives in JSON files inside the project. Each route reads from its JSON file and supports query parameters for filtering.

router.get('/', (req, res) => {
  const { region } = req.query;
  if (region) {
    const filtered = counties.filter(c =>
      c.region.toLowerCase() === region.toLowerCase()
    );
    return res.json({ count: filtered.length, data: filtered });
  }
  res.json({ count: counties.length, data: counties });
});

Simple, fast, and easy to extend.

I added helmet for security headers, morgan for request logging, and cors so any frontend can call it without issues.

What Is Coming Next

Constituencies and wards data
Universities and colleges
Hospitals and health facilities
Currency exchange rates
Rate limiting and optional API keys for high volume users

Use It in Your Project

The API is live and free. No sign up required.

Base URL: https://kenya-api-90wq.onrender.com

If you use it in a project, star the repo and drop a comment below with what you built. I would love to see it.

GitHub: https://github.com/Carter254g/kenya-api

I Built an ERC-20 Token and React dApp from Scratch Complete Web3 Breakdown

Carter — Sun, 03 May 2026 06:22:16 +0000

Most Web3 tutorials give you a token contract and stop there. I went furtherand built the full stack: a Solidity ERC-20 token, a Hardhat test suite, and a React dApp with MetaMask integration and transaction history.

Here is every technical decision I made.

GitHub: https://github.com/Carter254g/harambee-dapp

What I Built

HarambeeCoin (HBC) is a custom ERC-20 token. The dApp lets you connect MetaMask, check your balance, send tokens, and see your full transaction history — sent and received.

The Smart Contract

I wrote HarambeeCoin from scratch without OpenZeppelin to understand every line. The core is four functions:

function transfer(address to, uint256 amount) public returns (bool) {
    require(balanceOf[msg.sender] >= amount, "Insufficient balance");
    balanceOf[msg.sender] -= amount;
    balanceOf[to] += amount;
    emit Transfer(msg.sender, to, amount);
    return true;
}

I also added mint (owner only) and burn (any holder) on top of the standard ERC-20 interface.

Testing with Hardhat

Six tests cover the critical paths:

it("Should transfer tokens between accounts", async function () {
    await harambeeCoin.transfer(addr1.address, 1000);
    expect(await harambeeCoin.balanceOf(addr1.address)).to.equal(1000);
});

All six pass. Testing first meant I caught a balance check bug before it ever touched a real network.

Connecting React to the Blockchain

Ethers.js v6 handles the connection. One function sets up the entire Web3 layer:

const provider = new ethers.BrowserProvider(window.ethereum)
const signer = await provider.getSigner()
const contractInstance = new ethers.Contract(CONTRACT_ADDRESS, ABI, signer)

The contract instance then works exactly like a regular JavaScript object you call methods and await them.

Transaction History from Events

Every ERC-20 transfer emits a Transfer event. Ethers.js lets you query all past events as filters:

const sentFilter = contract.filters.Transfer(account, null)
const receivedFilter = contract.filters.Transfer(null, account)
const sentEvents = await contract.queryFilter(sentFilter, 0, 'latest')

This gives full history without a backend or database. The blockchain is the database.

What Broke

MetaMask caches network state aggressively. When the Hardhat node restarts, the blockchain resets but MetaMask still thinks it is on the old chain. The fix is to delete and re-add the Localhost network in MetaMask settings after every node restart.

Chain ID matters. Hardhat defaults to 31337, not 1337. Always check the actual chain ID from the node output before configuring MetaMask.

ENS resolution fails on local networks. If you paste an address and get an ENS error, make sure the address starts with 0x and is a full 42 character hex string.

What Is Next

Deploy to Sepolia testnet
Token faucet so anyone can get HBC
NFT minting extension
DAO voting with HBC tokens

Try It

GitHub: https://github.com/Carter254g/harambee-dapp

I Built a Telegram Bot That Searches, Monitors Prices and Lets You Buy and Sell. Here's How

Carter — Sat, 02 May 2026 14:24:02 +0000

Most people check Jiji or Amazon manually every day waiting for a price to drop. I built a Telegram bot that does it for you automatically and also lets you list and sell items directly from Telegram.

No website. No app. Just Telegram.

GitHub: https://github.com/Carter254g/price-alert-bot

What It Does

The bot has two sides.

For buyers: search for any product, set a target price, and get a Telegram alert the moment the price drops. It pulls real listings from Jiji Kenya and Google Shopping.

For sellers: list a product with a photo and description. Buyers can find it and contact you directly on Telegram.

The Architecture

The project is split into focused modules:

scraper.py — extracts prices from any product URL using BeautifulSoup
jiji.py — scrapes Jiji Kenya listings directly from their Nuxt data layer
search.py — queries Google Shopping via SerpAPI for any product in any country
telegram.py — sends price alert messages
bot_handler.py — handles all Telegram commands and conversation flows
scheduler.py — runs automatic price checks every 6 hours
listings.py — stores and retrieves local marketplace listings

The Jiji Scraper

Jiji loads listings with JavaScript so a regular request returns empty content. The trick is that Jiji uses Nuxt.js which embeds all the page data in a JSON script tag:

match = re.search(r'id="__NUXT_DATA__"[^>]*>(.*?)</script>', res.text, re.DOTALL)
data = json.loads(match.group(1))

From there it is a matter of walking the data structure to extract titles, prices, locations and URLs. The result is real Jiji listings without needing a headless browser.

The Conversation Flow

python-telegram-bot has a ConversationHandler that manages multi-step flows. The browse flow looks like this:

browse_handler = ConversationHandler(
    entry_points=[CommandHandler("browse", browse_start)],
    states={
        BROWSE_QUERY: [MessageHandler(filters.TEXT, browse_get_query)],
        BROWSE_MIN_PRICE: [MessageHandler(filters.TEXT, browse_min_price)],
        BROWSE_MAX_PRICE: [MessageHandler(filters.TEXT, browse_max_price)],
    },
    fallbacks=[CommandHandler("cancel", cancel)],
)

Each state waits for user input before moving to the next step. The user never has to type a command with arguments — the bot guides them through naturally.

Photo Support for Sellers

When a seller lists a product, they can send a photo. Telegram stores photos on their servers and gives back a file_id. That ID gets saved in the JSON config and later used to send the photo back to buyers:

if l.get("photo_id"):
    await update.message.reply_photo(photo=l["photo_id"], caption=caption)

No image hosting needed. Telegram handles it all.

Automatic Price Monitoring

The scheduler runs every 6 hours using APScheduler. It checks all monitored URLs, compares current prices to targets, and fires Telegram alerts when a price drops:

scheduler.add_job(check_all, "interval", hours=interval_hours)

Start it once and forget about it.

What I Learned

Nuxt.js apps embed their data in script tags. Once you know where to look, scraping them is straightforward without needing Selenium or Playwright.

Telegram's ConversationHandler is powerful but stateful. You have to manage session data carefully when multiple users are in different states at the same time.

Always send long results as individual messages. Telegram has a 4096 character limit per message and one long block will crash the handler silently.

What Is Next

WhatsApp integration
More marketplace sources beyond Jiji
Price history charts
Web dashboard to manage listings

Try It

GitHub: https://github.com/Carter254g/price-alert-bot

I Built a Full-Stack Invoice App from Scratch. Here's the Complete Breakdown

Carter — Fri, 01 May 2026 21:47:41 +0000

Most invoice tools are either too expensive or too complicated. I built my own in one week and deployed it live. Here is every technical decision I made and what I learned.

Live demo: https://invoxa-eta.vercel.app
GitHub: https://github.com/Carter254g/invoxa

What It Does

Invoxa lets you create clients, generate invoices with line items, track payment status, and see your revenue on a dashboard. Multi-currency support included.

The Stack

React on the frontend. Node.js and Express on the backend. PostgreSQL for the database. Deployed on Vercel and Render.

Simple. No unnecessary complexity.

The Part Most Tutorials Skip — Auth Middleware

Every protected route in the API runs through this middleware before the controller even sees the request:

const auth = (req, res, next) => {
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'No token provided' });
  }
  const token = authHeader.split(' ')[1];
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid or expired token' });
  }
};

Clean. Reusable. One function protects every route.

Database Migrations on Startup

Instead of manually creating tables, the server runs migrations automatically on startup:

migrate.createTables().then(() => {
  app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
  });
});

Anyone who clones the repo gets a working database in seconds.

The Axios Interceptor That Saved Me Hours

Instead of attaching the JWT token to every API call manually, one interceptor handles it globally:

api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

Write it once. Forget about it.

What Broke in Production

Three things hit me during deployment:

Render requires SSL for PostgreSQL connections. Add rejectUnauthorized: false to your pg Pool config in production or nothing works.
CORS needs to explicitly list your Vercel domain. A wildcard does not work with credentials.
JWT expiry values from environment variables need to be strings. When the value comes back undefined from the env, jwt.sign throws a silent error. Hardcode the fallback.

These cost me two hours. Now they cost you nothing.

The Dashboard Pulls Real Data

The dashboard shows total invoices, total clients, revenue collected, and outstanding balance — all calculated from live database queries on every load.

No fake data. No hardcoded numbers.

What is Next

PDF export for invoices
Email delivery via Nodemailer
Recurring invoices
Payment gateway integration

Try It and Star the Repo

Live app: https://invoxa-eta.vercel.app

If this helped you, star the repo on GitHub and drop a comment below
GitHub: https://github.com/Carter254g/invoxa
javascript
node
react
webdev