xoomar 0.1.0__tar.gz

xoomar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XOOMAR
+
+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.

xoomar-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: xoomar
+Version: 0.1.0
+Summary: Client for the XOOMAR free market data API: short interest, insider trades, COT, funding rates, Fed liquidity, SEC filings and more.
+Author-email: XOOMAR <info@xoomar.com>
+License: MIT
+Project-URL: Homepage, https://xoomar.com/markets/api
+Project-URL: Documentation, https://xoomar.com/markets/api
+Project-URL: Source, https://github.com/xoomar-llc/xoomar-python
+Project-URL: Data, https://xoomar.com/markets
+Keywords: market data,sec,finra,cot,short interest,insider trading,crypto,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# xoomar
+
+Python client for the [XOOMAR](https://xoomar.com/markets) free market data API: 29 datasets from primary sources (SEC EDGAR and XBRL, FINRA, CFTC, the Federal Reserve, USAspending, exchange APIs) as clean JSON, no key needed to start.
+
+```bash
+pip install xoomar
+```
+
+```python
+from xoomar import Xoomar
+
+x = Xoomar()                          # 30 requests a minute; Xoomar(api_key="...") for 120 with a free key
+
+x.short_interest("GME")[-1]           # FINRA short interest, latest settlement
+x.short_volume("GME", days=30)        # FINRA daily short sale volume
+x.fails_to_deliver("GME")             # SEC fails to deliver
+x.insiders("NVDA")                    # SEC Form 4 trades
+x.large_holders("HIMS")               # Schedule 13D and 13G holders
+x.financials("AAPL")["quarterly"]     # XBRL income statement by quarter
+x.fund_holders("AMZN")                # which tracked 13F managers hold it
+x.cot("gold")                         # CFTC positioning history
+x.fed_liquidity()[-1]                 # net liquidity, this week
+x.funding_rates()                     # perpetual funding on three exchanges
+x.bitcoin_treasuries()                # bitcoin on public balance sheets
+x.form_d(days=7)                      # private placements filed this week
+x.federal_contracts(ticker="LMT")     # federal contract actions
+```
+
+Every method returns the `data` part of the response; `x.last_meta` holds `updatedAt`, `source`, `license` and `attribution` from the last call. `x.get("short-interest", symbol="TSLA")` calls any endpoint directly and `x.csv("short-interest/csv")` fetches a CSV download.
+
+Full endpoint reference, fields and limits: https://xoomar.com/markets/api
+
+## Datasets
+
+Short interest, daily short volume, fails to deliver, insider trades (Form 4), planned sales (Form 144), large holders (13D/13G), 13F fund holdings, company financials and buybacks (XBRL), 8-K events, structured products, federal contracts, Form D private placements, the IPO pipeline, bitcoin treasuries, CFTC COT, funding rates, open interest, liquidations, options, whale positions, sentiment, signals, ETF flows, prediction markets, Fed liquidity, macro, policy rates, economic calendar.
+
+## Rate limits and keys
+
+30 requests a minute per IP without a key. A free account at https://xoomar.com/signup gives a key for 120 a minute; pass it as `Xoomar(api_key=...)`. A 429 raises `XoomarRateLimited` with `retry_after`.
+
+## Attribution
+
+The data is free to use, including commercially. When you republish it, on a site, in an app, in an article, in a dataset or a chart, credit XOOMAR with a visible link to the dataset page on xoomar.com. Terms: https://xoomar.com/terms
+
+## License
+
+MIT, XOOMAR.

xoomar-0.1.0/README.md

@@ -0,0 +1,47 @@
+# xoomar
+
+Python client for the [XOOMAR](https://xoomar.com/markets) free market data API: 29 datasets from primary sources (SEC EDGAR and XBRL, FINRA, CFTC, the Federal Reserve, USAspending, exchange APIs) as clean JSON, no key needed to start.
+
+```bash
+pip install xoomar
+```
+
+```python
+from xoomar import Xoomar
+
+x = Xoomar()                          # 30 requests a minute; Xoomar(api_key="...") for 120 with a free key
+
+x.short_interest("GME")[-1]           # FINRA short interest, latest settlement
+x.short_volume("GME", days=30)        # FINRA daily short sale volume
+x.fails_to_deliver("GME")             # SEC fails to deliver
+x.insiders("NVDA")                    # SEC Form 4 trades
+x.large_holders("HIMS")               # Schedule 13D and 13G holders
+x.financials("AAPL")["quarterly"]     # XBRL income statement by quarter
+x.fund_holders("AMZN")                # which tracked 13F managers hold it
+x.cot("gold")                         # CFTC positioning history
+x.fed_liquidity()[-1]                 # net liquidity, this week
+x.funding_rates()                     # perpetual funding on three exchanges
+x.bitcoin_treasuries()                # bitcoin on public balance sheets
+x.form_d(days=7)                      # private placements filed this week
+x.federal_contracts(ticker="LMT")     # federal contract actions
+```
+
+Every method returns the `data` part of the response; `x.last_meta` holds `updatedAt`, `source`, `license` and `attribution` from the last call. `x.get("short-interest", symbol="TSLA")` calls any endpoint directly and `x.csv("short-interest/csv")` fetches a CSV download.
+
+Full endpoint reference, fields and limits: https://xoomar.com/markets/api
+
+## Datasets
+
+Short interest, daily short volume, fails to deliver, insider trades (Form 4), planned sales (Form 144), large holders (13D/13G), 13F fund holdings, company financials and buybacks (XBRL), 8-K events, structured products, federal contracts, Form D private placements, the IPO pipeline, bitcoin treasuries, CFTC COT, funding rates, open interest, liquidations, options, whale positions, sentiment, signals, ETF flows, prediction markets, Fed liquidity, macro, policy rates, economic calendar.
+
+## Rate limits and keys
+
+30 requests a minute per IP without a key. A free account at https://xoomar.com/signup gives a key for 120 a minute; pass it as `Xoomar(api_key=...)`. A 429 raises `XoomarRateLimited` with `retry_after`.
+
+## Attribution
+
+The data is free to use, including commercially. When you republish it, on a site, in an app, in an article, in a dataset or a chart, credit XOOMAR with a visible link to the dataset page on xoomar.com. Terms: https://xoomar.com/terms
+
+## License
+
+MIT, XOOMAR.

xoomar-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xoomar"
+version = "0.1.0"
+description = "Client for the XOOMAR free market data API: short interest, insider trades, COT, funding rates, Fed liquidity, SEC filings and more."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "XOOMAR", email = "info@xoomar.com" }]
+keywords = ["market data", "sec", "finra", "cot", "short interest", "insider trading", "crypto", "api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Office/Business :: Financial",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://xoomar.com/markets/api"
+Documentation = "https://xoomar.com/markets/api"
+Source = "https://github.com/xoomar-llc/xoomar-python"
+Data = "https://xoomar.com/markets"
+
+[tool.setuptools.packages.find]
+where = ["src"]

xoomar-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xoomar-0.1.0/src/xoomar/__init__.py

@@ -0,0 +1,230 @@
+"""Client for the XOOMAR free market data API (https://xoomar.com/markets/api).
+
+Every method returns the ``data`` part of the JSON response as plain Python
+objects (lists or dicts). The full envelope of the last call, with
+``updatedAt``, ``source``, ``license`` and ``attribution``, is on
+``client.last_meta``.
+
+The data is free with attribution: when you republish it, link to the
+dataset page on xoomar.com. See https://xoomar.com/terms.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+__version__ = "0.1.0"
+__all__ = ["Xoomar", "XoomarError", "XoomarRateLimited"]
+
+DEFAULT_BASE_URL = "https://xoomar.com"
+
+
+class XoomarError(Exception):
+    """An HTTP or API error. ``status`` is the HTTP status, ``body`` the response text."""
+
+    def __init__(self, status: int, body: str, url: str):
+        super().__init__(f"HTTP {status} from {url}: {body[:200]}")
+        self.status = status
+        self.body = body
+        self.url = url
+
+
+class XoomarRateLimited(XoomarError):
+    """429: 30 requests a minute without a key, 120 with a free key from https://xoomar.com/signup."""
+
+    def __init__(self, status: int, body: str, url: str, retry_after: Optional[int]):
+        super().__init__(status, body, url)
+        self.retry_after = retry_after
+
+
+class Xoomar:
+    """
+    >>> from xoomar import Xoomar
+    >>> x = Xoomar()                      # or Xoomar(api_key="...") for 120 requests a minute
+    >>> x.short_interest("GME")[-1]
+    {'settlementDate': '2026-08-14', 'symbol': 'GME', 'shortQty': 54036583, ...}
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0, user_agent: Optional[str] = None):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.user_agent = user_agent or f"xoomar-python/{__version__}"
+        self.last_meta: Dict[str, Any] = {}
+
+    # ── transport ──
+
+    def get(self, path: str, **params: Any) -> Any:
+        """GET ``/api/markets/<path>`` with query parameters; returns the ``data`` field."""
+        query = {k: v for k, v in params.items() if v is not None}
+        url = f"{self.base_url}/api/markets/{path.lstrip('/')}"
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        headers = {"Accept": "application/json", "User-Agent": self.user_agent}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        req = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                payload = json.loads(res.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body = e.read().decode("utf-8", "replace") if e.fp else ""
+            if e.code == 429:
+                ra = e.headers.get("Retry-After") if e.headers else None
+                raise XoomarRateLimited(e.code, body, url, int(ra) if ra and ra.isdigit() else None) from None
+            raise XoomarError(e.code, body, url) from None
+        if isinstance(payload, dict) and "data" in payload:
+            self.last_meta = {k: v for k, v in payload.items() if k != "data"}
+            return payload["data"]
+        self.last_meta = {}
+        return payload
+
+    def csv(self, path: str, **params: Any) -> str:
+        """The CSV download for a dataset, e.g. ``csv("short-interest/csv")``, as text."""
+        query = {k: v for k, v in params.items() if v is not None}
+        url = f"{self.base_url}/api/markets/{path.lstrip('/')}"
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        headers = {"Accept": "text/csv", "User-Agent": self.user_agent}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        req = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                return res.read().decode("utf-8")
+        except urllib.error.HTTPError as e:
+            raise XoomarError(e.code, e.read().decode("utf-8", "replace") if e.fp else "", url) from None
+
+    # ── companies (SEC and FINRA) ──
+
+    def short_interest(self, symbol: Optional[str] = None) -> Any:
+        """FINRA short interest: history for a symbol, or the latest settlement's highest days to cover."""
+        return self.get("short-interest", symbol=symbol)
+
+    def short_volume(self, symbol: Optional[str] = None, days: Optional[int] = None, sort: Optional[str] = None) -> Any:
+        """FINRA daily short sale volume: history for a symbol, or the latest day (sort="shares" for largest volumes)."""
+        return self.get("short-volume", symbol=symbol, days=days, sort=sort)
+
+    def fails_to_deliver(self, symbol: Optional[str] = None) -> Any:
+        """SEC fails to deliver: history for a symbol, or the latest settlement date's largest fails."""
+        return self.get("fails-to-deliver", symbol=symbol)
+
+    def insiders(self, ticker: Optional[str] = None, type: Optional[str] = None, window: Optional[str] = None) -> Any:
+        """SEC Form 4 trades: a ticker's history, or the latest across companies (type="buys", window="7d")."""
+        if ticker:
+            return self.get(f"insiders/{ticker.lower()}")
+        return self.get("insiders", type=type, window=window)
+
+    def planned_sales(self, symbol: Optional[str] = None, days: Optional[int] = None) -> Any:
+        """SEC Form 144 notices of proposed sale."""
+        return self.get("planned-sales", symbol=symbol, days=days)
+
+    def large_holders(self, symbol: Optional[str] = None, form: Optional[str] = None, days: Optional[int] = None, new: Optional[bool] = None, sort: Optional[str] = None) -> Any:
+        """Schedule 13D and 13G cover pages (form="13D" or "13G")."""
+        return self.get("large-holders", symbol=symbol, form=form, days=days, new=1 if new else None, sort=sort)
+
+    def financials(self, symbol: str) -> Any:
+        """XBRL quarterly income, annual statements and latest balance sheet for a ticker."""
+        return self.get("financials", symbol=symbol)
+
+    def buybacks(self) -> Any:
+        """Largest share repurchases per company in its latest fiscal year."""
+        return self.get("buybacks")
+
+    def fund_holders(self, ticker: str) -> Any:
+        """Tracked 13F managers holding a ticker at their latest filing."""
+        return self.get("funds", ticker=ticker)
+
+    def fund(self, slug: str) -> Any:
+        """One tracked manager's latest 13F portfolio (e.g. "berkshire-hathaway")."""
+        return self.get(f"funds/{slug}")
+
+    def events(self, ticker: Optional[str] = None, item: Optional[str] = None, days: Optional[int] = None) -> Any:
+        """SEC 8-K material events."""
+        return self.get("events", ticker=ticker, item=item, days=days)
+
+    def structured_products(self, **params: Any) -> Any:
+        """Bank structured notes from 424B2 and FWP filings (issuer=, underlying=, noteType=, days=, cursor=)."""
+        return self.get("structured-products", **params)
+
+    def federal_contracts(self, ticker: Optional[str] = None, days: Optional[int] = None, by: Optional[str] = None, listed: Optional[bool] = None) -> Any:
+        """Largest US federal contract actions (by="ticker" sums by listed parent)."""
+        return self.get("federal-contracts", ticker=ticker, days=days, by=by, listed=1 if listed else None)
+
+    # ── markets ──
+
+    def funding_rates(self, slug: Optional[str] = None) -> Any:
+        """Perpetual futures funding on Binance, Bybit and OKX; a symbol slug (e.g. "btc") gives its history."""
+        return self.get(f"funding-rates/{slug}") if slug else self.get("funding-rates")
+
+    def open_interest(self, slug: str) -> Any:
+        """Hourly open interest history for a symbol slug."""
+        return self.get(f"open-interest/{slug}")
+
+    def liquidations(self) -> Any:
+        """Recent crypto liquidations across exchanges."""
+        return self.get("liquidations")
+
+    def options(self, currency: str = "BTC") -> Any:
+        """Deribit options: put/call, max pain, DVOL for BTC or ETH."""
+        return self.get(f"options/{currency}")
+
+    def whales(self, coin: Optional[str] = None) -> Any:
+        """Hyperliquid whale positions, all or for one coin."""
+        return self.get(f"whales/{coin}") if coin else self.get("whales")
+
+    def cot(self, market: Optional[str] = None) -> Any:
+        """CFTC Commitments of Traders: the latest report across markets, or one market's history (e.g. "gold")."""
+        return self.get(f"cot/{market}") if market else self.get("cot")
+
+    def sentiment(self, asset: Optional[str] = None, kind: Optional[str] = None, window: Optional[str] = None) -> Any:
+        """Composite sentiment scores, all assets or one asset slug."""
+        return self.get(f"sentiment/{asset}") if asset else self.get("sentiment", kind=kind, window=window)
+
+    def signals(self, asset: Optional[str] = None) -> Any:
+        """Rules-based composite signals."""
+        return self.get(f"signals/{asset}") if asset else self.get("signals")
+
+    def etf_flows(self, asset: Optional[str] = None, days: Optional[int] = None) -> Any:
+        """Spot bitcoin and ether ETF flows."""
+        return self.get("etf-flows", asset=asset, days=days)
+
+    def bitcoin_treasuries(self) -> Any:
+        """Bitcoin held by public companies from their SEC filings."""
+        return self.get("bitcoin-treasuries")
+
+    def predictions(self, category: Optional[str] = None) -> Any:
+        """Polymarket odds."""
+        return self.get("predictions", category=category)
+
+    # ── macro ──
+
+    def macro(self, series: Optional[str] = None, from_: Optional[str] = None, to: Optional[str] = None) -> Any:
+        """US Treasury yield curve, spreads, stablecoin supply (series=, from=, to=)."""
+        return self.get("macro", series=series, **{"from": from_, "to": to})
+
+    def fed_liquidity(self, series: Optional[str] = None, limit: Optional[int] = None) -> Any:
+        """Weekly net liquidity with components, or one FRED series (WALCL, WRESBAL, RRPONTSYD, WTREGEN, SOFR, EFFR, IORB, WSHOSHO)."""
+        return self.get("fed-liquidity", series=series, limit=limit)
+
+    def rates(self, country: Optional[str] = None) -> Any:
+        """Central bank policy rates: all economies, or one country code's history (e.g. "us")."""
+        return self.get(f"rates/{country}") if country else self.get("rates")
+
+    def calendar(self, from_: Optional[str] = None, to: Optional[str] = None, importance: Optional[str] = None) -> Any:
+        """US economic calendar with consensus and actuals."""
+        return self.get("calendar", importance=importance, **{"from": from_, "to": to})
+
+    # ── filings and offerings ──
+
+    def form_d(self, days: Optional[int] = None, funds: Optional[bool] = None, cik: Optional[str] = None, sort: Optional[str] = None, amendments: Optional[bool] = None) -> Any:
+        """SEC Form D private placements: largest raises in a window, one issuer by CIK, or sort="recent"."""
+        return self.get("startup-funding", days=days, funds=1 if funds else None, cik=cik, sort=sort, amendments=1 if amendments else None)
+
+    def ipos(self, form: Optional[str] = None, days: Optional[int] = None, new: Optional[bool] = None) -> Any:
+        """IPO pipeline filings (form="S-1,F-1", "424B4", "RW", "EFFECT"; new=True for filers not yet listed)."""
+        return self.get("ipos", form=form, days=days, new=1 if new else None)

xoomar-0.1.0/src/xoomar.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: xoomar
+Version: 0.1.0
+Summary: Client for the XOOMAR free market data API: short interest, insider trades, COT, funding rates, Fed liquidity, SEC filings and more.
+Author-email: XOOMAR <info@xoomar.com>
+License: MIT
+Project-URL: Homepage, https://xoomar.com/markets/api
+Project-URL: Documentation, https://xoomar.com/markets/api
+Project-URL: Source, https://github.com/xoomar-llc/xoomar-python
+Project-URL: Data, https://xoomar.com/markets
+Keywords: market data,sec,finra,cot,short interest,insider trading,crypto,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# xoomar
+
+Python client for the [XOOMAR](https://xoomar.com/markets) free market data API: 29 datasets from primary sources (SEC EDGAR and XBRL, FINRA, CFTC, the Federal Reserve, USAspending, exchange APIs) as clean JSON, no key needed to start.
+
+```bash
+pip install xoomar
+```
+
+```python
+from xoomar import Xoomar
+
+x = Xoomar()                          # 30 requests a minute; Xoomar(api_key="...") for 120 with a free key
+
+x.short_interest("GME")[-1]           # FINRA short interest, latest settlement
+x.short_volume("GME", days=30)        # FINRA daily short sale volume
+x.fails_to_deliver("GME")             # SEC fails to deliver
+x.insiders("NVDA")                    # SEC Form 4 trades
+x.large_holders("HIMS")               # Schedule 13D and 13G holders
+x.financials("AAPL")["quarterly"]     # XBRL income statement by quarter
+x.fund_holders("AMZN")                # which tracked 13F managers hold it
+x.cot("gold")                         # CFTC positioning history
+x.fed_liquidity()[-1]                 # net liquidity, this week
+x.funding_rates()                     # perpetual funding on three exchanges
+x.bitcoin_treasuries()                # bitcoin on public balance sheets
+x.form_d(days=7)                      # private placements filed this week
+x.federal_contracts(ticker="LMT")     # federal contract actions
+```
+
+Every method returns the `data` part of the response; `x.last_meta` holds `updatedAt`, `source`, `license` and `attribution` from the last call. `x.get("short-interest", symbol="TSLA")` calls any endpoint directly and `x.csv("short-interest/csv")` fetches a CSV download.
+
+Full endpoint reference, fields and limits: https://xoomar.com/markets/api
+
+## Datasets
+
+Short interest, daily short volume, fails to deliver, insider trades (Form 4), planned sales (Form 144), large holders (13D/13G), 13F fund holdings, company financials and buybacks (XBRL), 8-K events, structured products, federal contracts, Form D private placements, the IPO pipeline, bitcoin treasuries, CFTC COT, funding rates, open interest, liquidations, options, whale positions, sentiment, signals, ETF flows, prediction markets, Fed liquidity, macro, policy rates, economic calendar.
+
+## Rate limits and keys
+
+30 requests a minute per IP without a key. A free account at https://xoomar.com/signup gives a key for 120 a minute; pass it as `Xoomar(api_key=...)`. A 429 raises `XoomarRateLimited` with `retry_after`.
+
+## Attribution
+
+The data is free to use, including commercially. When you republish it, on a site, in an app, in an article, in a dataset or a chart, credit XOOMAR with a visible link to the dataset page on xoomar.com. Terms: https://xoomar.com/terms
+
+## License
+
+MIT, XOOMAR.

xoomar-0.1.0/src/xoomar.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/xoomar/__init__.py
+src/xoomar.egg-info/PKG-INFO
+src/xoomar.egg-info/SOURCES.txt
+src/xoomar.egg-info/dependency_links.txt
+src/xoomar.egg-info/top_level.txt
+tests/test_client.py

xoomar-0.1.0/src/xoomar.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xoomar-0.1.0/src/xoomar.egg-info/top_level.txt

@@ -0,0 +1 @@
+xoomar

xoomar-0.1.0/tests/test_client.py

@@ -0,0 +1,47 @@
+import io
+import json
+import unittest
+from unittest import mock
+
+from xoomar import Xoomar, XoomarRateLimited
+
+
+class FakeResponse(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+class ClientTests(unittest.TestCase):
+    def test_get_returns_data_and_keeps_meta(self):
+        payload = {"data": [{"symbol": "GME"}], "updatedAt": "2026-09-13T00:00:00Z", "source": "xoomar.com", "attribution": "Free with attribution"}
+        with mock.patch("urllib.request.urlopen", return_value=FakeResponse(json.dumps(payload).encode())) as u:
+            x = Xoomar(api_key="k")
+            rows = x.short_interest("GME")
+            self.assertEqual(rows, [{"symbol": "GME"}])
+            self.assertEqual(x.last_meta["source"], "xoomar.com")
+            req = u.call_args[0][0]
+            self.assertEqual(req.full_url, "https://xoomar.com/api/markets/short-interest?symbol=GME")
+            self.assertEqual(req.get_header("X-api-key"), "k")
+
+    def test_path_methods(self):
+        with mock.patch("urllib.request.urlopen", return_value=FakeResponse(b'{"data": []}')) as u:
+            Xoomar().insiders("nvda")
+            self.assertEqual(u.call_args[0][0].full_url, "https://xoomar.com/api/markets/insiders/nvda")
+        with mock.patch("urllib.request.urlopen", return_value=FakeResponse(b'{"data": []}')) as u:
+            Xoomar().large_holders("HIMS", form="13D", new=True)
+            self.assertEqual(u.call_args[0][0].full_url, "https://xoomar.com/api/markets/large-holders?symbol=HIMS&form=13D&new=1")
+
+    def test_rate_limit(self):
+        import urllib.error
+        err = urllib.error.HTTPError("https://xoomar.com/api/markets/cot", 429, "Too Many Requests", {"Retry-After": "12"}, io.BytesIO(b"slow down"))
+        with mock.patch("urllib.request.urlopen", side_effect=err):
+            with self.assertRaises(XoomarRateLimited) as ctx:
+                Xoomar().cot()
+            self.assertEqual(ctx.exception.retry_after, 12)
+
+
+if __name__ == "__main__":
+    unittest.main()