mansaapi

Official Dart and Flutter SDK for the Mansa API — African data infrastructure for developers and AI agents. Live stock market data from 16+ African exchanges, macro indicators with provenance, company fundamentals, and identity & location reference data. Built in Lagos by Mansa Labs.

Pure Dart — works in Flutter (Android, iOS, web, desktop) and server-side Dart. Single runtime dependency: package:http.

Install

dart pub add mansaapi
# or, in a Flutter project:
flutter pub add mansaapi

Get an API key

Every request needs a Bearer token. Get a free key instantly (100 requests/day, no credit card) at mansaapi.com/docs#get-api-key.

Quickstart (Flutter)

import 'package:flutter/material.dart';
import 'package:mansaapi/mansaapi.dart';

final mansa = MansaAPI(apiKey: 'mansa_live_sk_...');

class MarketDashboard extends StatefulWidget {
  const MarketDashboard({super.key});

  @override
  State<MarketDashboard> createState() => _MarketDashboardState();
}

class _MarketDashboardState extends State<MarketDashboard> {
  late final Future<({List<dynamic> gainers, bool ngxOpen, List<dynamic> rates})>
      _data = _load();

  Future<({List<dynamic> gainers, bool ngxOpen, List<dynamic> rates})>
      _load() async {
    // Run the three calls in parallel.
    final results = await Future.wait([
      mansa.markets.getPanAfricanMovers(limit: 10), // top movers, all Africa
      mansa.markets.isOpen('NGX'),                  // is NGX trading now?
      mansa.macro.getPolicyRates(),                 // central bank rates
    ]);
    final movers = results[0] as Map<String, dynamic>;
    final status = results[1] as Map<String, dynamic>;
    return (
      gainers: movers['gainers'] as List<dynamic>,
      ngxOpen: status['is_open'] == true,
      rates: results[2] as List<dynamic>,
    );
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: _data,
      builder: (context, snapshot) {
        if (snapshot.hasError) {
          final error = snapshot.error;
          final message = error is MansaAPIException
              ? '${error.message}${error.hint != null ? '\n${error.hint}' : ''}'
              : 'Something went wrong';
          return Center(child: Text(message));
        }
        if (!snapshot.hasData) {
          return const Center(child: CircularProgressIndicator());
        }
        final data = snapshot.data!;
        return ListView(
          children: [
            ListTile(
              title: const Text('Nigerian Exchange'),
              trailing: Text(data.ngxOpen ? 'OPEN' : 'CLOSED'),
            ),
            for (final mover in data.gainers.cast<Map<String, dynamic>>())
              ListTile(
                title: Text('${mover['ticker']}'),
                subtitle: Text('${mover['exchange']}'),
                trailing: Text('${mover['change_pct']}%'),
              ),
          ],
        );
      },
    );
  }
}

Works exactly the same in plain Dart on the server — see example/mansaapi_example.dart.

Error handling

Every method throws MansaAPIException on an API error envelope, HTTP error, or network failure:

try {
  final stock = await mansa.markets.getStock('NGX', 'GTCO');
  print(stock['price']);
} on MansaAPIException catch (e) {
  print(e.code);       // e.g. INVALID_API_KEY, PAYMENT_REQUIRED, NOT_FOUND
  print(e.statusCode); // e.g. 401, 402, 404, 429 (0 = network failure)
  print(e.message);    // human-readable description
  print(e.hint);       // optional pointer, e.g. where to get a key
  if (e.isRateLimited) {
    // back off and retry tomorrow, or upgrade your tier
  }
}

Configuration

final mansa = MansaAPI(
  apiKey: 'mansa_live_sk_...',
  baseUrl: 'https://mansaapi.com/api/v1', // default
  timeout: const Duration(seconds: 30),   // default
  httpClient: myClient,                   // optional, e.g. for tests
);

// When you're done (e.g. in dispose()):
mansa.close();

Methods return the decoded data payload (Map<String, dynamic> or List). A few endpoints whose useful fields live alongside data (noted below) return the full payload instead.

Methods

mansa.markets

Method	Endpoint	Returns
getExchanges()	GET /markets/exchanges	List
getExchange(exchangeCode)	GET /markets/exchanges/{exchange}	Map
getStocks(exchangeCode, {limit, offset, sector, sortBy, order})	GET /markets/exchanges/{exchange}/stocks	List
getStock(exchangeCode, ticker)	GET /markets/exchanges/{exchange}/stocks/{ticker}	Map
getStockHistory(exchangeCode, ticker, {range})	GET /markets/exchanges/{exchange}/stocks/{ticker}/history	Map
getStockFundamentals(exchangeCode, ticker)	GET /markets/exchanges/{exchange}/stocks/{ticker}/fundamentals	Map
getMovers(exchangeCode, {limit, type})	GET /markets/exchanges/{exchange}/movers	Map (gainers/losers lists)
getPanAfricanMovers({limit})	GET /markets/movers/pan-african	Map (gainers/losers lists)
search(query, {exchange, limit})	GET /markets/search	List
getTrending({limit})	GET /markets/trending	List
getAllIndices()	GET /markets/indices	List
getIndexHistory(indexCode, {from, to})	GET /markets/indices/{code}/history	Map
getIndices(exchangeCode)	GET /markets/exchanges/{exchange}/indices	List
getIndex(exchangeCode, code)	GET /markets/exchanges/{exchange}/indices/{code}	Map
getExchangeIndexHistory(exchangeCode, code, {range})	GET /markets/exchanges/{exchange}/indices/{code}/history	Map
getETFs(exchangeCode)	GET /markets/exchanges/{exchange}/etfs	List
getETF(exchangeCode, symbol)	GET /markets/exchanges/{exchange}/etfs/{symbol}	Map
resolveETF(exchangeCode, symbol)	GET /markets/exchanges/{exchange}/etfs/resolve/{symbol}	Map (full payload)
getForex()	GET /markets/forex	List
getCommodities()	GET /markets/commodities	List
isOpen(exchangeCode)	GET /markets/calendar/{exchange}/is-open	Map
getCalendar(exchangeCode, {year}) †	GET /markets/calendar/{exchange}	Map
getDividends(exchangeCode, ticker, {limit}) †	GET /markets/exchanges/{exchange}/dividends/{ticker}	Map (full payload)
getDividendsCalendar(exchangeCode, {upcoming, from, to, symbol, limit}) †	GET /markets/exchanges/{exchange}/dividends-calendar	Map (full payload)
getDisclosures(exchangeCode, {symbol, type, company, limit}) †	GET /markets/exchanges/{exchange}/disclosures	List
getInsiderTrades(exchangeCode, {symbol, side, days, limit}) ‡	GET /markets/exchanges/{exchange}/insider-trades	Map (full payload incl. stats)
getRecommendations(exchangeCode, {week}) †	GET /markets/exchanges/{exchange}/recommendations	Map (full payload)
getBonds(country, {type}) ‡	GET /markets/bonds/{country}	List
getYieldCurve(country) ‡	GET /markets/yields/{country}/curve	List
getTreasuryBills(country, {limit}) ‡	GET /markets/yields/{country}/tbills	List
getAuctions(country, {type, limit}) ‡	GET /markets/yields/{country}/auctions	List

mansa.macro

Method	Endpoint	Returns
getPolicyRates()	GET /macro/policy-rates	List
getIndicators({country})	GET /macro/indicators	List
getIndicatorHistory(country, indicator, {from, to}) †	GET /macro/{country}/{indicator}/history	List

mansa.fundamentals

Method	Endpoint	Returns
getFundamentals(exchangeCode, ticker) †	GET /fundamentals/{exchange}/{ticker}	Map
getMetrics(exchangeCode, ticker) †	GET /metrics/{exchange}/{ticker}	Map
screen({exchange, peMax, pbMax, dividendYieldMin, roeMin, zMin, marketCapUsdMin, consensus, verifiedOnly, limit}) †	GET /screener	Map

mansa.identity

Method	Endpoint	Returns
getBanks({country, type})	GET /identity/banks	List
getBank(bankCode)	GET /identity/banks/{code}	Map
getMobileNetworks({country})	GET /identity/mobile-networks	List
lookupMobileNetwork(phone)	GET /identity/mobile-networks/lookup	Map
getCurrencies()	GET /identity/currencies	List
getCurrency(currencyCode)	GET /identity/currencies/{code}	Map
validateNuban(account, bankCode)	GET /identity/nuban/validate	Map

mansa.location

Method	Endpoint	Returns
getCountries({region})	GET /location/countries	List
getCountry(code)	GET /location/countries/{code}	Map
getStates(countryCode)	GET /location/countries/{code}/states	List
getLgas(countryCode, stateCode)	GET /location/countries/{code}/states/{state}/lgas	List
getPostalCodes(countryCode, stateCode, {lga, limit, offset})	GET /location/countries/{code}/states/{state}/postal-codes	Map
getHolidays(countryCode, year)	GET /location/countries/{code}/holidays/{year}	List

† Starter tier and above ‡ Professional tier and above. All other endpoints are available on the free tier.

Documentation

Full endpoint reference, response shapes, and tier details: mansaapi.com/docs

License

MIT © 2026 Mansa Labs