apexrunner-tools 0.1.0__tar.gz

apexrunner_tools-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/

apexrunner_tools-0.1.0/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.

apexrunner_tools-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,95 @@
+# 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/examples/crewai_crew.py

@@ -0,0 +1,29 @@
+"""CrewAI crew with an execution trader that uses APEX Runner tools.
+
+    pip install "apexrunner-tools[crewai]"
+    AGENT_WALLET_KEY=0x... OPENAI_API_KEY=... python examples/crewai_crew.py
+
+Spends real USDC on Base (about $0.007 per tool call), capped by budget_usdc.
+"""
+
+import os
+
+from crewai import Agent, Crew, Task
+
+from apexrunner_tools import ApexClient
+from apexrunner_tools.crewai import get_apex_tools
+
+apex = ApexClient(private_key=os.environ["AGENT_WALLET_KEY"], budget_usdc=0.10)
+trader = Agent(
+    role="Execution trader",
+    goal="Execute crypto orders at the lowest total cost and risk",
+    backstory="You never place an order without checking risk, timing and slippage first.",
+    tools=get_apex_tools(apex),
+)
+task = Task(
+    description="Decide how and when to sell $5,000 of ETH. Use the tools, then give a concrete plan.",
+    expected_output="A short execution plan: now or later, order type, and whether to split the order.",
+    agent=trader,
+)
+print(Crew(agents=[trader], tasks=[task]).kickoff())
+print(f"APEX spend: ${apex.budget.spent_usdc:.3f} of ${apex.budget.limit_usdc:.2f}")

apexrunner_tools-0.1.0/examples/langchain_agent.py

@@ -0,0 +1,24 @@
+"""LangChain agent that checks risk, timing and slippage before proposing a trade.
+
+    pip install "apexrunner-tools[langchain]" langchain langchain-openai
+    AGENT_WALLET_KEY=0x... OPENAI_API_KEY=... python examples/langchain_agent.py
+
+Spends real USDC on Base (about $0.007 per tool call), capped by budget_usdc.
+"""
+
+import os
+
+from langchain.agents import create_agent
+
+from apexrunner_tools import ApexClient
+from apexrunner_tools.langchain import get_apex_tools
+
+apex = ApexClient(private_key=os.environ["AGENT_WALLET_KEY"], budget_usdc=0.10)
+agent = create_agent(
+    "openai:gpt-4.1-mini",
+    tools=get_apex_tools(apex),
+    system_prompt="Before recommending any crypto order, check market risk, the execution window and slippage.",
+)
+result = agent.invoke({"messages": [{"role": "user", "content": "Should I sell $5,000 of ETH right now?"}]})
+print(result["messages"][-1].content)
+print(f"APEX spend: ${apex.budget.spent_usdc:.3f} of ${apex.budget.limit_usdc:.2f}")

apexrunner_tools-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apexrunner-tools"
+version = "0.1.0"
+description = "LangChain and CrewAI tools for APEX Runner pre-trade crypto signals (risk, execution timing, slippage), paid per call over x402 in USDC on Base."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "APEX Runner", email = "267811382+kynto2001-ctrl@users.noreply.github.com" }]
+keywords = ["x402", "langchain", "crewai", "crypto", "trading", "agents", "usdc", "base"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Intended Audience :: Developers",
+]
+dependencies = [
+  # 2.8 is the floor the API was verified against (same names through 2.28).
+  "x402[evm,requests,httpx]>=2.8,<3",
+  "pydantic>=2.6,<3",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=1.0,<2"]
+crewai = ["crewai>=1.0,<2"]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "langchain-core>=1.0,<2", "crewai>=1.0,<2"]
+
+[project.urls]
+Homepage = "https://apexrunner.ai"
+Documentation = "https://apexrunner.ai/signals/docs/"
+Repository = "https://github.com/kynto2001-ctrl/apexrunner-tools"
+Issues = "https://github.com/kynto2001-ctrl/apexrunner-tools/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apexrunner_tools"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.hatch.build.targets.sdist]
+# scripts/ holds APEX-internal ops tooling (live paid test, seed wallet address, key path).
+exclude = ["scripts/", ".github/", ".venv/", "dist/"]

apexrunner_tools-0.1.0/src/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__",
+]