apexrunner-tools 0.1.0__py3-none-any.whl

apexrunner_tools/__init__.py

@@ -0,0 +1,31 @@
+"""APEX Runner pre-trade crypto signals for LangChain and CrewAI agents, paid per call over x402.
+
+Framework adapters live in ``apexrunner_tools.langchain`` and ``apexrunner_tools.crewai``
+so that importing the core never requires either framework.
+"""
+
+from .client import ApexClient, ApexResult
+from .constants import __version__
+from .errors import (
+    ApexError,
+    ApexResponseError,
+    ApexUnavailable,
+    BudgetExceeded,
+    PaymentRefused,
+    PaymentRejected,
+)
+from .signals import SIGNALS, SignalSpec
+
+__all__ = [
+    "ApexClient",
+    "ApexResult",
+    "ApexError",
+    "ApexResponseError",
+    "ApexUnavailable",
+    "BudgetExceeded",
+    "PaymentRefused",
+    "PaymentRejected",
+    "SIGNALS",
+    "SignalSpec",
+    "__version__",
+]

apexrunner_tools/client.py

@@ -0,0 +1,297 @@
+"""ApexClient: one paid call per signal, with caching, budget and error mapping."""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from dataclasses import dataclass, field, replace
+from typing import Any, Callable
+
+import requests
+from x402.http import decode_payment_required_header, decode_payment_response_header
+from x402.http.clients import wrapRequestsWithPayment, x402HttpxClient
+
+from .constants import (
+    APEX_BASE_URL,
+    DEFAULT_BUDGET_USDC,
+    DEFAULT_MAX_PAYMENT_USDC,
+    MAX_ALLOWED_PAYMENT_USDC,
+    MAX_CACHE_SECONDS,
+    MAX_CONTENT_CHARS,
+    REQUEST_TIMEOUT_S,
+    USER_AGENT,
+)
+from .errors import ApexResponseError, ApexUnavailable, PaymentRejected
+from .payment import (
+    SpendBudget,
+    build_async_client,
+    build_sync_client,
+    call_ledger,
+    from_atomic,
+    map_payment_exception,
+    resolve_signer,
+    to_atomic,
+)
+from .signals import SignalSpec, get_spec
+
+
+@dataclass(frozen=True)
+class ApexResult:
+    signal: str
+    data: dict[str, Any]
+    cached: bool = False
+    #: USDC signed for this call (0.0 when served from cache).
+    amount_usdc: float = 0.0
+    transaction: str | None = None
+    payer: str | None = None
+    network: str | None = None
+    query: dict[str, str] = field(default_factory=dict)
+
+    def payment(self) -> dict[str, Any]:
+        return {
+            "amount_usdc": self.amount_usdc,
+            "transaction": self.transaction,
+            "network": self.network,
+            "cached": self.cached,
+        }
+
+    def to_content(self, max_chars: int = MAX_CONTENT_CHARS) -> str:
+        """Compact JSON for the model."""
+        out = json.dumps(
+            {"signal": self.signal, "data": self.data, "payment": self.payment()},
+            separators=(",", ":"),
+            default=str,
+        )
+        return out if len(out) <= max_chars else out[:max_chars] + "...[truncated]"
+
+    def to_artifact(self) -> dict[str, Any]:
+        """Full result for the application (not sent to the model)."""
+        return {
+            "signal": self.signal,
+            "query": self.query,
+            "data": self.data,
+            "payment": {**self.payment(), "payer": self.payer},
+        }
+
+
+class _TTLCache:
+    def __init__(self, clock: Callable[[], float]):
+        self._clock = clock
+        self._items: dict[tuple, tuple[float, ApexResult]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: tuple) -> ApexResult | None:
+        with self._lock:
+            hit = self._items.get(key)
+            if hit is None:
+                return None
+            if hit[0] <= self._clock():
+                del self._items[key]
+                return None
+            return hit[1]
+
+    def put(self, key: tuple, result: ApexResult, ttl: float) -> None:
+        if ttl <= 0:
+            return
+        with self._lock:
+            self._items[key] = (self._clock() + ttl, result)
+
+
+def _ttl_for(data: dict[str, Any]) -> float:
+    """Cache for as long as the response says it is valid, minus its age, capped."""
+    valid = data.get("valid_for_seconds")
+    if not isinstance(valid, (int, float)) or isinstance(valid, bool) or valid <= 0:
+        return 0.0
+    age = data.get("data_age_seconds", 0)
+    if not isinstance(age, (int, float)) or isinstance(age, bool) or age < 0:
+        age = 0
+    if data.get("stale") is True:
+        return 0.0
+    return float(min(valid - age, MAX_CACHE_SECONDS))
+
+
+class ApexClient:
+    """Pays for and fetches APEX Runner signals.
+
+    Supply the wallet as exactly one of ``private_key``, ``account`` (an
+    eth_account LocalAccount) or ``signer`` (any object with ``address`` and
+    ``sign_typed_data``). The wallet needs USDC on Base mainnet; no ETH is
+    needed, because payments are signed authorizations settled by the facilitator.
+    """
+
+    def __init__(
+        self,
+        *,
+        private_key: str | None = None,
+        account: Any = None,
+        signer: Any = None,
+        max_payment_usdc: float = DEFAULT_MAX_PAYMENT_USDC,
+        budget_usdc: float = DEFAULT_BUDGET_USDC,
+        cache: bool = True,
+        timeout: float = REQUEST_TIMEOUT_S,
+        base_url: str = APEX_BASE_URL,
+        _clock: Callable[[], float] = time.monotonic,
+    ):
+        if not (0 < max_payment_usdc <= MAX_ALLOWED_PAYMENT_USDC):
+            raise ValueError(f"max_payment_usdc must be in (0, {MAX_ALLOWED_PAYMENT_USDC}]")
+        self._signer = resolve_signer(private_key, account, signer)
+        self.address: str = self._signer.address
+        self.budget = SpendBudget(budget_usdc)
+        self._max_atomic = to_atomic(max_payment_usdc)
+        self._timeout = timeout
+        self._base_url = base_url.rstrip("/")
+        self._cache = _TTLCache(_clock) if cache else None
+        self._session = wrapRequestsWithPayment(
+            requests.Session(), build_sync_client(self._signer, self.budget, self._max_atomic)
+        )
+        self._session.headers["User-Agent"] = USER_AGENT
+        self._session.headers["Accept"] = "application/json"
+        self._async_x402 = build_async_client(self._signer, self.budget, self._max_atomic)
+
+    # ── public API ─────────────────────────────────────────────────────────────
+
+    def call(self, signal: str, **params: Any) -> ApexResult:
+        spec, query, key = self._prepare(signal, params)
+        hit = self._cached(key)
+        if hit is not None:
+            return hit
+        ledger: list[int] = []
+        token = call_ledger.set(ledger)
+        try:
+            resp = self._session.get(self._url(spec), params=query, timeout=self._timeout)
+        except Exception as exc:  # noqa: BLE001 - mapped to ApexError below
+            raise map_payment_exception(exc, self.budget) from exc
+        finally:
+            call_ledger.reset(token)
+        return self._finish(spec, query, key, resp.status_code, resp.headers, resp.content, ledger)
+
+    async def acall(self, signal: str, **params: Any) -> ApexResult:
+        spec, query, key = self._prepare(signal, params)
+        hit = self._cached(key)
+        if hit is not None:
+            return hit
+        ledger: list[int] = []
+        token = call_ledger.set(ledger)
+        try:
+            # A fresh AsyncClient per call: httpx clients are bound to an event loop,
+            # and agent frameworks do not guarantee the same loop between calls.
+            async with x402HttpxClient(
+                self._async_x402,
+                timeout=self._timeout,
+                headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+            ) as http:
+                resp = await http.get(self._url(spec), params=query)
+                content = resp.content
+        except Exception as exc:  # noqa: BLE001
+            raise map_payment_exception(exc, self.budget) from exc
+        finally:
+            call_ledger.reset(token)
+        return self._finish(spec, query, key, resp.status_code, resp.headers, content, ledger)
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "ApexClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ── internals ──────────────────────────────────────────────────────────────
+
+    def _url(self, spec: SignalSpec) -> str:
+        return f"{self._base_url}/{spec.slug}"
+
+    def _prepare(self, signal: str, params: dict[str, Any]):
+        spec = get_spec(signal)
+        args = spec.input_model(**params)
+        query = spec.to_query(args)
+        return spec, query, (spec.slug, tuple(sorted(query.items())))
+
+    def _cached(self, key: tuple) -> ApexResult | None:
+        if self._cache is None:
+            return None
+        hit = self._cache.get(key)
+        return None if hit is None else replace(hit, cached=True, amount_usdc=0.0)
+
+    def _finish(
+        self,
+        spec: SignalSpec,
+        query: dict[str, str],
+        key: tuple,
+        status: int,
+        headers: Any,
+        content: bytes,
+        ledger: list[int],
+    ) -> ApexResult:
+        signed = from_atomic(sum(ledger))
+        if status == 402:
+            reason = _payment_error_reason(headers)
+            raise PaymentRejected(
+                f"Payment was rejected{f' ({reason})' if reason else ''}. Check that wallet "
+                f"{self.address} holds USDC on Base mainnet (about $0.01 per call)."
+            )
+        if not 200 <= status < 300:
+            body = content[:300].decode("utf-8", "replace")
+            raise ApexUnavailable(
+                f"APEX Runner returned HTTP {status} for {spec.name}; x402 settles only on "
+                f"success, so this call should not be charged. Body: {body}",
+                status_code=status,
+            )
+        try:
+            data = json.loads(content)
+        except ValueError:
+            raise ApexResponseError(f"APEX Runner returned a non-JSON body for {spec.name}.") from None
+        if not isinstance(data, dict):
+            raise ApexResponseError(f"APEX Runner returned a non-object JSON body for {spec.name}.")
+
+        receipt = _settle_receipt(headers)
+        result = ApexResult(
+            signal=spec.name,
+            data=data,
+            amount_usdc=signed,
+            transaction=receipt.get("transaction"),
+            payer=receipt.get("payer"),
+            network=receipt.get("network"),
+            query=query,
+        )
+        if self._cache is not None:
+            self._cache.put(key, result, _ttl_for(data))
+        return result
+
+
+def _header(headers: Any, *names: str) -> str | None:
+    for name in names:
+        value = headers.get(name)
+        if value:
+            return value
+    return None
+
+
+def _settle_receipt(headers: Any) -> dict[str, Any]:
+    raw = _header(headers, "PAYMENT-RESPONSE", "X-PAYMENT-RESPONSE")
+    if not raw:
+        return {}
+    try:
+        settle = decode_payment_response_header(raw)
+        return {
+            "transaction": getattr(settle, "transaction", None),
+            "payer": getattr(settle, "payer", None),
+            "network": getattr(settle, "network", None),
+        }
+    except Exception:  # noqa: BLE001 - a receipt we cannot read is not a failed call
+        return {}
+
+
+def _payment_error_reason(headers: Any) -> str | None:
+    raw = _header(headers, "PAYMENT-REQUIRED")
+    if not raw:
+        return None
+    try:
+        return getattr(decode_payment_required_header(raw), "error", None)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+__all__ = ["ApexClient", "ApexResult"]

apexrunner_tools/constants.py

@@ -0,0 +1,34 @@
+"""Pinned values. The payment policy refuses any payment request that differs."""
+
+__version__ = "0.1.0"
+
+APEX_BASE_URL = "https://apexrunner.ai/signals"
+
+# Base mainnet, CAIP-2. APEX is paid here only.
+BASE_MAINNET = "eip155:8453"
+
+# Native USDC on Base (6 decimals).
+BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+USDC_DECIMALS = 6
+
+# APEX Runner's receiving address, as served in every 402 challenge.
+APEX_PAY_TO = "0x8D0663BBb967ebF1c047405A888DDf865f3E8854"
+
+# Per-call ceiling. List price today is $0.01 (charged $0.007 until 2027-01-01).
+DEFAULT_MAX_PAYMENT_USDC = 0.02
+# Hard ceiling for any configured per-call cap: a typo must not authorise $10 calls.
+MAX_ALLOWED_PAYMENT_USDC = 1.00
+
+# Total the client may sign for over its lifetime.
+DEFAULT_BUDGET_USDC = 1.00
+
+REQUEST_TIMEOUT_S = 20.0
+
+# Never serve a cached result older than this, whatever the response claims.
+MAX_CACHE_SECONDS = 300
+
+# Keeps one signal payload from flooding the model's context window.
+MAX_CONTENT_CHARS = 16_000
+
+# Distinct UA so APEX can attribute traffic from this package.
+USER_AGENT = f"apexrunner-tools/{__version__} (python; +https://apexrunner.ai)"

apexrunner_tools/crewai.py

@@ -0,0 +1,75 @@
+"""CrewAI tools. Requires ``pip install apexrunner-tools[crewai]``.
+
+    from apexrunner_tools.crewai import get_apex_tools
+    analyst = Agent(role="...", goal="...", backstory="...",
+                    tools=get_apex_tools(private_key=os.environ["AGENT_WALLET_KEY"]))
+
+CrewAI's own tool cache is switched off for these tools: it has no expiry, so
+it would keep serving market data long after it went stale. ApexClient caches
+each result only for as long as the response says it is valid.
+
+Failures are returned as JSON with ``success: false`` and the reason, so the
+agent can read them instead of the crew crashing.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+try:
+    from crewai.tools import BaseTool
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("Install the CrewAI extra: pip install 'apexrunner-tools[crewai]'") from exc
+
+from pydantic import ConfigDict, Field
+
+from .client import ApexClient
+from .errors import ApexError
+from .signals import SIGNALS
+
+
+def _never_cache(_args: Any = None, _result: Any = None) -> bool:
+    return False
+
+
+class ApexCrewTool(BaseTool):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: ApexClient = Field(exclude=True)
+    signal: str
+    cache_function: Any = _never_cache
+
+    def _run(self, **kwargs: Any) -> str:
+        try:
+            return self.client.call(self.signal, **kwargs).to_content()
+        except ApexError as exc:
+            return _failure(self.signal, exc)
+
+    async def _arun(self, **kwargs: Any) -> str:
+        try:
+            return (await self.client.acall(self.signal, **kwargs)).to_content()
+        except ApexError as exc:
+            return _failure(self.signal, exc)
+
+
+def _failure(signal: str, exc: ApexError) -> str:
+    return json.dumps({"success": False, "signal": signal, "error": str(exc)})
+
+
+def get_apex_tools(client: ApexClient | None = None, **client_kwargs: Any) -> list[ApexCrewTool]:
+    """The three APEX tools sharing one client (one wallet, one budget, one cache)."""
+    if client is None:
+        client = ApexClient(**client_kwargs)
+    elif client_kwargs:
+        raise ValueError("Pass either client or client arguments, not both.")
+    return [
+        ApexCrewTool(
+            name=spec.name,
+            description=spec.description,
+            args_schema=spec.input_model,
+            client=client,
+            signal=spec.name,
+        )
+        for spec in SIGNALS
+    ]

apexrunner_tools/errors.py

@@ -0,0 +1,31 @@
+"""Every failure the client raises. All subclass ApexError."""
+
+
+class ApexError(Exception):
+    """Base class for apexrunner-tools errors."""
+
+
+class PaymentRefused(ApexError):
+    """No payment option passed the local policy. Nothing was signed."""
+
+
+class BudgetExceeded(PaymentRefused):
+    """Signing this payment would exceed the client's spend budget. Nothing was signed."""
+
+
+class PaymentRejected(ApexError):
+    """A payment was signed but the server or facilitator refused it.
+
+    Usually the wallet holds too little USDC on Base."""
+
+
+class ApexUnavailable(ApexError):
+    """APEX answered with a non-success status. x402 settles only on success."""
+
+    def __init__(self, message: str, status_code: int):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ApexResponseError(ApexError):
+    """APEX returned a success status with a body that is not a JSON object."""

apexrunner_tools/langchain.py

@@ -0,0 +1,71 @@
+"""LangChain tools. Requires ``pip install apexrunner-tools[langchain]``.
+
+    from apexrunner_tools.langchain import get_apex_tools
+    tools = get_apex_tools(private_key=os.environ["AGENT_WALLET_KEY"])
+    agent = create_agent(model, tools=tools)
+
+Each tool returns ``content_and_artifact``: the model sees compact JSON, and the
+ToolMessage artifact carries the full data plus the payment receipt.
+Failures raise ToolException, which ``handle_tool_error=True`` turns into a
+message the model can read and act on.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+try:
+    from langchain_core.tools import BaseTool, ToolException
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("Install the LangChain extra: pip install 'apexrunner-tools[langchain]'") from exc
+
+from pydantic import ConfigDict, Field
+
+from .client import ApexClient
+from .errors import ApexError
+from .signals import SIGNALS
+
+
+class ApexTool(BaseTool):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    client: ApexClient = Field(exclude=True)
+    signal: str
+    response_format: Literal["content", "content_and_artifact"] = "content_and_artifact"
+    handle_tool_error: bool = True
+
+    def _run(self, *args: Any, run_manager: Any = None, **kwargs: Any) -> tuple[str, dict]:
+        try:
+            result = self.client.call(self.signal, **kwargs)
+        except ApexError as exc:
+            raise ToolException(str(exc)) from exc
+        return result.to_content(), result.to_artifact()
+
+    async def _arun(self, *args: Any, run_manager: Any = None, **kwargs: Any) -> tuple[str, dict]:
+        try:
+            result = await self.client.acall(self.signal, **kwargs)
+        except ApexError as exc:
+            raise ToolException(str(exc)) from exc
+        return result.to_content(), result.to_artifact()
+
+
+def get_apex_tools(client: ApexClient | None = None, **client_kwargs: Any) -> list[ApexTool]:
+    """The three APEX tools sharing one client (one wallet, one budget, one cache).
+
+    Pass an existing ``client``, or the ApexClient arguments (``private_key=...``,
+    ``budget_usdc=...``, ...) to create one.
+    """
+    if client is None:
+        client = ApexClient(**client_kwargs)
+    elif client_kwargs:
+        raise ValueError("Pass either client or client arguments, not both.")
+    return [
+        ApexTool(
+            name=spec.name,
+            description=spec.description,
+            args_schema=spec.input_model,
+            client=client,
+            signal=spec.name,
+        )
+        for spec in SIGNALS
+    ]

apexrunner_tools/payment.py

@@ -0,0 +1,181 @@
+"""Wallet setup, the APEX-only payment policy, and the spend budget.
+
+Two independent gates run before anything is signed:
+
+1. A payment *policy* removes every payment option that is not exact-scheme
+   USDC on Base, to APEX's pinned address, at or under the per-call cap. If no
+   option is left, x402 raises and nothing is signed.
+2. A *before-payment hook* re-checks the selected option and charges the spend
+   budget. If the budget would be exceeded it aborts, and nothing is signed.
+
+The hook runs once per signature, not once per call, so the SDK's "recovery"
+path (which can sign a second payment within one HTTP call) is budgeted too.
+A signed authorization counts as spent the moment it is signed: the budget
+never assumes a payment was *not* settled.
+"""
+
+from __future__ import annotations
+
+import threading
+from contextvars import ContextVar
+from decimal import Decimal
+from typing import Any
+
+from x402 import x402Client, x402ClientSync
+from x402.mechanisms.evm.exact import register_exact_evm_client
+from x402.mechanisms.evm.signers import EthAccountSigner
+from x402.schemas import AbortResult, NoMatchingRequirementsError, PaymentAbortedError
+
+from .constants import APEX_PAY_TO, BASE_MAINNET, BASE_USDC, USDC_DECIMALS
+from .errors import ApexError, BudgetExceeded, PaymentRefused
+
+ABORT_BUDGET = "apexrunner_budget_exceeded"
+ABORT_NOT_APEX = "apexrunner_not_apex_payment"
+
+_UNIT = Decimal(10) ** USDC_DECIMALS
+
+
+def to_atomic(usdc: float | int | str | Decimal) -> int:
+    return int((Decimal(str(usdc)) * _UNIT).to_integral_value())
+
+
+def from_atomic(atomic: int) -> float:
+    return float(Decimal(atomic) / _UNIT)
+
+
+# Amounts signed during the current call. Set by ApexClient around each request.
+# Works for threads (sync) and asyncio tasks, including hooks the async client
+# runs through asyncio.to_thread (which copies the context).
+call_ledger: ContextVar[list[int] | None] = ContextVar("apexrunner_call_ledger", default=None)
+
+
+def resolve_signer(private_key: str | None = None, account: Any = None, signer: Any = None) -> Any:
+    """Return an x402 EVM signer from exactly one of the three ways to supply a wallet.
+
+    A private key becomes an eth_account LocalAccount, which holds it only to sign;
+    the key string itself is not stored anywhere else.
+    """
+    supplied = sum(x is not None for x in (private_key, account, signer))
+    if supplied != 1:
+        raise ValueError("Provide exactly one of private_key, account or signer.")
+    if private_key is not None:
+        from eth_account import Account
+
+        account = Account.from_key(private_key)
+    if account is not None:
+        return EthAccountSigner(account)
+    if not isinstance(getattr(signer, "address", None), str) or not callable(
+        getattr(signer, "sign_typed_data", None)
+    ):
+        raise TypeError("signer must have an 'address' string and a 'sign_typed_data' method.")
+    return signer
+
+
+def is_apex_requirement(req: Any, max_atomic: int) -> bool:
+    amount = str(getattr(req, "amount", "") or "")
+    if not amount.isdigit():
+        return False
+    return (
+        getattr(req, "scheme", None) == "exact"
+        and getattr(req, "network", None) == BASE_MAINNET
+        and str(getattr(req, "asset", "")).lower() == BASE_USDC.lower()
+        and str(getattr(req, "pay_to", "")).lower() == APEX_PAY_TO.lower()
+        and 0 < int(amount) <= max_atomic
+    )
+
+
+def apex_only_policy(max_atomic: int):
+    def policy(version: int, reqs: list) -> list:
+        if version != 2:  # APEX speaks x402 v2; never guess at v1 fields
+            return []
+        return [r for r in reqs if is_apex_requirement(r, max_atomic)]
+
+    return policy
+
+
+class SpendBudget:
+    """Thread-safe running total of USDC signed by one client."""
+
+    def __init__(self, limit_usdc: float):
+        if limit_usdc < 0:
+            raise ValueError("budget_usdc must be >= 0")
+        self._limit = to_atomic(limit_usdc)
+        self._spent = 0
+        self._lock = threading.Lock()
+
+    def try_spend(self, atomic: int) -> bool:
+        with self._lock:
+            if self._spent + atomic > self._limit:
+                return False
+            self._spent += atomic
+            return True
+
+    @property
+    def limit_usdc(self) -> float:
+        return from_atomic(self._limit)
+
+    @property
+    def spent_usdc(self) -> float:
+        with self._lock:
+            return from_atomic(self._spent)
+
+    @property
+    def remaining_usdc(self) -> float:
+        with self._lock:
+            return from_atomic(self._limit - self._spent)
+
+
+def _before_payment_hook(budget: SpendBudget, max_atomic: int):
+    def hook(ctx: Any) -> AbortResult | None:
+        req = ctx.selected_requirements
+        if ctx.payment_required.x402_version != 2 or not is_apex_requirement(req, max_atomic):
+            return AbortResult(reason=ABORT_NOT_APEX)
+        amount = int(req.amount)
+        if not budget.try_spend(amount):
+            return AbortResult(reason=ABORT_BUDGET)
+        ledger = call_ledger.get()
+        if ledger is not None:
+            ledger.append(amount)
+        return None
+
+    return hook
+
+
+def build_sync_client(signer: Any, budget: SpendBudget, max_atomic: int) -> x402ClientSync:
+    client = x402ClientSync()
+    register_exact_evm_client(client, signer, networks=BASE_MAINNET)
+    client.register_policy(apex_only_policy(max_atomic))
+    client.on_before_payment_creation(_before_payment_hook(budget, max_atomic))
+    return client
+
+
+def build_async_client(signer: Any, budget: SpendBudget, max_atomic: int) -> x402Client:
+    client = x402Client()
+    register_exact_evm_client(client, signer, networks=BASE_MAINNET)
+    client.register_policy(apex_only_policy(max_atomic))
+    client.on_before_payment_creation(_before_payment_hook(budget, max_atomic))
+    return client
+
+
+def map_payment_exception(exc: BaseException, budget: SpendBudget) -> ApexError:
+    """Translate x402's exception (often wrapped by the HTTP adapter) into ours."""
+    seen: set[int] = set()
+    cur: BaseException | None = exc
+    while cur is not None and id(cur) not in seen:
+        seen.add(id(cur))
+        if isinstance(cur, PaymentAbortedError):
+            if cur.reason == ABORT_BUDGET:
+                return BudgetExceeded(
+                    f"Spend budget reached (${budget.spent_usdc:.4f} of ${budget.limit_usdc:.2f} "
+                    "signed). Nothing was signed for this call."
+                )
+            return PaymentRefused(
+                "The payment request did not match APEX Runner's pinned terms. Nothing was signed."
+            )
+        if isinstance(cur, NoMatchingRequirementsError):
+            return PaymentRefused(
+                "No acceptable payment option: APEX payments must be exact USDC on Base to the "
+                "pinned address at or under the per-call cap. Nothing was signed."
+            )
+        cur = cur.__cause__ or cur.__context__
+    return ApexError(f"Request to APEX Runner failed: {type(exc).__name__}: {exc}")

apexrunner_tools/schemas.py

@@ -0,0 +1,26 @@
+"""Tool inputs, shared by the LangChain and CrewAI adapters.
+
+Bounds mirror the server's own validation (apex-signals PARAM_SPECS).
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+Coin = Literal["BTC", "ETH", "SOL", "AVAX", "LINK", "XRP"]
+
+
+class RiskAssessmentBundleInput(BaseModel):
+    """No input: a market-wide risk snapshot."""
+
+
+class ExecutionWindowOptimizerInput(BaseModel):
+    coin: Coin = Field(default="BTC", description="Asset symbol to score the execution window for.")
+
+
+class SlippageForecastInput(BaseModel):
+    coin: Coin = Field(default="BTC", description="Asset symbol of the order.")
+    size_usd: float = Field(
+        ge=10, le=1_000_000, description="Order notional in USD, between 10 and 1,000,000. Example: 5000."
+    )
+    side: Literal["buy", "sell"] = Field(default="buy", description="Order side.")

apexrunner_tools/signals.py

@@ -0,0 +1,82 @@
+"""The three tools, defined once. Both framework adapters read from here."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from .schemas import ExecutionWindowOptimizerInput, RiskAssessmentBundleInput, SlippageForecastInput
+
+_COST = (
+    "Costs about $0.01 in USDC on Base, paid automatically from the agent's wallet. "
+    "Repeating the same call while the data is still fresh returns the cached result at no cost."
+)
+
+
+@dataclass(frozen=True)
+class SignalSpec:
+    name: str
+    slug: str
+    input_model: type[BaseModel]
+    description: str
+
+    def to_query(self, args: BaseModel) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for key, value in args.model_dump().items():
+            if isinstance(value, float) and value.is_integer():
+                value = int(value)
+            out[key] = str(value)
+        return out
+
+
+RISK_ASSESSMENT_BUNDLE = SignalSpec(
+    name="risk_assessment_bundle",
+    slug="risk-assessment-bundle",
+    input_model=RiskAssessmentBundleInput,
+    description=(
+        "Check crypto market risk before sizing or opening a position. One call returns 4 signals: "
+        "liquidation cascade risk per coin (liquidation_pressure), the nearest liquidation clusters "
+        "and which way price is being pulled (liquidation_magnet), overall market heat with a "
+        "suggested action (portfolio_heat), and top-trader long/short positioning (whale_sentiment). "
+        "Use it to avoid entering just as leverage is about to unwind. Takes no input. " + _COST
+    ),
+)
+
+EXECUTION_WINDOW_OPTIMIZER = SignalSpec(
+    name="execution_window_optimizer",
+    slug="execution-window-optimizer",
+    input_model=ExecutionWindowOptimizerInput,
+    description=(
+        "Decide whether to execute a crypto order now or wait. Scores the current window 0-100 "
+        "from trading session, market regime, Fear & Greed and volatility, and returns a verdict "
+        "(EXECUTE_NOW, GOOD_WINDOW, WAIT_15MIN or WAIT_SESSION), a recommended order type and the "
+        "next favourable window. Input: coin (BTC, ETH, SOL, AVAX, LINK or XRP; default BTC). " + _COST
+    ),
+)
+
+SLIPPAGE_FORECAST = SignalSpec(
+    name="slippage_forecast",
+    slug="slippage-forecast",
+    input_model=SlippageForecastInput,
+    description=(
+        "Forecast the hidden market-impact cost of a crypto order before placing it. Returns "
+        "expected slippage as a percentage and in USD for the given coin, size and side, plus a "
+        "recommendation: EXECUTE_NOW, EXECUTE, SPLIT_ORDER (with a suggested tranche count) or "
+        "USE_LIMIT. Use it for any order above a few hundred dollars. Inputs: coin (BTC, ETH, SOL, "
+        "AVAX, LINK or XRP), size_usd (10 to 1,000,000), side (buy or sell). "
+        "Example: coin=ETH, size_usd=5000, side=sell. " + _COST
+    ),
+)
+
+SIGNALS: tuple[SignalSpec, ...] = (RISK_ASSESSMENT_BUNDLE, EXECUTION_WINDOW_OPTIMIZER, SLIPPAGE_FORECAST)
+
+_BY_KEY = {key: spec for spec in SIGNALS for key in (spec.name, spec.slug)}
+
+
+def get_spec(signal: str) -> SignalSpec:
+    try:
+        return _BY_KEY[signal]
+    except KeyError:
+        names = ", ".join(s.name for s in SIGNALS)
+        raise ValueError(f"Unknown signal {signal!r}. Available: {names}") from None

apexrunner_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: apexrunner-tools
+Version: 0.1.0
+Summary: LangChain and CrewAI tools for APEX Runner pre-trade crypto signals (risk, execution timing, slippage), paid per call over x402 in USDC on Base.
+Project-URL: Homepage, https://apexrunner.ai
+Project-URL: Documentation, https://apexrunner.ai/signals/docs/
+Project-URL: Repository, https://github.com/kynto2001-ctrl/apexrunner-tools
+Project-URL: Issues, https://github.com/kynto2001-ctrl/apexrunner-tools/issues
+Author-email: APEX Runner <267811382+kynto2001-ctrl@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,base,crewai,crypto,langchain,trading,usdc,x402
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: x402[evm,httpx,requests]<3,>=2.8
+Provides-Extra: crewai
+Requires-Dist: crewai<2,>=1.0; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: crewai<2,>=1.0; extra == 'dev'
+Requires-Dist: langchain-core<2,>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# apexrunner-tools
+
+Pre-trade crypto signals for **LangChain** and **CrewAI** agents. Each call is paid per use over [x402](https://x402.org) from the agent's own wallet: about $0.01 in USDC on Base mainnet. There is no API key, no account and no subscription.
+
+| Tool | Input | Returns |
+|---|---|---|
+| `risk_assessment_bundle` | none | 4 signals in one call: liquidation cascade risk, nearest liquidation clusters, market heat, top-trader positioning |
+| `execution_window_optimizer` | `coin` | 0–100 window score and a verdict: EXECUTE_NOW / GOOD_WINDOW / WAIT_15MIN / WAIT_SESSION, plus an order type |
+| `slippage_forecast` | `coin`, `size_usd`, `side` | Expected slippage % and USD, and a recommendation: EXECUTE_NOW / EXECUTE / SPLIT_ORDER / USE_LIMIT |
+
+Coins: BTC, ETH, SOL, AVAX, LINK, XRP.
+
+## Install
+
+```bash
+pip install "apexrunner-tools[langchain]"   # or [crewai]
+```
+
+## LangChain
+
+```python
+import os
+from langchain.agents import create_agent
+from apexrunner_tools.langchain import get_apex_tools
+
+tools = get_apex_tools(private_key=os.environ["AGENT_WALLET_KEY"])  # $1.00 budget by default
+agent = create_agent("openai:gpt-4.1-mini", tools=tools)
+```
+
+Each tool returns `content_and_artifact`. The model sees compact JSON. The `ToolMessage.artifact` holds the full data and the payment receipt (amount and transaction hash).
+
+## CrewAI
+
+```python
+import os
+from crewai import Agent
+from apexrunner_tools.crewai import get_apex_tools
+
+trader = Agent(
+    role="Execution trader",
+    goal="Place orders at the lowest total cost",
+    backstory="Checks risk, timing and slippage before every order.",
+    tools=get_apex_tools(private_key=os.environ["AGENT_WALLET_KEY"]),
+)
+```
+
+## Without a framework
+
+```python
+from apexrunner_tools import ApexClient
+
+with ApexClient(private_key=os.environ["AGENT_WALLET_KEY"]) as apex:
+    r = apex.call("slippage_forecast", coin="ETH", size_usd=5000, side="sell")
+    print(r.data["recommendation"], r.amount_usdc, r.transaction)
+    print(apex.budget.spent_usdc, apex.budget.remaining_usdc)
+```
+
+`acall()` is the async version.
+
+## Wallet
+
+Supply exactly one of these:
+
+- `private_key="0x…"`. It is turned into an `eth_account` signer, which holds the key only so it can sign. The key never appears in any attribute, `repr()` or a tool's serialised form.
+- `account=LocalAccount`, from `eth_account`.
+- `signer=...`, any object with an `address` and `sign_typed_data(...)`. Use this for KMS, HSM or hosted wallets.
+
+The wallet needs **USDC on Base mainnet**, and no ETH. Payments are signed USDC authorizations (EIP-3009), and the facilitator pays the gas. One dollar covers about 100 calls.
+
+## Safeguards
+
+| Safeguard | What it does |
+|---|---|
+| **Pinned payment terms** | Before anything is signed, every payment option is checked: it must be x402 v2 `exact` USDC on Base, payable to APEX Runner's pinned address. Anything else is refused and **nothing is signed** (`PaymentRefused`). This holds even if the server, DNS or a proxy is compromised. |
+| **Per-call cap** | `max_payment_usdc`, default **$0.02** and never above $1.00. A higher price is refused before signing. |
+| **Spend budget** | `budget_usdc`, default **$1.00** per client. It is checked at the moment of signing, every signature counts (including the SDK's automatic re-sign on recovery), and it is safe across threads. When the budget is spent, calls raise `BudgetExceeded` and nothing is signed. A signed payment counts as spent even if the call then fails: the budget never assumes a payment was not settled. |
+| **Expiring cache** | Repeating an identical call while its data is still valid (the response's `valid_for_seconds` minus its age, at most 300 s) returns the cached result at no cost. Stale data is never cached. CrewAI's own cache has no expiry, so it is switched off for these tools. |
+
+## Errors
+
+All errors subclass `ApexError`:
+
+| Error | Meaning | Charged? |
+|---|---|---|
+| `PaymentRefused` | The payment request didn't match the pinned terms | No, nothing was signed |
+| `BudgetExceeded` | The budget is spent | No, nothing was signed |
+| `PaymentRejected` | A payment was signed but refused, usually too little USDC | No settlement |
+| `ApexUnavailable` | The server returned a non-2xx status | x402 settles only on success |
+| `ApexResponseError` | The server returned a 2xx with an unreadable body | Possibly; report it |
+
+LangChain turns these into a tool message the model can read. CrewAI tools return `{"success": false, "error": ...}`.
+
+## License
+
+MIT

apexrunner_tools-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+apexrunner_tools/__init__.py,sha256=plFzZpLHdOaqs_WfhbzpKbXeaBklB-ykgjls2k3fx8Q,752
+apexrunner_tools/client.py,sha256=1RubhPH3QFo7lrRvEkjnbEkEX-z0zbaZIZqKIg_YeL8,10725
+apexrunner_tools/constants.py,sha256=2FWL2thpd912-izTFeXZS5ARQM_Eo_6RgCPostEJ9dU,1152
+apexrunner_tools/crewai.py,sha256=BgVdXUscRaUX10G9uYVocSg001QOsugLw109tFIeil4,2460
+apexrunner_tools/errors.py,sha256=DG9MjdKaga9K0dE5WQ3383piEaamPB3TsnQlwLtAM7A,911
+apexrunner_tools/langchain.py,sha256=wGpWnO6e9uywdCIhijd8c09Jmw_CcKaR9IK4ztAPHg4,2573
+apexrunner_tools/payment.py,sha256=-wbNGVt3nlo8Qfwg_jk2CFVv2qgcQ_MhNGGqCdbAcjw,6977
+apexrunner_tools/schemas.py,sha256=DOKMcEJjcKDomirj_YgOsbvLlRTyF-TY5axNZi-cqCw,856
+apexrunner_tools/signals.py,sha256=QMTemtZMWLiVAXg1dQO6aStq8U5cQRaY1fm8r4IpWM4,3292
+apexrunner_tools-0.1.0.dist-info/METADATA,sha256=NNC4l6Bt8Byhydm6wQKiIeX3zafgooUsreCzr3D-_xA,6007
+apexrunner_tools-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+apexrunner_tools-0.1.0.dist-info/licenses/LICENSE,sha256=H2oaFd6oS8ncxyFUXpNsLXHRQwb_S7ewMH4dRxCuGCI,1068
+apexrunner_tools-0.1.0.dist-info/RECORD,,

apexrunner_tools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

apexrunner_tools-0.1.0.dist-info/licenses/LICENSE

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