Skip to main content

apexrunner-tools

Pre-trade crypto signals for LangChain and CrewAI agents, plus RiskShield, a pre-trade gate that blocks high-risk trades in code before they reach your exchange. Each call is paid per use over x402 from the agent's own wallet: about $0.01 in USDC on Base mainnet ($0.014 for check_trade_safety). 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
check_trade_safety coin, side, size_usd (all required) 0–100 safety score for one specific trade and a verdict: LOW_RISK (65+) / CAUTION (40–64) / DANGER (<40), with the reason for each factor

Coins: BTC, ETH, SOL, AVAX, LINK, XRP. check_trade_safety covers BTC, ETH and SOL, long/short (buy/sell accepted), $10 to $10,000,000.

Install

pip install "apexrunner-tools[langchain]"   # or [crewai]

LangChain

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

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

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.

RiskShield: block dangerous trades before they execute

A prompt can tell an agent to check risk first. RiskShield makes it impossible to skip: it wraps the function that places the order, so every trade is scored by check_trade_safety before it runs, and a trade in the DANGER band never reaches your exchange code.

import os
from apexrunner_tools import ApexClient, RiskShield, TradeBlocked

shield = RiskShield(ApexClient(private_key=os.environ["AGENT_WALLET_KEY"]))

@shield.protect
def place_order(coin: str, side: str, size_usd: float) -> dict:
    return exchange.market_order(coin, side, size_usd)   # your code, unchanged

try:
    place_order("ETH", "long", 5000)
except TradeBlocked as e:
    print(e)              # BLOCKED: long ETH $5,000 scored 31/100 (DANGER; blocks under 40). ...
    e.decision.reasons    # one line per factor, highest risk first
Option Default Effect
block_below 40 Block when the score is below this. 40 blocks DANGER only; 65 also blocks CAUTION. A DANGER verdict always blocks.
fail_open False If the check can't be completed (APEX unavailable, budget spent, unsupported coin, unreadable response), the trade is blocked. Set True to let it through instead; the decision still records why.
on_decision None Callback that receives every ShieldDecision (score, verdict, reasons, error, receipt). Use it to log or alert.

Your function's own coin, side and size_usd arguments are used. If they're named differently, map them with @shield.protect(params={"coin": "symbol", "side": "direction", "size_usd": "notional"}). For an order object, use @shield.protect(extract=lambda order: (order.coin, order.side, order.usd)). Async functions work the same way. To score without wrapping, call shield.check(coin, side, size_usd), which returns a ShieldDecision and never raises, or shield.guard(...), which raises TradeBlocked. For one-off use, @apex_shield(private_key=...) creates the client and the shield in one line.

Cost: one check is $0.014. An identical check (same coin, side and size) within the response's validity window (120 s) is served from cache at no cost. The default $1.00 client budget covers about 70 checks. When it is spent, trades are blocked (fail closed) until you raise the budget.

In an agent: let the LLM decide what to trade, and put the shield on the tool that executes. TradeBlocked is not an ApexError and is not caught by the tools' error handling, so catch it in your order tool and return str(e) to the model. The message explains why, and the agent can resize, flip or skip:

from langchain_core.tools import tool

@tool
def execute_trade(coin: str, side: str, size_usd: float) -> str:
    """Place a market order. It is risk-checked first and may be refused."""
    try:
        return str(place_order(coin, side, size_usd))
    except TradeBlocked as e:
        return str(e)

What the score is, and isn't: a heuristic computed from live market structure: Hyperliquid liquidation clusters near the mark price, top-trader crowding on your side, funding paid by your side, and modelled slippage for your size. The weights are not yet calibrated against outcomes (method.calibrated: false in every response). A trade that passes is not "safe", and none of this is investment advice. RiskShield is a guard against walking into obvious structural risk, not a strategy.

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

TradeBlocked (RiskShield) is separate and is not an ApexError: the API worked, and the trade was refused. e.decision holds the full ShieldDecision.

LangChain turns these into a tool message the model can read. CrewAI tools return {"success": false, "error": ...}.

License

MIT

Metadata

Release files for apexrunner-tools 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apexrunner-tools 0.2.0
File Size Uploaded Provenance Actions
apexrunner_tools-0.2.0.tar.gz 29.4 kB With provenance Details for apexrunner_tools-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apexrunner-tools 0.2.0
File Interpreter ABI Platform Actions
apexrunner_tools-0.2.0-py3-none-any.whl Python 3 none any Details for apexrunner_tools-0.2.0-py3-none-any.whl

Total release size: 53.0 kB

Release files / apexrunner_tools-0.2.0.tar.gz

Download URL apexrunner_tools-0.2.0.tar.gz
Size 29.4 kB
Tags Source
SHA-256 checksum
How to use checksums
dc1d70af51966a7e74aa08972fbbbbb52ebe84f78dab4dd41a37860d41849137
BLAKE2b-256 checksum
How to use checksums
2f87ec3b349af8f7713505a7281b7ef6c4d3ae0e35ec0d7e5e8e579457519265
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / apexrunner_tools-0.2.0-py3-none-any.whl

Download URL apexrunner_tools-0.2.0-py3-none-any.whl
Size 23.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
292e1b22e5509edc5ccf2fbc58008af3e6bfc42f6deff05137166238687d3895
BLAKE2b-256 checksum
How to use checksums
33e1eab47e19ac3af19e58991b68e5a342188a6f33176f28c9038a1a4978bac3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for apexrunner-tools 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for apexrunner_tools-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page