crewai-true402 0.1.0__tar.gz

crewai_true402-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc

crewai_true402-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+MIT No Attribution
+
+Copyright 2026 true402
+
+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.
+
+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.

crewai_true402-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: crewai-true402
+Version: 0.1.0
+Summary: true402 tools for CrewAI — pay-per-call on-chain rug/honeypot & address safety for Base AI agents over x402 (USDC, no account, no API key).
+Project-URL: Homepage, https://true402.dev
+Project-URL: Source, https://github.com/true402/crewai-true402
+Project-URL: OpenAPI, https://true402.dev/openapi.json
+Author-email: true402 <contact@true402.dev>
+License: MIT
+License-File: LICENSE
+Keywords: agent-tools,ai-agent,base,crewai,crewai-tools,crypto,defi,honeypot,rug-check,token-safety,web3,x402
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.28
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.30; extra == 'crewai'
+Description-Content-Type: text/markdown
+
+# crewai-true402
+
+**[true402](https://true402.dev) tools for [CrewAI](https://www.crewai.com)** — give a Base trading agent a pre-trade **rug/honeypot check** it pays for per call over [x402](https://x402.org) (USDC on Base). No accounts, no API keys — the wallet is the identity. The safety checks have a **free daily trial**, so the tools work out of the box with no wallet configured.
+
+## Install
+
+```bash
+pip install crewai-true402
+```
+
+## Use
+
+```python
+from crewai import Agent
+from crewai_true402 import true402_tools
+
+# Reads PAYER_PRIVATE_KEY from the env (a Base wallet holding a little USDC).
+# Omit the key to rely on the free daily trial for the safety stalls.
+tools = true402_tools()
+
+trader = Agent(
+    role="Base memecoin trader",
+    goal="Only buy tokens that pass an on-chain safety check",
+    tools=tools,
+    backstory="You never ape into a token before rug-checking it.",
+)
+```
+
+The agent gets four tools:
+
+| Tool | What | Price |
+|------|------|-------|
+| `true402_token_report` | Composite **avoid/caution/ok** verdict — honeypot buy/sell simulation + liquidity + ownership + recent rug activity. Call **before buying**. | ~$0.01 |
+| `true402_token_safety` | Structural safety score 0–100 + flags (honeypot sim, liquidity, mint/ownership). | ~$0.005 |
+| `true402_address_safety` | Profile + risk for any address before you send/approve/call it (EOA vs contract, balances, proxy detection). | ~$0.005 |
+| `true402_deployer_check` | Deployer wallet reputation — age, contracts shipped, fresh-throwaway flag — to catch serial ruggers. | ~$0.008 |
+
+## Configuration
+
+`true402_tools()` reads the environment, or pass a `PayOpts`:
+
+```python
+from crewai_true402 import true402_tools, PayOpts
+
+tools = true402_tools(PayOpts(
+    payer_private_key="0x…",   # a Base wallet with a little USDC (gas is sponsored; USDC only)
+    max_amount_usd=0.10,        # hard per-call ceiling — refuses to sign a 402 demanding more
+))
+```
+
+| Env var | Default | Meaning |
+|---------|---------|---------|
+| `PAYER_PRIVATE_KEY` | — | Base wallet key that signs x402 payments (needs USDC, not ETH). Unset → free trial only. |
+| `TRUE402_BASE_URL` | `https://true402.dev/api` | Override to point at a self-hosted instance. |
+| `BASE_RPC_URL` | `https://mainnet.base.org` | Base RPC for the balance pre-check. |
+
+## Safety
+
+The client **refuses to sign** anything that isn't USDC-on-Base within `max_amount_usd` (default $0.10) — so a rogue or compromised endpoint can't make your agent authorize an unexpected asset, network, or amount. The private key is used only to sign locally; it never leaves the process.
+
+## Links
+
+- Live check in your browser: <https://true402.dev/check>
+- API reference: <https://true402.dev/docs/api> · OpenAPI: <https://true402.dev/openapi.json>
+- Also available: [LangChain](https://www.npmjs.com/package/@true402.dev/langchain) · [MCP server](https://www.npmjs.com/package/@true402.dev/mcp-server) · [CLI](https://www.npmjs.com/package/@true402.dev/rugcheck)
+
+## License
+
+MIT

crewai_true402-0.1.0/README.md

@@ -0,0 +1,69 @@
+# crewai-true402
+
+**[true402](https://true402.dev) tools for [CrewAI](https://www.crewai.com)** — give a Base trading agent a pre-trade **rug/honeypot check** it pays for per call over [x402](https://x402.org) (USDC on Base). No accounts, no API keys — the wallet is the identity. The safety checks have a **free daily trial**, so the tools work out of the box with no wallet configured.
+
+## Install
+
+```bash
+pip install crewai-true402
+```
+
+## Use
+
+```python
+from crewai import Agent
+from crewai_true402 import true402_tools
+
+# Reads PAYER_PRIVATE_KEY from the env (a Base wallet holding a little USDC).
+# Omit the key to rely on the free daily trial for the safety stalls.
+tools = true402_tools()
+
+trader = Agent(
+    role="Base memecoin trader",
+    goal="Only buy tokens that pass an on-chain safety check",
+    tools=tools,
+    backstory="You never ape into a token before rug-checking it.",
+)
+```
+
+The agent gets four tools:
+
+| Tool | What | Price |
+|------|------|-------|
+| `true402_token_report` | Composite **avoid/caution/ok** verdict — honeypot buy/sell simulation + liquidity + ownership + recent rug activity. Call **before buying**. | ~$0.01 |
+| `true402_token_safety` | Structural safety score 0–100 + flags (honeypot sim, liquidity, mint/ownership). | ~$0.005 |
+| `true402_address_safety` | Profile + risk for any address before you send/approve/call it (EOA vs contract, balances, proxy detection). | ~$0.005 |
+| `true402_deployer_check` | Deployer wallet reputation — age, contracts shipped, fresh-throwaway flag — to catch serial ruggers. | ~$0.008 |
+
+## Configuration
+
+`true402_tools()` reads the environment, or pass a `PayOpts`:
+
+```python
+from crewai_true402 import true402_tools, PayOpts
+
+tools = true402_tools(PayOpts(
+    payer_private_key="0x…",   # a Base wallet with a little USDC (gas is sponsored; USDC only)
+    max_amount_usd=0.10,        # hard per-call ceiling — refuses to sign a 402 demanding more
+))
+```
+
+| Env var | Default | Meaning |
+|---------|---------|---------|
+| `PAYER_PRIVATE_KEY` | — | Base wallet key that signs x402 payments (needs USDC, not ETH). Unset → free trial only. |
+| `TRUE402_BASE_URL` | `https://true402.dev/api` | Override to point at a self-hosted instance. |
+| `BASE_RPC_URL` | `https://mainnet.base.org` | Base RPC for the balance pre-check. |
+
+## Safety
+
+The client **refuses to sign** anything that isn't USDC-on-Base within `max_amount_usd` (default $0.10) — so a rogue or compromised endpoint can't make your agent authorize an unexpected asset, network, or amount. The private key is used only to sign locally; it never leaves the process.
+
+## Links
+
+- Live check in your browser: <https://true402.dev/check>
+- API reference: <https://true402.dev/docs/api> · OpenAPI: <https://true402.dev/openapi.json>
+- Also available: [LangChain](https://www.npmjs.com/package/@true402.dev/langchain) · [MCP server](https://www.npmjs.com/package/@true402.dev/mcp-server) · [CLI](https://www.npmjs.com/package/@true402.dev/rugcheck)
+
+## License
+
+MIT

crewai_true402-0.1.0/crewai_true402/__init__.py

@@ -0,0 +1,26 @@
+"""true402 tools for CrewAI — pay-per-call on-chain rug/honeypot & address safety for Base AI agents
+over x402 (USDC on Base, no account, no API key; the wallet is the identity).
+
+    from crewai_true402 import true402_tools
+    tools = true402_tools()
+"""
+from .tools import (
+    AddressSafetyTool,
+    DeployerCheckTool,
+    TokenReportTool,
+    TokenSafetyTool,
+    true402_tools,
+)
+from .x402 import PayOpts, pay_stall, sign_payment
+
+__version__ = "0.1.0"
+__all__ = [
+    "true402_tools",
+    "TokenReportTool",
+    "TokenSafetyTool",
+    "AddressSafetyTool",
+    "DeployerCheckTool",
+    "PayOpts",
+    "pay_stall",
+    "sign_payment",
+]

crewai_true402-0.1.0/crewai_true402/tools.py

@@ -0,0 +1,100 @@
+"""true402 tools for CrewAI — pay-per-call on-chain safety for Base agents over x402.
+
+    from crewai_true402 import true402_tools
+    tools = true402_tools()  # reads PAYER_PRIVATE_KEY from the env
+
+    agent = Agent(role="Trader", tools=tools, ...)
+"""
+from __future__ import annotations
+
+import json
+from typing import Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from .x402 import PayOpts, pay_stall
+
+
+class _TokenInput(BaseModel):
+    token: str = Field(..., description="A Base ERC-20 token contract address (0x…)")
+
+
+class _AddressInput(BaseModel):
+    address: str = Field(..., description="Any Base address (0x…) — an EOA or a contract")
+
+
+class _StallTool(BaseTool):
+    """Base for a true402 stall exposed as a CrewAI tool."""
+
+    path: str
+    input_key: str
+    opts: PayOpts
+
+    def _run(self, **kwargs) -> str:
+        value = kwargs.get(self.input_key)
+        result = pay_stall(self.path, {self.input_key: value}, self.opts)
+        return json.dumps(result)
+
+
+class TokenReportTool(_StallTool):
+    name: str = "true402_token_report"
+    description: str = (
+        "Pre-trade rug/honeypot check for a Base ERC-20: a composite avoid/caution/ok verdict from an "
+        "on-chain buy/sell honeypot simulation, liquidity depth, ownership/mint inspection, and recent "
+        "rug activity. Call BEFORE buying a token. ~$0.01 USDC over x402."
+    )
+    args_schema: Type[BaseModel] = _TokenInput
+    path: str = "/v1/base/token-report"
+    input_key: str = "token"
+
+
+class TokenSafetyTool(_StallTool):
+    name: str = "true402_token_safety"
+    description: str = (
+        "Structural safety score (0–100) + flags for a Base ERC-20: honeypot simulation, liquidity, "
+        "mint/ownership/blacklist. Lighter than token_report. ~$0.005 USDC over x402."
+    )
+    args_schema: Type[BaseModel] = _TokenInput
+    path: str = "/v1/token-safety"
+    input_key: str = "token"
+
+
+class AddressSafetyTool(_StallTool):
+    name: str = "true402_address_safety"
+    description: str = (
+        "Profile + risk for any Base address before you send to / approve / call it: EOA-vs-contract, "
+        "ETH+USDC balance, activity, ownership, and upgradeable-proxy (EIP-1967) detection. "
+        "~$0.005 USDC over x402."
+    )
+    args_schema: Type[BaseModel] = _AddressInput
+    path: str = "/v1/base/address-safety"
+    input_key: str = "address"
+
+
+class DeployerCheckTool(_StallTool):
+    name: str = "true402_deployer_check"
+    description: str = (
+        "Deployer reputation for a Base token: resolves who created it and that wallet's track record "
+        "(age, contracts shipped, fresh-throwaway flag) to catch serial ruggers a structural check "
+        "can't see. ~$0.008 USDC over x402."
+    )
+    args_schema: Type[BaseModel] = _TokenInput
+    path: str = "/v1/base/deployer-check"
+    input_key: str = "token"
+
+
+def true402_tools(opts: Optional[PayOpts] = None) -> list[BaseTool]:
+    """The four true402 safety tools, ready to hand to a CrewAI Agent.
+
+    Pass a PayOpts, or leave None to read PAYER_PRIVATE_KEY / TRUE402_BASE_URL / BASE_RPC_URL from the
+    environment. Stalls with a free daily trial (token safety/report, address safety) work even with no
+    wallet configured — they return a real result until the trial is exhausted, then require payment.
+    """
+    o = opts or PayOpts.from_env()
+    return [
+        TokenReportTool(opts=o),
+        TokenSafetyTool(opts=o),
+        AddressSafetyTool(opts=o),
+        DeployerCheckTool(opts=o),
+    ]

crewai_true402-0.1.0/crewai_true402/x402.py

@@ -0,0 +1,169 @@
+"""Pay any true402 stall over x402 and return its JSON.
+
+The whole protocol, in one function: POST → 402 with payment terms → sign an EIP-3009 USDC
+authorization → retry with an X-PAYMENT header → 200. No accounts, no API keys; the wallet is the
+identity. USDC on Base, gas sponsored by the facilitator (the payer needs only USDC, not ETH).
+
+Safety: the client REFUSES to sign anything that isn't USDC-on-Base within a caller-set cap, so a
+rogue/compromised endpoint (or a MITM past TLS) can't make the agent authorize an unexpected
+asset/network or an excessive amount.
+"""
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+BASE_NETWORK = "eip155:8453"
+BASE_CHAIN_ID = 8453
+DEFAULT_BASE_URL = "https://true402.dev/api"
+DEFAULT_RPC_URL = "https://mainnet.base.org"
+_BALANCE_OF_SELECTOR = "0x70a08231"
+
+
+@dataclass
+class PayOpts:
+    """Configuration for paying true402 stalls."""
+
+    payer_private_key: str
+    """A Base wallet private key holding a little USDC (the payer)."""
+    base_url: str = DEFAULT_BASE_URL
+    rpc_url: str = DEFAULT_RPC_URL
+    max_amount_usd: float = 0.10
+    """Hard ceiling, in USDC, on a single signed payment. The client refuses a 402 demanding more."""
+    timeout: float = 30.0
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "PayOpts":
+        """Build from PAYER_PRIVATE_KEY / TRUE402_BASE_URL / BASE_RPC_URL env vars."""
+        key = overrides.pop("payer_private_key", None) or os.environ.get("PAYER_PRIVATE_KEY", "")
+        return cls(
+            payer_private_key=key,
+            base_url=overrides.pop("base_url", None) or os.environ.get("TRUE402_BASE_URL", DEFAULT_BASE_URL),
+            rpc_url=overrides.pop("rpc_url", None) or os.environ.get("BASE_RPC_URL", DEFAULT_RPC_URL),
+            **overrides,
+        )
+
+
+def _usdc_balance(rpc_url: str, holder: str, timeout: float) -> int:
+    data = _BALANCE_OF_SELECTOR + holder[2:].rjust(64, "0")
+    body = {"jsonrpc": "2.0", "id": 1, "method": "eth_call", "params": [{"to": BASE_USDC, "data": data}, "latest"]}
+    r = requests.post(rpc_url, json=body, timeout=timeout, headers={"content-type": "application/json"})
+    r.raise_for_status()
+    return int(r.json()["result"], 16)
+
+
+def sign_payment(accept: dict, opts: PayOpts) -> str:
+    """Sign an EIP-3009 authorization for the given 402 `accepts[]` entry → base64 X-PAYMENT value."""
+    key = opts.payer_private_key
+    if not key:
+        raise ValueError("no payer_private_key set — cannot pay (set PAYER_PRIVATE_KEY or PayOpts.payer_private_key)")
+    if not key.startswith("0x"):
+        key = "0x" + key
+    account = Account.from_key(key)
+
+    network = accept.get("network")
+    if network and network != BASE_NETWORK:
+        raise ValueError(f'unexpected payment network "{network}" (expected {BASE_NETWORK}) — refusing to sign')
+    asset = accept.get("asset", "")
+    if asset.lower() != BASE_USDC.lower():
+        raise ValueError(f"unexpected payment asset {asset} (expected Base USDC) — refusing to sign")
+
+    value = int(accept.get("amount") or accept.get("maxAmountRequired") or "0")
+    cap_atomic = round(opts.max_amount_usd * 1e6)
+    if value > cap_atomic:
+        raise ValueError(f"402 demands {value} USDC base units, over the ${opts.max_amount_usd} cap — refusing to sign")
+
+    held = _usdc_balance(opts.rpc_url, account.address, opts.timeout)
+    if held < value:
+        raise ValueError(f"payer {account.address} holds {held} < {value} USDC base units — fund it")
+
+    now = int(time.time())
+    valid_before = now + int(accept.get("maxTimeoutSeconds") or 120)
+    nonce = "0x" + secrets.token_hex(32)
+    extra = accept.get("extra") or {}
+    authorization = {
+        "from": account.address,
+        "to": accept["payTo"],
+        "value": value,
+        "validAfter": now - 60,
+        "validBefore": valid_before,
+        "nonce": bytes.fromhex(nonce[2:]),
+    }
+    signable = encode_typed_data(
+        domain_data={
+            "name": extra.get("name", "USD Coin"),
+            "version": extra.get("version", "2"),
+            "chainId": BASE_CHAIN_ID,
+            "verifyingContract": BASE_USDC,
+        },
+        message_types={
+            "TransferWithAuthorization": [
+                {"name": "from", "type": "address"},
+                {"name": "to", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "validAfter", "type": "uint256"},
+                {"name": "validBefore", "type": "uint256"},
+                {"name": "nonce", "type": "bytes32"},
+            ],
+        },
+        message_data=authorization,
+    )
+    signature = Account.sign_message(signable, key).signature.hex()
+    if not signature.startswith("0x"):
+        signature = "0x" + signature
+
+    payment = {
+        "x402Version": 2,
+        "scheme": "exact",
+        "network": network,
+        "payload": {
+            "signature": signature,
+            "authorization": {
+                "from": authorization["from"],
+                "to": authorization["to"],
+                "value": str(value),
+                "validAfter": str(authorization["validAfter"]),
+                "validBefore": str(authorization["validBefore"]),
+                "nonce": nonce,
+            },
+        },
+    }
+    import base64
+
+    return base64.b64encode(json.dumps(payment).encode()).decode()
+
+
+def pay_stall(path: str, payload: dict, opts: PayOpts) -> Any:
+    """POST `payload` to a true402 stall path (e.g. '/v1/base/token-report'), paying over x402 if asked.
+
+    If the first response is 200 (a free-trial call), returns it without paying. If it's 402, signs and
+    retries. Raises on any other status or on a refused/insufficient payment.
+    """
+    url = opts.base_url.rstrip("/") + path
+    headers = {"content-type": "application/json"}
+    first = requests.post(url, json=payload, headers=headers, timeout=opts.timeout)
+    if first.status_code == 200:
+        return first.json()  # served free (free trial) — no payment needed
+    if first.status_code != 402:
+        raise RuntimeError(f"expected HTTP 402 from {path}, got {first.status_code}: {first.text[:200]}")
+
+    challenge = first.json()
+    accepts = challenge.get("accepts") or []
+    accept = next((a for a in accepts if a.get("scheme") == "exact"), None)
+    if not accept:
+        raise RuntimeError('no x402 "exact" payment requirement in the 402')
+
+    x_payment = sign_payment(accept, opts)
+    paid = requests.post(url, json=payload, headers={**headers, "X-PAYMENT": x_payment}, timeout=opts.timeout)
+    if paid.status_code != 200:
+        raise RuntimeError(f"paid request to {path} failed (HTTP {paid.status_code}): {paid.text[:200]}")
+    return paid.json()

crewai_true402-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-true402"
+version = "0.1.0"
+description = "true402 tools for CrewAI — pay-per-call on-chain rug/honeypot & address safety for Base AI agents over x402 (USDC, no account, no API key)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["crewai", "crewai-tools", "x402", "base", "rug-check", "honeypot", "token-safety", "crypto", "ai-agent", "agent-tools", "defi", "web3"]
+authors = [{ name = "true402", email = "contact@true402.dev" }]
+dependencies = [
+    "requests>=2.28",
+    "eth-account>=0.11",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+crewai = ["crewai>=0.30"]
+
+[project.urls]
+Homepage = "https://true402.dev"
+Source = "https://github.com/true402/crewai-true402"
+"OpenAPI" = "https://true402.dev/openapi.json"
+
+[tool.hatch.build.targets.wheel]
+packages = ["crewai_true402"]