token-verdict-tools

Token Verdict tools for LangChain and CrewAI — plus the shared, framework-free client underneath both.

Token Verdict is a pay-per-call token risk service. Send a token contract address, get back a SOLID / CAUTION / DANGER verdict, a 0–100 score, six market-structure signals (liquidity depth, volume churn, sell pressure, price action, trader breadth, pair age) and a narrative take. A second route, the pre-trade check, combines the token verdict with optional wallet and allowance legs into one PROCEED / CAUTION / ABORT decision — the check to run before an agent spends.

Calls are paid per use with x402: USDC on Base, $0.02 per verdict, $0.05 per pre-trade check. There are no API keys and no accounts — the HTTP 402 challenge is the checkout.

Install

pip install token-verdict-tools[langchain]   # LangChain tools
pip install token-verdict-tools[crewai]      # CrewAI tools
pip install token-verdict-tools              # just the shared client

You need a payer account

Neither framework has a wallet provider, so the tools take an eth_account local account at construction. The account must hold a little USDC on Base mainnet — it signs an EIP-3009 authorization per call and the service settles it. Use a dedicated, small-balance agent wallet.

import os
from eth_account import Account

account = Account.from_key(os.environ["AGENT_PRIVATE_KEY"])

Every call is spend-guarded: the client only signs a payment if the challenge asks for USDC on Base at or under the route's cap — $0.02 for a verdict, $0.05 for a pre-trade check by default. A repriced endpoint is refused, never silently paid. Raise a cap explicitly via max_verdict_amount= / max_pre_trade_amount= if the service's price ever changes.

LangChain

from token_verdict_tools.langchain_tools import PreTradeCheckTool, TokenVerdictTool

tools = [TokenVerdictTool(account=account), PreTradeCheckTool(account=account)]
# ...hand `tools` to any LangChain agent as usual.

TokenVerdictTool(account=account).invoke({"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"})

Tools return the service's JSON. Failures raise ToolException with handle_tool_error on, so invoke returns an "Error getting token verdict: …" message to the agent instead of crashing the run — a verdict is never fabricated.

CrewAI

from token_verdict_tools.crewai_tools import PreTradeCheckTool, TokenVerdictTool

agent = Agent(role="Risk checker", goal="Vet tokens before any trade",
              tools=[TokenVerdictTool(account=account), PreTradeCheckTool(account=account)])

Same contract, CrewAI idiom: _run returns the JSON string on success and an "Error …" string on failure.

Just the client

from token_verdict_tools import TokenVerdictClient

client = TokenVerdictClient(account=account)
client.verdict("0x...")                                        # $0.02
client.verdict("0x...", chain="ethereum")                       # Base/ETH/SOL markets
client.pre_trade("0x...", wallet_address="0x...", spender="0x...")  # $0.05

verdict() / pre_trade() return the response dict and raise TokenVerdictPaymentError (challenge unpaid — e.g. the spend guard refused) or TokenVerdictRequestError (any other non-200) on failure.

Development

pip install -e .[all,dev]
pytest

Tests are fully offline: HTTP is stubbed at the requests adapter layer, so the real x402 client, exact EVM scheme and EIP-712 signing run against recorded 402 challenges — including a signature-recovery check on the payment the client produces. No test makes a live paid call.