Metadata-Version: 2.5
Name: token-verdict-tools
Version: 0.1.0
Summary: Token Verdict tools for LangChain and CrewAI - pay-per-call token risk verdicts (SOLID/CAUTION/DANGER) and pre-trade checks (PROCEED/CAUTION/ABORT) via x402 USDC payments on Base.
Project-URL: Homepage, https://github.com/QuincyGB/token-verdict
Project-URL: Repository, https://github.com/QuincyGB/token-verdict
Author: QuincyGB
License: MIT
License-File: LICENSE
Keywords: agents,base,crewai,langchain,risk,token,web3,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: eth-account>=0.13
Requires-Dist: pydantic>=2
Requires-Dist: requests>=2.32
Requires-Dist: x402[evm,requests]>=2.4.0
Provides-Extra: all
Requires-Dist: crewai>=0.80; extra == 'all'
Requires-Dist: langchain-core>=0.3; extra == 'all'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Description-Content-Type: text/markdown

# token-verdict-tools

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

[Token Verdict](https://token-verdict-production.up.railway.app) 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](https://x402.org): 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

```bash
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`](https://eth-account.readthedocs.io) 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.

```python
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

```python
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

```python
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

```python
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

```bash
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.
