comparex-api

Nigerian fintech API client for Node.js and TypeScript. 156 endpoints across 16 categories - banking, identity verification, exchange rates, crypto, tax, telecom, education, insurance, employment, real estate, and more.

Install

npm install comparex-api

Quick Start

import { Comparex } from 'comparex-api';

const client = new Comparex({
  apiKey: 'cx_your_api_key_here',
});

// List Nigerian banks
const banks = await client.banks.list();
console.log(banks.data.items);

// Validate a BVN
const result = await client.identity.validateBvn('22212345678');
console.log(result.data.valid); // true

// Get exchange rates
const rates = await client.rates.currencies();
console.log(rates.data.items);

Get your free API key at comparex.kelthos.com/api-hub

API Reference

Banking (16 endpoints)

client.banks.list({ type: 'commercial', search: 'access' })
client.banks.get('058')             // Bank by NIBSS code
client.banks.fees('058')            // Fee breakdown
client.banks.features('058')        // Mobile, USSD, cards
client.banks.accountTypes('058')    // Savings, current, domiciliary
client.banks.digital('058')         // Digital banking services
client.banks.rates('058')           // Interest rates
client.banks.info('058')            // SWIFT, HQ, CEO
client.banks.branches('058')        // Branch/ATM counts
client.banks.holidays()             // Bank holidays 2026
client.banks.bins()                 // Card BIN directory
client.banks.binLookup('506118')    // BIN lookup
client.banks.gateways()             // Payment gateways
client.banks.transferFees()         // NIP/NEFT/RTGS fees
client.banks.compare(['gtb', 'access', 'zenith'])
client.banks.stats()

Geography (14 endpoints)

client.geo.states({ zone: 'South West', sort: 'population' })
client.geo.state('LA')              // Lagos details
client.geo.lgas('LA')               // LGAs in Lagos
client.geo.cities('LA')             // Cities in Lagos
client.geo.industries('LA')         // Industries
client.geo.rent('LA')               // Rent data
client.geo.postalCodes('LA')        // Postal codes
client.geo.demographics('LA')       // Demographics
client.geo.zones()                  // 6 geopolitical zones
client.geo.zone('south-west')       // States in zone
client.geo.searchLgas('ikeja')      // Search 774 LGAs
client.geo.capitals()               // All state capitals
client.geo.search('lekki')          // Search everything
client.geo.stats()

Telecom (13 endpoints)

client.telecom.providers()
client.telecom.provider('mtn')
client.telecom.plans('mtn', { sort: 'price' })
client.telecom.carrierPrefixes('mtn')
client.telecom.ussd('mtn')
client.telecom.customerCare('mtn')
client.telecom.lookup('08012345678') // Carrier lookup
client.telecom.prefixes()
client.telecom.prefixLookup('0801')
client.telecom.isps()
client.telecom.isp('spectranet')
client.telecom.ncc()
client.telecom.stats()

Tax (17 endpoints)

client.tax.paye()                    // Tax brackets
client.tax.calculatePaye(5000000)    // PAYE for N5M income
client.tax.vat()
client.tax.calculateVat(100000)
client.tax.wht()
client.tax.whtByType('dividends')
client.tax.cit()
client.tax.calculateCit(10000000, 50000000)
client.tax.netSalary(500000)         // Net from N500K gross
client.tax.capitalGains()
client.tax.stampDuty()
client.tax.pension()
client.tax.nhf()
client.tax.allowances()
client.tax.authorities()
client.tax.calendar()
client.tax.summary()

Education (10 endpoints)

client.education.universities({ type: 'Federal', sort: 'cutoff' })
client.education.university('UNILAG')
client.education.polytechnics()
client.education.polytechnic('YABATECH')
client.education.jamb()
client.education.nysc()
client.education.professionalBodies()
client.education.professionalBody('ICAN')
client.education.stats()
client.education.search('computer science')

Identity Validation (12 endpoints)

client.identity.validateBvn('22212345678')
client.identity.validateNin('12345678901')
client.identity.validateNuban('0123456789', '058')
client.identity.validatePhone('08012345678')
client.identity.validateEmail('[email protected]')
client.identity.validateTin('12345678-0001')
client.identity.validateCac('RC123456')
client.identity.validateVotersCard('90F5B1234567890123')
client.identity.validateDriversLicense('AAA12345AA01')
client.identity.validatePassport('A12345678')
client.identity.documents()
client.identity.document('bvn')

Exchange Rates & Crypto (11 endpoints)

client.rates.currencies()
client.rates.currency('USD')
client.rates.convert(100, 'USD', 'NGN')   // Convert $100
client.rates.history({ from: '2025-01-01' })
client.rates.bdc()                          // Parallel market
client.rates.crypto()                       // BTC, ETH, USDT in NGN
client.rates.cryptoRate('BTC')
client.rates.cryptoExchanges()             // Quidax, Luno, etc.
client.rates.cryptoExchange('quidax')
client.rates.validateWallet('bc1q...', 'bitcoin')
client.rates.stats()

Utilities (15 endpoints)

client.utilities.discos()
client.utilities.disco('ekedc')
client.utilities.tariffs('ekedc')
client.utilities.coverage('ekedc')
client.utilities.paymentChannels('ekedc')
client.utilities.meters('ekedc')
client.utilities.calculateBill(200, 'ekedc', 'R2') // 200 kWh
client.utilities.cableTv()                 // DSTV, GOtv, StarTimes
client.utilities.cableTvProvider('dstv')
client.utilities.gas()
client.utilities.lpgPrices()               // Cooking gas prices
client.utilities.gasProvider('ng-gas')
client.utilities.water()
client.utilities.waterCorp('lagos')
client.utilities.stats()

Insurance (10 endpoints)

client.insurance.providers({ type: 'Life' })
client.insurance.provider('leadway')
client.insurance.products('leadway')
client.insurance.motorTypes()
client.insurance.motorQuote(15000000, 'comprehensive') // N15M car
client.insurance.health()
client.insurance.healthProvider('hygeia')
client.insurance.nhis()
client.insurance.naicom()
client.insurance.stats()

Employment (11 endpoints)

client.employment.salaries({ category: 'technology', sort: 'highest' })
client.employment.sectors()
client.employment.sector('technology')
client.employment.salary('software-engineer')
client.employment.minimumWage()
client.employment.laborLaws()
client.employment.employers({ sector: 'banking' })
client.employment.employer('dangote')
client.employment.jobBoards()
client.employment.jobBoard('jobberman')
client.employment.stats()

Real Estate (6 endpoints)

client.realEstate.prices({ state: 'Lagos', sort: 'rent' })
client.realEstate.area('lekki')
client.realEstate.mortgageProviders()
client.realEstate.mortgageProvider('fmbn')
client.realEstate.calculateMortgage(50000000, 18, 20) // N50M, 18%, 20yrs
client.realEstate.stats()

Transport (5 endpoints)

client.transport.fuelPrices()
client.transport.vehicleRegistration()
client.transport.rideHailing()
client.transport.rideService('uber')
client.transport.stats()

Agriculture (3 endpoints)

client.agriculture.commodities({ category: 'Grains' })
client.agriculture.commodity('rice')
client.agriculture.stats()

Business (7 endpoints)

client.business.companyTypes()
client.business.companyType('llc')
client.business.cacFees()
client.business.stockExchange()
client.business.stocks({ sector: 'banking' })
client.business.stock('DANGCEM')
client.business.stats()

Legal (3 endpoints)

client.legal.courtFees()
client.legal.services()
client.legal.summary()

Cost of Living (3 endpoints)

client.costOfLiving.cities({ sort: 'expensive' })
client.costOfLiving.city('lagos')
client.costOfLiving.compare('lagos', 'abuja')

Error Handling

import { Comparex, ComparexError } from 'comparex-api';

const client = new Comparex({ apiKey: 'cx_...' });

try {
  const data = await client.banks.list();
} catch (err) {
  if (err instanceof ComparexError) {
    console.log(err.status);  // HTTP status code
    console.log(err.message); // Error message
    console.log(err.body);    // Full response body
  }
}

Configuration

const client = new Comparex({
  apiKey: 'cx_your_key',
  baseUrl: 'https://comparex.kelthos.com', // default
  timeout: 30000,                           // ms, default 30s
});

Plans

| Plan | Requests | Price | |------|----------|-------| | Free | 1,000/month | Free | | Pro | 50,000/month | 0.1 SOL | | Enterprise | 1,000,000/month | 0.5 SOL |

Get your key: comparex.kelthos.com/api-hub

License

MIT