vextorium 0.1.0__tar.gz

vextorium-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+dist/
+*.egg-info/
+.env

vextorium-0.1.0/LICENSE

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

vextorium-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: vextorium
+Version: 0.1.0
+Summary: 550+ pay-per-call data services for trading bots and AI agents, paid automatically in USDC on Base via x402. No API keys.
+Project-URL: Homepage, https://vextorium.com
+Project-URL: Catalog, https://api.vextorium.com/catalog.json
+Project-URL: Source, https://github.com/bru1noia/vextorium-python
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,base,crypto,freqtrade,funding-rate,liquidations,trading,usdc,x402
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.10
+Requires-Dist: requests>=2.28
+Requires-Dist: x402[evm]>=2.25
+Provides-Extra: freqtrade
+Requires-Dist: pandas; extra == 'freqtrade'
+Description-Content-Type: text/markdown
+
+# vextorium (Python)
+
+550+ pay-per-call data services for trading bots and AI agents: perp funding, liquidation maps, Hyperliquid
+markets and whales, market regime, prices, on-chain data on 30+ chains, DeFi, official statistics and more.
+
+**No API keys, no sign-up.** A Base wallet with a little USDC is the account; each call is paid automatically
+via [x402](https://x402.org) (typically $0.003–$0.01). Failed calls are not charged.
+
+```bash
+pip install "vextorium @ git+https://github.com/bru1noia/vextorium-python"
+```
+
+```python
+from vextorium import Vextorium
+
+vx = Vextorium(private_key="0x...", budget_usd=1.0, max_price_usd=0.02)  # use a separate small wallet
+vx.call("perp-funding", currency="BTC")        # funding, premium, open interest
+vx.call("hyperliquid-liquidation-map", currency="ETH", brackets=10)
+vx.call("market-regime")                       # risk-on / risk-off score
+vx.services("funding")                         # free: search the catalog
+print(vx.spent / 1e6, "USDC spent")
+```
+
+Safety: every call is capped by `max_price_usd`, the session by `budget_usd` (`BudgetExceeded` is raised
+before paying), payments only go out on Base USDC, and one payment runs at a time per wallet.
+
+## freqtrade
+
+Add funding, nearest liquidations and market regime as columns (latest candle only, no look-ahead), cached so
+a bot calls each service at most once per `refresh_minutes`:
+
+```python
+from vextorium.freqtrade import VextoriumContext
+
+class MyStrategy(IStrategy):
+    vx = VextoriumContext(budget_usd=2.0, refresh_minutes=60)   # key from VEXTORIUM_KEY
+
+    def populate_indicators(self, dataframe, metadata):
+        dataframe = self.vx.add_columns(dataframe, metadata["pair"])
+        # vx_funding_annual_pct, vx_premium_pct, vx_open_interest_usd, vx_nearest_long_liq_pct,
+        # vx_nearest_short_liq_pct, vx_long_at_risk_usd, vx_short_at_risk_usd, vx_regime_score
+        return dataframe
+```
+
+Cost example: 1 pair, refresh 60 min, 3 signals ≈ 24 × 0.019 = 0.46 USDC/day.
+
+Full catalog: https://api.vextorium.com/catalog.json · OpenAPI: https://api.vextorium.com/openapi.json ·
+MCP server: https://github.com/bru1noia/vextorium-mcp
+
+License: MIT

vextorium-0.1.0/README.md

@@ -0,0 +1,50 @@
+# vextorium (Python)
+
+550+ pay-per-call data services for trading bots and AI agents: perp funding, liquidation maps, Hyperliquid
+markets and whales, market regime, prices, on-chain data on 30+ chains, DeFi, official statistics and more.
+
+**No API keys, no sign-up.** A Base wallet with a little USDC is the account; each call is paid automatically
+via [x402](https://x402.org) (typically $0.003–$0.01). Failed calls are not charged.
+
+```bash
+pip install "vextorium @ git+https://github.com/bru1noia/vextorium-python"
+```
+
+```python
+from vextorium import Vextorium
+
+vx = Vextorium(private_key="0x...", budget_usd=1.0, max_price_usd=0.02)  # use a separate small wallet
+vx.call("perp-funding", currency="BTC")        # funding, premium, open interest
+vx.call("hyperliquid-liquidation-map", currency="ETH", brackets=10)
+vx.call("market-regime")                       # risk-on / risk-off score
+vx.services("funding")                         # free: search the catalog
+print(vx.spent / 1e6, "USDC spent")
+```
+
+Safety: every call is capped by `max_price_usd`, the session by `budget_usd` (`BudgetExceeded` is raised
+before paying), payments only go out on Base USDC, and one payment runs at a time per wallet.
+
+## freqtrade
+
+Add funding, nearest liquidations and market regime as columns (latest candle only, no look-ahead), cached so
+a bot calls each service at most once per `refresh_minutes`:
+
+```python
+from vextorium.freqtrade import VextoriumContext
+
+class MyStrategy(IStrategy):
+    vx = VextoriumContext(budget_usd=2.0, refresh_minutes=60)   # key from VEXTORIUM_KEY
+
+    def populate_indicators(self, dataframe, metadata):
+        dataframe = self.vx.add_columns(dataframe, metadata["pair"])
+        # vx_funding_annual_pct, vx_premium_pct, vx_open_interest_usd, vx_nearest_long_liq_pct,
+        # vx_nearest_short_liq_pct, vx_long_at_risk_usd, vx_short_at_risk_usd, vx_regime_score
+        return dataframe
+```
+
+Cost example: 1 pair, refresh 60 min, 3 signals ≈ 24 × 0.019 = 0.46 USDC/day.
+
+Full catalog: https://api.vextorium.com/catalog.json · OpenAPI: https://api.vextorium.com/openapi.json ·
+MCP server: https://github.com/bru1noia/vextorium-mcp
+
+License: MIT

vextorium-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vextorium"
+version = "0.1.0"
+description = "550+ pay-per-call data services for trading bots and AI agents, paid automatically in USDC on Base via x402. No API keys."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["x402[evm]>=2.25", "requests>=2.28", "eth-account>=0.10"]
+keywords = ["x402", "usdc", "base", "trading", "freqtrade", "crypto", "funding-rate", "liquidations", "ai-agents"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Office/Business :: Financial :: Investment"]
+
+[project.optional-dependencies]
+freqtrade = ["pandas"]
+
+[project.urls]
+Homepage = "https://vextorium.com"
+Catalog = "https://api.vextorium.com/catalog.json"
+Source = "https://github.com/bru1noia/vextorium-python"

vextorium-0.1.0/vextorium/__init__.py

@@ -0,0 +1,103 @@
+"""Vextorium: 550+ pay-per-call data services for bots and AI agents, paid automatically in USDC on Base (x402).
+
+No API keys, no sign-up: a Base wallet with a little USDC is the account. Every call is capped (max_price) and
+there is a spend limit per session (budget), so a bot left running can never spend more than you allow.
+
+    from vextorium import Vextorium
+    vx = Vextorium(private_key=os.environ["VEXTORIUM_KEY"], budget_usd=1.0)
+    vx.call("perp-funding", symbol="BTC")
+    vx.services(query="funding")          # free: search the catalog
+"""
+from __future__ import annotations
+
+import os
+import threading
+
+import requests
+
+__version__ = "0.1.0"
+__all__ = ["Vextorium", "VextoriumError", "BudgetExceeded"]
+
+API = "https://api.vextorium.com"
+BASE = "eip155:8453"
+USDC_BASE = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
+
+
+class VextoriumError(Exception):
+    """The service answered with an error (failed calls are not charged)."""
+
+
+class BudgetExceeded(VextoriumError):
+    """The call would go over the spend limit you set."""
+
+
+class Vextorium:
+    def __init__(self, private_key: str | None = None, budget_usd: float = 1.0, max_price_usd: float = 0.02,
+                 api: str = API, timeout: float = 60):
+        from eth_account import Account
+        from x402 import x402ClientSync
+        from x402.client_base import max_amount, prefer_network
+        from x402.http.clients import x402_requests
+        from x402.mechanisms.evm.exact import register_exact_evm_client
+        from x402.mechanisms.evm.signers import EthAccountSigner
+
+        key = private_key or os.environ.get("VEXTORIUM_KEY")
+        if not key:
+            raise ValueError("private_key (or VEXTORIUM_KEY): a Base wallet with USDC; use a separate small wallet")
+        self.account = Account.from_key(key)
+        self.api, self.timeout = api.rstrip("/"), timeout
+        self.budget = int(round(budget_usd * 1e6))
+        self.max_price = int(round(max_price_usd * 1e6))
+        self.spent = 0  # USDC atomic units actually charged in this session
+        self._lock = threading.Lock()
+        client = x402ClientSync()
+        register_exact_evm_client(client, EthAccountSigner(self.account), networks=[BASE],
+                                  policies=[prefer_network(BASE), max_amount(self.max_price)])
+        self._pay = x402_requests(client)
+        self._free = requests.Session()
+
+    # -- free -----------------------------------------------------------------
+    def services(self, query: str | None = None) -> list[dict]:
+        """Catalog (free). Optional text filter on path/description."""
+        items = self._free.get(f"{self.api}/catalog.json", timeout=self.timeout).json()["services"]
+        if query:
+            q = query.lower()
+            items = [s for s in items if q in (str(s.get("endpoint", "")) + str(s.get("description", "")) + " ".join(s.get("tags") or [])).lower()]
+        return items
+
+    # -- paid -----------------------------------------------------------------
+    def call(self, service: str, **params):
+        """Call one service, e.g. call("crypto-price", symbol="ETH"). Pays the listed price (≤ max_price)."""
+        path = service if service.startswith("/") else "/v1/" + service
+        with self._lock:  # one payment at a time per wallet (nonces) and an exact budget
+            probe = self._free.post(self.api + path, json=params, timeout=self.timeout)
+            if probe.status_code != 402:
+                return self._result(probe)
+            price = self._price(probe)
+            if price is None:
+                raise VextoriumError(f"{path}: no USDC-on-Base offer within max_price")
+            if self.spent + price > self.budget:
+                raise BudgetExceeded(f"{path} costs {price / 1e6} USDC; spent {self.spent / 1e6} of {self.budget / 1e6}")
+            r = self._pay.post(self.api + path, json=params, timeout=self.timeout)
+            if r.ok and (r.headers.get("PAYMENT-RESPONSE") or r.headers.get("X-PAYMENT-RESPONSE")):
+                self.spent += price
+            return self._result(r)
+
+    def _price(self, r) -> int | None:
+        try:
+            offers = r.json().get("accepts") or []
+        except ValueError:
+            return None
+        ok = [int(o["amount"]) for o in offers if o.get("network") == BASE and str(o.get("asset", "")).lower() == USDC_BASE
+              and int(o.get("amount", 0)) <= self.max_price]
+        return min(ok) if ok else None
+
+    @staticmethod
+    def _result(r):
+        try:
+            data = r.json()
+        except ValueError:
+            data = r.text
+        if not r.ok:
+            raise VextoriumError(f"HTTP {r.status_code}: {str(data)[:300]}")
+        return data

vextorium-0.1.0/vextorium/freqtrade.py

@@ -0,0 +1,67 @@
+"""freqtrade helper: add Vextorium market context (funding, liquidations, market regime) to a strategy.
+
+Calls are cached per candle, so a 5m bot on 1 pair makes at most 1 call per signal per candle
+(e.g. funding: 288 calls/day x 0.009 = 2.6 USDC/day). Use refresh_minutes to call less often.
+
+    from vextorium.freqtrade import VextoriumContext
+    class MyStrategy(IStrategy):
+        vx = VextoriumContext(budget_usd=2.0, refresh_minutes=60)
+        def populate_indicators(self, dataframe, metadata):
+            return self.vx.add_columns(dataframe, metadata["pair"])
+"""
+from __future__ import annotations
+
+import logging
+import time
+
+from . import Vextorium, VextoriumError
+
+log = logging.getLogger(__name__)
+
+
+class VextoriumContext:
+    def __init__(self, private_key: str | None = None, budget_usd: float = 1.0, refresh_minutes: float = 60,
+                 signals=("funding", "liquidations", "regime"), client: Vextorium | None = None):
+        self.vx = client or Vextorium(private_key=private_key, budget_usd=budget_usd)
+        self.refresh = refresh_minutes * 60
+        self.signals = set(signals)
+        self._cache: dict[tuple, tuple[float, dict]] = {}
+
+    def _get(self, service: str, **params) -> dict | None:
+        key = (service, tuple(sorted(params.items())))
+        hit = self._cache.get(key)
+        if hit and time.time() - hit[0] < self.refresh:
+            return hit[1]
+        try:
+            data = self.vx.call(service, **params)
+        except VextoriumError as e:  # failed calls are not charged; the bot keeps running without the column
+            log.warning("vextorium %s: %s", service, e)
+            return hit[1] if hit else None
+        self._cache[key] = (time.time(), data)
+        return data
+
+    def context(self, pair: str) -> dict:
+        """Latest values for a pair like 'BTC/USDT' or 'BTC/USDT:USDT'."""
+        coin = pair.split("/")[0].upper()
+        out: dict = {}
+        if "funding" in self.signals and (f := self._get("perp-funding", currency=coin)):
+            out["vx_funding_annual_pct"] = f.get("annual_funding_pct")
+            out["vx_premium_pct"] = f.get("premium_pct")
+            out["vx_open_interest_usd"] = f.get("open_interest_usd")
+        if "liquidations" in self.signals and (m := self._get("hyperliquid-liquidation-map", currency=coin, brackets=10)):
+            out["vx_nearest_long_liq_pct"] = ((m.get("nearest_long_liquidations") or [{}])[0]).get("distance_pct")
+            out["vx_nearest_short_liq_pct"] = ((m.get("nearest_short_liquidations") or [{}])[0]).get("distance_pct")
+            out["vx_long_at_risk_usd"] = m.get("long_notional_at_risk_usd")
+            out["vx_short_at_risk_usd"] = m.get("short_notional_at_risk_usd")
+        if "regime" in self.signals and (r := self._get("market-regime")):
+            out["vx_regime_score"] = r.get("score")
+        return out
+
+    def add_columns(self, dataframe, pair: str):
+        """Writes the latest values on the last row (live/dry-run); past rows stay NaN (no look-ahead)."""
+        for col, val in self.context(pair).items():
+            if col not in dataframe:
+                dataframe[col] = float("nan")
+            if val is not None and len(dataframe):
+                dataframe.loc[dataframe.index[-1], col] = val
+        return dataframe