mansaapi 0.1.0__tar.gz

mansaapi-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.pytest_cache/

mansaapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mansa Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mansaapi-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: mansaapi
+Version: 0.1.0
+Summary: Official Python SDK for Mansa API — African market data, bank codes, location, and identity.
+Project-URL: Homepage, https://mansaapi.com
+Project-URL: Documentation, https://mansaapi.com/docs
+Project-URL: Repository, https://github.com/HeyZod/mansaapi-python
+Author: Mansa Labs
+License: MIT
+License-File: LICENSE
+Keywords: africa,african,api,bank codes,fintech,ngx,nigeria,sdk,stock market
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Description-Content-Type: text/markdown
+
+# mansaapi (Python)
+
+Official Python SDK for [Mansa API](https://mansaapi.com) — African market data, bank codes, location, and financial identity in one clean REST layer.
+
+[![PyPI version](https://img.shields.io/pypi/v/mansaapi.svg)](https://pypi.org/project/mansaapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Install
+
+```bash
+pip install mansaapi
+```
+
+## Quick start
+
+```python
+from mansaapi import MansaAPI
+
+mansa = MansaAPI(api_key="mansa_live_sk_...")
+
+# GTBank by code
+bank = mansa.identity.get_bank("058")
+print(bank["data"]["name"])        # "Guaranty Trust Bank (GTBank)"
+print(bank["data"]["swift_code"])  # "GTBINGLA"
+
+# Pan-African market movers
+movers = mansa.markets.get_pan_african_movers(limit=10)
+
+# Nigerian public holidays 2026
+holidays = mansa.location.get_holidays("NG", 2026)
+```
+
+Get a free API key at [mansaapi.com](https://mansaapi.com) — 100 requests/day, no credit card.
+
+---
+
+## Markets
+
+```python
+mansa.markets.get_exchanges()
+mansa.markets.get_stocks("NGX", sector="Banking", limit=20)
+mansa.markets.get_stock("NGX", "GTCO")
+mansa.markets.get_movers("NGX", type="gainers")
+mansa.markets.get_pan_african_movers()
+mansa.markets.get_indices("NGX")
+mansa.markets.get_etfs("NGX")
+mansa.markets.get_forex()
+mansa.markets.get_commodities()
+mansa.markets.search("Zenith", exchange="NGX")
+```
+
+### Premium endpoints
+
+Starter tier or higher for dividends, disclosures, recommendations.
+Pro tier for insider trades. See [mansaapi.com/pricing](https://mansaapi.com/pricing).
+
+```python
+mansa.markets.get_dividends("NGX", "GTCO")          # Starter+
+mansa.markets.get_disclosures("NGX", symbol="GTCO")  # Starter+
+mansa.markets.get_recommendations("NGX")             # Starter+
+mansa.markets.get_insider_trades("NGX", days=30)     # Pro+
+```
+
+---
+
+## Identity
+
+```python
+mansa.identity.get_banks()                     # all African banks
+mansa.identity.get_banks(country="NG")         # filter by country
+mansa.identity.get_bank("057")                 # single bank by code
+mansa.identity.get_mobile_networks(country="GH")
+mansa.identity.lookup_mobile_network("08031234567")
+mansa.identity.get_currencies()
+mansa.identity.validate_nuban("0123456789", "058")
+```
+
+---
+
+## Location
+
+```python
+mansa.location.get_countries()
+mansa.location.get_country("NG")
+mansa.location.get_states("NG")
+mansa.location.get_lgas("NG", "LA")        # Lagos LGAs
+mansa.location.get_holidays("NG", 2026)
+```
+
+---
+
+## Error handling
+
+```python
+from mansaapi import MansaAPI, MansaAPIError
+
+mansa = MansaAPI(api_key="mansa_live_sk_...")
+
+try:
+    data = mansa.markets.get_insider_trades("NGX")
+except MansaAPIError as err:
+    print(err.code)     # "TIER_REQUIRED"
+    print(err.status)   # 403
+    print(err.message)  # "This endpoint requires a professional tier key..."
+```
+
+### Error codes
+
+| Code | Status | Meaning |
+|---|---|---|
+| `INVALID_API_KEY` | 401 | Key not found or revoked |
+| `RATE_LIMIT_EXCEEDED` | 429 | Daily request limit reached |
+| `TIER_REQUIRED` | 403 | Endpoint requires a higher tier |
+| `NOT_FOUND` | 404 | Resource not found |
+| `UPSTREAM_ERROR` | 502 | Upstream data source unreachable |
+
+---
+
+## Supported exchanges
+
+NGX (Nigeria), GSE (Ghana), NSE (Kenya), JSE (South Africa), BRVM (West Africa), DSE (Tanzania), LUSE (Zambia).
+
+---
+
+## Links
+
+- [Documentation](https://mansaapi.com/docs)
+- [Python quickstart](https://mansaapi.com/docs/quickstart/python)
+- [Pricing](https://mansaapi.com/pricing)
+- [OpenAPI spec](https://mansaapi.com/openapi.json)
+- [api@mansamarkets.com](mailto:api@mansamarkets.com)

mansaapi-0.1.0/README.md

@@ -0,0 +1,131 @@
+# mansaapi (Python)
+
+Official Python SDK for [Mansa API](https://mansaapi.com) — African market data, bank codes, location, and financial identity in one clean REST layer.
+
+[![PyPI version](https://img.shields.io/pypi/v/mansaapi.svg)](https://pypi.org/project/mansaapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Install
+
+```bash
+pip install mansaapi
+```
+
+## Quick start
+
+```python
+from mansaapi import MansaAPI
+
+mansa = MansaAPI(api_key="mansa_live_sk_...")
+
+# GTBank by code
+bank = mansa.identity.get_bank("058")
+print(bank["data"]["name"])        # "Guaranty Trust Bank (GTBank)"
+print(bank["data"]["swift_code"])  # "GTBINGLA"
+
+# Pan-African market movers
+movers = mansa.markets.get_pan_african_movers(limit=10)
+
+# Nigerian public holidays 2026
+holidays = mansa.location.get_holidays("NG", 2026)
+```
+
+Get a free API key at [mansaapi.com](https://mansaapi.com) — 100 requests/day, no credit card.
+
+---
+
+## Markets
+
+```python
+mansa.markets.get_exchanges()
+mansa.markets.get_stocks("NGX", sector="Banking", limit=20)
+mansa.markets.get_stock("NGX", "GTCO")
+mansa.markets.get_movers("NGX", type="gainers")
+mansa.markets.get_pan_african_movers()
+mansa.markets.get_indices("NGX")
+mansa.markets.get_etfs("NGX")
+mansa.markets.get_forex()
+mansa.markets.get_commodities()
+mansa.markets.search("Zenith", exchange="NGX")
+```
+
+### Premium endpoints
+
+Starter tier or higher for dividends, disclosures, recommendations.
+Pro tier for insider trades. See [mansaapi.com/pricing](https://mansaapi.com/pricing).
+
+```python
+mansa.markets.get_dividends("NGX", "GTCO")          # Starter+
+mansa.markets.get_disclosures("NGX", symbol="GTCO")  # Starter+
+mansa.markets.get_recommendations("NGX")             # Starter+
+mansa.markets.get_insider_trades("NGX", days=30)     # Pro+
+```
+
+---
+
+## Identity
+
+```python
+mansa.identity.get_banks()                     # all African banks
+mansa.identity.get_banks(country="NG")         # filter by country
+mansa.identity.get_bank("057")                 # single bank by code
+mansa.identity.get_mobile_networks(country="GH")
+mansa.identity.lookup_mobile_network("08031234567")
+mansa.identity.get_currencies()
+mansa.identity.validate_nuban("0123456789", "058")
+```
+
+---
+
+## Location
+
+```python
+mansa.location.get_countries()
+mansa.location.get_country("NG")
+mansa.location.get_states("NG")
+mansa.location.get_lgas("NG", "LA")        # Lagos LGAs
+mansa.location.get_holidays("NG", 2026)
+```
+
+---
+
+## Error handling
+
+```python
+from mansaapi import MansaAPI, MansaAPIError
+
+mansa = MansaAPI(api_key="mansa_live_sk_...")
+
+try:
+    data = mansa.markets.get_insider_trades("NGX")
+except MansaAPIError as err:
+    print(err.code)     # "TIER_REQUIRED"
+    print(err.status)   # 403
+    print(err.message)  # "This endpoint requires a professional tier key..."
+```
+
+### Error codes
+
+| Code | Status | Meaning |
+|---|---|---|
+| `INVALID_API_KEY` | 401 | Key not found or revoked |
+| `RATE_LIMIT_EXCEEDED` | 429 | Daily request limit reached |
+| `TIER_REQUIRED` | 403 | Endpoint requires a higher tier |
+| `NOT_FOUND` | 404 | Resource not found |
+| `UPSTREAM_ERROR` | 502 | Upstream data source unreachable |
+
+---
+
+## Supported exchanges
+
+NGX (Nigeria), GSE (Ghana), NSE (Kenya), JSE (South Africa), BRVM (West Africa), DSE (Tanzania), LUSE (Zambia).
+
+---
+
+## Links
+
+- [Documentation](https://mansaapi.com/docs)
+- [Python quickstart](https://mansaapi.com/docs/quickstart/python)
+- [Pricing](https://mansaapi.com/pricing)
+- [OpenAPI spec](https://mansaapi.com/openapi.json)
+- [api@mansamarkets.com](mailto:api@mansamarkets.com)

mansaapi-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mansaapi"
+version = "0.1.0"
+description = "Official Python SDK for Mansa API — African market data, bank codes, location, and identity."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Mansa Labs" }]
+requires-python = ">=3.8"
+keywords = ["africa", "african", "stock market", "bank codes", "nigeria", "ngx", "fintech", "api", "sdk"]
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://mansaapi.com"
+Documentation = "https://mansaapi.com/docs"
+Repository = "https://github.com/HeyZod/mansaapi-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mansaapi"]

mansaapi-0.1.0/src/mansaapi/__init__.py

@@ -0,0 +1,4 @@
+from ._client import MansaAPI, __version__
+from .errors import MansaAPIError
+
+__all__ = ["MansaAPI", "MansaAPIError", "__version__"]

mansaapi-0.1.0/src/mansaapi/_client.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .errors import MansaAPIError
+
+__version__ = "0.1.0"
+DEFAULT_BASE_URL = "https://mansaapi.com"
+
+Params = Optional[Dict[str, Any]]
+
+
+class _HttpClient:
+    def __init__(self, api_key: str, base_url: str, timeout: float) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"mansaapi-python/{__version__}",
+            }
+        )
+
+    def get(self, path: str, params: Params = None) -> Dict[str, Any]:
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        resp = self._session.get(
+            f"{self._base_url}{path}", params=clean, timeout=self._timeout
+        )
+        return self._handle(resp)
+
+    def post(self, path: str, payload: Any) -> Dict[str, Any]:
+        resp = self._session.post(
+            f"{self._base_url}{path}", json=payload, timeout=self._timeout
+        )
+        return self._handle(resp)
+
+    @staticmethod
+    def _handle(resp: requests.Response) -> Dict[str, Any]:
+        try:
+            body = resp.json()
+        except ValueError:
+            raise MansaAPIError(
+                "INVALID_RESPONSE",
+                f"Non-JSON response (status {resp.status_code})",
+                resp.status_code,
+                resp.text,
+            )
+
+        if not resp.ok or body.get("success") is False:
+            err = body.get("error") or {}
+            raise MansaAPIError(
+                err.get("code", "UNKNOWN_ERROR"),
+                err.get("message", f"Request failed with status {resp.status_code}"),
+                resp.status_code,
+                body,
+            )
+        return body
+
+
+class _Markets:
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    def get_exchanges(self) -> Dict[str, Any]:
+        return self._http.get("/api/v1/markets/exchanges")
+
+    def get_exchange(self, exchange_code: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/markets/exchanges/{exchange_code}")
+
+    def get_stocks(self, exchange_code: str, **params: Any) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/markets/exchanges/{exchange_code}/stocks", params)
+
+    def get_stock(self, exchange_code: str, ticker: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/markets/exchanges/{exchange_code}/stocks/{ticker}")
+
+    def get_movers(self, exchange_code: str, **params: Any) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/markets/exchanges/{exchange_code}/movers", params)
+
+    def get_pan_african_movers(self, **params: Any) -> Dict[str, Any]:
+        return self._http.get("/api/v1/markets/movers/pan-african", params)
+
+    def get_indices(self, exchange_code: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/markets/exchanges/{exchange_code}/indices")
+
+    def get_index(self, exchange_code: str, code: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/markets/exchanges/{exchange_code}/indices/{code}")
+
+    def get_etfs(self, exchange_code: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/markets/exchanges/{exchange_code}/etfs")
+
+    def get_forex(self) -> Dict[str, Any]:
+        return self._http.get("/api/v1/markets/forex")
+
+    def get_commodities(self) -> Dict[str, Any]:
+        return self._http.get("/api/v1/markets/commodities")
+
+    def search(self, query: str, **params: Any) -> Dict[str, Any]:
+        return self._http.get("/api/v1/markets/search", {"q": query, **params})
+
+    # Premium (Starter+)
+    def get_dividends(self, exchange_code: str, ticker: str, **params: Any) -> Dict[str, Any]:
+        return self._http.get(
+            f"/api/v1/markets/exchanges/{exchange_code}/dividends/{ticker}", params
+        )
+
+    def get_disclosures(self, exchange_code: str, **params: Any) -> Dict[str, Any]:
+        return self._http.get(
+            f"/api/v1/markets/exchanges/{exchange_code}/disclosures", params
+        )
+
+    def get_recommendations(self, exchange_code: str, **params: Any) -> Dict[str, Any]:
+        return self._http.get(
+            f"/api/v1/markets/exchanges/{exchange_code}/recommendations", params
+        )
+
+    # Premium (Pro+)
+    def get_insider_trades(self, exchange_code: str, **params: Any) -> Dict[str, Any]:
+        return self._http.get(
+            f"/api/v1/markets/exchanges/{exchange_code}/insider-trades", params
+        )
+
+
+class _Identity:
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    def get_banks(self, country: Optional[str] = None) -> Dict[str, Any]:
+        return self._http.get("/api/v1/identity/banks", {"country": country})
+
+    def get_bank(self, code: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/identity/banks/{code}")
+
+    def get_mobile_networks(self, country: Optional[str] = None) -> Dict[str, Any]:
+        return self._http.get("/api/v1/identity/mobile-networks", {"country": country})
+
+    def lookup_mobile_network(self, phone: str) -> Dict[str, Any]:
+        return self._http.get("/api/v1/identity/mobile-networks/lookup", {"phone": phone})
+
+    def get_currencies(self) -> Dict[str, Any]:
+        return self._http.get("/api/v1/identity/currencies")
+
+    def validate_nuban(self, account: str, bank_code: str) -> Dict[str, Any]:
+        return self._http.get(
+            "/api/v1/identity/nuban/validate",
+            {"account": account, "bank_code": bank_code},
+        )
+
+
+class _Location:
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    def get_countries(self) -> Dict[str, Any]:
+        return self._http.get("/api/v1/location/countries")
+
+    def get_country(self, code: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/location/countries/{code}")
+
+    def get_states(self, country_code: str) -> Dict[str, Any]:
+        return self._http.get(f"/api/v1/location/countries/{country_code}/states")
+
+    def get_lgas(self, country_code: str, state_code: str) -> Dict[str, Any]:
+        return self._http.get(
+            f"/api/v1/location/countries/{country_code}/states/{state_code}/lgas"
+        )
+
+    def get_holidays(self, country_code: str, year: int) -> Dict[str, Any]:
+        return self._http.get(
+            f"/api/v1/location/countries/{country_code}/holidays/{year}"
+        )
+
+
+class _Keys:
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    def create(self, name: str, email: str, project_description: Optional[str] = None) -> Dict[str, Any]:
+        return self._http.post(
+            "/api/v1/keys",
+            {
+                "name": name,
+                "email": email,
+                "tier": "standard",
+                "project_description": project_description,
+            },
+        )
+
+
+class MansaAPI:
+    """Official Python client for the Mansa API.
+
+    Example:
+        from mansaapi import MansaAPI
+
+        mansa = MansaAPI(api_key="mansa_live_sk_...")
+        bank = mansa.identity.get_bank("058")
+        print(bank["data"]["name"])  # "Guaranty Trust Bank (GTBank)"
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required. Get one free at https://mansaapi.com")
+        http = _HttpClient(api_key, base_url, timeout)
+        self.markets = _Markets(http)
+        self.identity = _Identity(http)
+        self.location = _Location(http)
+        self.keys = _Keys(http)

mansaapi-0.1.0/src/mansaapi/errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MansaAPIError(Exception):
+    """Raised when the Mansa API returns an error response."""
+
+    def __init__(self, code: str, message: str, status: int, raw: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.raw = raw
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"MansaAPIError(code={self.code!r}, status={self.status}, message={self.message!r})"