token-verdict-tools 0.1.0__tar.gz

token_verdict_tools-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[all,dev]"
+
+      - name: Test package
+        run: python -m pytest
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish package with PyPI trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

token_verdict_tools-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+.tmp/
+.pytest_cache/

token_verdict_tools-0.1.0/LICENSE

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

token_verdict_tools-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+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.

token_verdict_tools-0.1.0/README.md

@@ -0,0 +1,102 @@
+# 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.

token_verdict_tools-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "token-verdict-tools"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "QuincyGB" }]
+keywords = ["langchain", "crewai", "agents", "x402", "token", "risk", "base", "web3"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "eth-account>=0.13",
+    "pydantic>=2",
+    "requests>=2.32",
+    "x402[evm,requests]>=2.4.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+crewai = ["crewai>=0.80"]
+all = ["langchain-core>=0.3", "crewai>=0.80"]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/QuincyGB/token-verdict"
+Repository = "https://github.com/QuincyGB/token-verdict"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/token_verdict_tools"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

token_verdict_tools-0.1.0/src/token_verdict_tools/__init__.py

@@ -0,0 +1,54 @@
+"""Token Verdict tools for LangChain and CrewAI.
+
+This package's core is the shared, framework-free client:
+
+    from eth_account import Account
+    from token_verdict_tools import TokenVerdictClient
+
+    client = TokenVerdictClient(account=Account.from_key(...))
+    client.verdict("0x...")       # POST /v1/verdict, $0.02 USDC on Base
+    client.pre_trade("0x...", wallet_address="0x...")  # $0.05
+
+The framework tools live in submodules so importing the client never drags
+a framework in:
+
+    from token_verdict_tools.langchain_tools import TokenVerdictTool
+    from token_verdict_tools.crewai_tools import PreTradeCheckTool
+"""
+
+from .client import TokenVerdictClient, TokenVerdictOptions, usd_to_atomic
+from .constants import (
+    BASE_NETWORK,
+    BASE_USDC_ADDRESS,
+    TOKEN_VERDICT_BASE_URL,
+    TOKEN_VERDICT_PATH,
+    TOKEN_VERDICT_PRE_TRADE_PATH,
+    TOKEN_VERDICT_PRE_TRADE_PRICE,
+    TOKEN_VERDICT_PRICE,
+)
+from .errors import (
+    TokenVerdictError,
+    TokenVerdictPaymentError,
+    TokenVerdictRequestError,
+)
+from .schemas import PreTradeCheckInput, TokenVerdictInput
+
+__all__ = [
+    "BASE_NETWORK",
+    "BASE_USDC_ADDRESS",
+    "TOKEN_VERDICT_BASE_URL",
+    "TOKEN_VERDICT_PATH",
+    "TOKEN_VERDICT_PRE_TRADE_PATH",
+    "TOKEN_VERDICT_PRE_TRADE_PRICE",
+    "TOKEN_VERDICT_PRICE",
+    "PreTradeCheckInput",
+    "TokenVerdictClient",
+    "TokenVerdictError",
+    "TokenVerdictInput",
+    "TokenVerdictOptions",
+    "TokenVerdictPaymentError",
+    "TokenVerdictRequestError",
+    "usd_to_atomic",
+]
+
+__version__ = "0.1.0"

token_verdict_tools-0.1.0/src/token_verdict_tools/client.py

@@ -0,0 +1,265 @@
+"""Shared Token Verdict client for the LangChain and CrewAI tools.
+
+One client serves both frameworks. It reuses the x402 client approach from
+the AgentKit Python action provider (coinbase/agentkit PR #1599): an
+``x402ClientSync`` with the exact EVM scheme registered over an
+``EthAccountSigner``, guarded by a payment policy that only lets USDC-on-Base
+requirements at or under the per-route cap through to signing.
+
+Unlike AgentKit, LangChain and CrewAI have no wallet-provider abstraction,
+so the signer is an ``eth_account`` local account supplied by the user. All
+signing goes through that account via the x402 SDK's signer bridge; this
+package never handles raw key material beyond holding the account object the
+user passed in.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import requests
+from eth_account.signers.local import LocalAccount
+from x402 import x402ClientSync
+from x402.client_base import RequirementsView
+from x402.http.clients.requests import wrapRequestsWithPayment
+from x402.mechanisms.evm import EthAccountSigner
+from x402.mechanisms.evm.exact.register import register_exact_evm_client
+
+from .constants import (
+    BASE_NETWORK,
+    BASE_USDC_ADDRESS,
+    TOKEN_VERDICT_BASE_URL,
+    TOKEN_VERDICT_PATH,
+    TOKEN_VERDICT_PRE_TRADE_PATH,
+    TOKEN_VERDICT_PRE_TRADE_PRICE,
+    TOKEN_VERDICT_PRICE,
+    USDC_DECIMALS,
+)
+from .errors import TokenVerdictPaymentError, TokenVerdictRequestError
+
+ADDRESS_PATTERN = re.compile(r"^0x[a-fA-F0-9]{40}$")
+USD_AMOUNT_PATTERN = re.compile(r"^\$?(\d+)(?:\.(\d+))?$")
+
+# Atomic USDC units per dollar (10 ** USDC_DECIMALS).
+ATOMIC_PER_DOLLAR: int = 10**USDC_DECIMALS
+
+SUPPORTED_CHAINS = ("base", "ethereum", "solana")
+
+
+def usd_to_atomic(amount: str) -> int:
+    """Convert a USD amount string (e.g. "$0.02") to USDC atomic units.
+
+    Args:
+        amount: The USD amount string to convert.
+
+    Returns:
+        The amount in USDC atomic units (6 decimals).
+
+    Raises:
+        ValueError: If the amount string is not a valid USD amount.
+    """
+    match = USD_AMOUNT_PATTERN.match(amount.strip())
+    if not match:
+        raise ValueError(f"Invalid USD amount: {amount}")
+
+    dollars: str = match.group(1)
+    fraction: str = match.group(2) or ""
+    if len(fraction) > USDC_DECIMALS:
+        raise ValueError(
+            f"USD amount has too many decimal places (max {USDC_DECIMALS}): {amount}"
+        )
+
+    return int(dollars) * ATOMIC_PER_DOLLAR + int(fraction.ljust(USDC_DECIMALS, "0") or "0")
+
+
+@dataclass
+class TokenVerdictOptions:
+    """Options for the Token Verdict client.
+
+    Attributes:
+        base_url: Base URL of the Token Verdict service.
+        max_verdict_amount: Spend guard for /v1/verdict - the maximum USD
+            amount the client will sign for in one verdict call. Defaults to
+            the service's known price.
+        max_pre_trade_amount: Spend guard for /v1/pre-trade, likewise.
+        session: Optional pre-configured requests session (test seam,
+            mirroring the AgentKit provider's session override).
+    """
+
+    base_url: str = TOKEN_VERDICT_BASE_URL
+    max_verdict_amount: str = TOKEN_VERDICT_PRICE
+    max_pre_trade_amount: str = TOKEN_VERDICT_PRE_TRADE_PRICE
+    session: requests.Session | None = None
+
+
+@dataclass
+class TokenVerdictClient:
+    """Pays Token Verdict's x402 charges from a user-supplied account.
+
+    Attributes:
+        account: The eth_account local account that signs (and funds) the
+            USDC payments on Base.
+        options: Service URL and spend-guard configuration.
+    """
+
+    account: LocalAccount
+    options: TokenVerdictOptions = field(default_factory=TokenVerdictOptions)
+    _active_cap_atomic: int = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        # The cap the spend-guard policy enforces for the in-flight call.
+        # The requests stack is synchronous, so one active cap per client is
+        # exact; it defaults to the lower (verdict) cap.
+        self._active_cap_atomic = usd_to_atomic(self.options.max_verdict_amount)
+
+    def _spend_guard_policy(
+        self, version: int, options: list[RequirementsView]
+    ) -> list[RequirementsView]:
+        """Filter a challenge's payment options down to payable ones.
+
+        Mirrors the AgentKit providers' PaymentPolicy: an option is payable
+        only if it asks for USDC on Base at or under the active route's cap.
+        Anything else is filtered out before signing, so the x402 client
+        refuses instead of paying.
+        """
+        del version
+        return [
+            option
+            for option in options
+            if str(option.network) == BASE_NETWORK
+            and option.asset.lower() == BASE_USDC_ADDRESS.lower()
+            and int(option.get_amount()) <= self._active_cap_atomic
+        ]
+
+    def _create_paying_session(self) -> requests.Session:
+        """Create a requests session that pays x402 challenges automatically."""
+        client = x402ClientSync()
+        register_exact_evm_client(
+            client,
+            EthAccountSigner(self.account),
+            policies=[self._spend_guard_policy],
+        )
+        session = self.options.session or requests.Session()
+        return wrapRequestsWithPayment(session, client)
+
+    def _post(self, path: str, body: dict[str, Any], cap_usd: str) -> dict[str, Any]:
+        """POST to a paid route, paying its challenge under the route's cap.
+
+        Raises:
+            TokenVerdictPaymentError: If the challenge stays unpaid (402) -
+                e.g. the spend guard filtered every payment option out.
+            TokenVerdictRequestError: On any other non-200 response or a
+                malformed success body.
+        """
+        self._active_cap_atomic = usd_to_atomic(cap_usd)
+        try:
+            session = self._create_paying_session()
+            try:
+                response = session.post(f"{self.options.base_url}{path}", json=body)
+            except Exception as e:
+                # The x402 client raises (rather than returning the 402)
+                # when the spend-guard policy filters every payment option
+                # out, and for other payment-construction failures. Those
+                # are payment failures, not request failures.
+                if "payment" in str(e).lower():
+                    raise TokenVerdictPaymentError(
+                        f"Token Verdict payment failed: {e}"
+                    ) from e
+                raise TokenVerdictRequestError(
+                    f"Token Verdict request failed: {e}"
+                ) from e
+        finally:
+            self._active_cap_atomic = usd_to_atomic(self.options.max_verdict_amount)
+
+        if response.status_code == 402:
+            raise TokenVerdictPaymentError(
+                "Token Verdict payment failed: the x402 challenge could not be "
+                f"paid within the spend guard (cap {cap_usd} USDC on Base). "
+                "The endpoint may have been repriced, or the account may lack "
+                "USDC / a settlement route."
+            )
+        if response.status_code != 200:
+            body_text = response.text[:500]
+            raise TokenVerdictRequestError(
+                f"Token Verdict request failed: HTTP {response.status_code}: {body_text}"
+            )
+
+        data = response.json()
+        if not isinstance(data, dict):
+            raise TokenVerdictRequestError(
+                "Token Verdict request failed: response was not a JSON object"
+            )
+        return data
+
+    def verdict(self, address: str, chain: str = "base") -> dict[str, Any]:
+        """Get a risk verdict for a token (POST /v1/verdict, $0.02).
+
+        Args:
+            address: The token contract address (0x-prefixed, 40 hex chars).
+            chain: Which chain's market to analyze: "base" (default),
+                "ethereum", or "solana". Payment always settles on Base.
+
+        Returns:
+            The service's verdict response: SOLID / CAUTION / DANGER, a 0-100
+            score, the six market-structure signals, and a narrative take.
+
+        Raises:
+            ValueError: If the address or chain is malformed.
+            TokenVerdictError: If the call or its payment fails.
+        """
+        if not ADDRESS_PATTERN.match(address or ""):
+            raise ValueError("address must be a 0x token contract address")
+        if chain not in SUPPORTED_CHAINS:
+            raise ValueError(f"chain must be one of {SUPPORTED_CHAINS}")
+        return self._post(
+            TOKEN_VERDICT_PATH,
+            {"address": address, "chain": chain},
+            self.options.max_verdict_amount,
+        )
+
+    def pre_trade(
+        self,
+        token_address: str,
+        wallet_address: str | None = None,
+        spender: str | None = None,
+        chain: str = "base",
+    ) -> dict[str, Any]:
+        """Run the combined pre-trade check (POST /v1/pre-trade, $0.05).
+
+        Combines the token verdict with optional wallet (sanctions, age,
+        poisoning) and allowance legs into one PROCEED / CAUTION / ABORT
+        decision - the check to run before an agent spends.
+
+        Args:
+            token_address: The token contract the trade would buy or receive.
+            wallet_address: Optional Base wallet to check.
+            spender: Optional spender contract; with wallet_address, adds
+                the allowance leg.
+            chain: Chain for the token leg (default "base"); wallet and
+                allowance legs are Base-only, enforced by the service.
+
+        Returns:
+            The service's combined decision response.
+
+        Raises:
+            ValueError: If an address is malformed, or spender is given
+                without wallet_address.
+            TokenVerdictError: If the call or its payment fails.
+        """
+        if not ADDRESS_PATTERN.match(token_address or ""):
+            raise ValueError("token_address must be a 0x contract address")
+        if wallet_address is not None and not ADDRESS_PATTERN.match(wallet_address):
+            raise ValueError("wallet_address must be a 0x address")
+        if spender is not None and not ADDRESS_PATTERN.match(spender):
+            raise ValueError("spender must be a 0x contract address")
+        if spender is not None and wallet_address is None:
+            raise ValueError("spender requires wallet_address")
+
+        body: dict[str, Any] = {"token_address": token_address, "chain": chain}
+        if wallet_address is not None:
+            body["wallet_address"] = wallet_address
+        if spender is not None:
+            body["spender"] = spender
+        return self._post(
+            TOKEN_VERDICT_PRE_TRADE_PATH, body, self.options.max_pre_trade_amount
+        )

token_verdict_tools-0.1.0/src/token_verdict_tools/constants.py

@@ -0,0 +1,17 @@
+"""Constants for the Token Verdict tools package."""
+
+# The live Token Verdict service (https://github.com/QuincyGB/token-verdict).
+TOKEN_VERDICT_BASE_URL = "https://token-verdict-production.up.railway.app"
+TOKEN_VERDICT_PATH = "/v1/verdict"
+TOKEN_VERDICT_PRE_TRADE_PATH = "/v1/pre-trade"
+
+# The service's known prices. Also the default spend-guard caps: the client
+# never signs a payment above the cap for the route being called, so a
+# repriced or hostile endpoint can never silently charge the agent more.
+TOKEN_VERDICT_PRICE = "$0.02"
+TOKEN_VERDICT_PRE_TRADE_PRICE = "$0.05"
+
+# Payment always settles in USDC on Base, whichever chain's token is analyzed.
+BASE_NETWORK = "eip155:8453"
+BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+USDC_DECIMALS = 6