langchain-clawfetch 0.1.0__tar.gz

langchain_clawfetch-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/

langchain_clawfetch-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.1.0] - 2026-10-18
+
+### Added
+- Initial release: `ClawFetchFetch`, `ClawFetchRender`, `ClawFetchExtract`, `ClawFetchResearch`, `ClawFetchParse`, `ClawFetchDomainsCheck`, `ClawFetchDomainsSuggest` tools (sync and async) and `ClawFetchToolkit`.

langchain_clawfetch-0.1.0/LICENSE

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

langchain_clawfetch-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: langchain-clawfetch
+Version: 0.1.0
+Summary: LangChain tools for ClawFetch — pay-per-call web intelligence for AI agents (x402, USDC on Base)
+Project-URL: Homepage, https://api.clawfetch.ai
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,clawfetch,langchain,tools,web-scraping,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: clawfetch<0.3,>=0.2.2
+Requires-Dist: langchain-core<2,>=0.3
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-clawfetch
+
+LangChain tools for [ClawFetch](https://api.clawfetch.ai), a pay-per-call web intelligence API for AI agents. Each call is paid with an x402 micropayment in USDC on Base.
+
+## Install
+
+```bash
+pip install langchain-clawfetch
+```
+
+## Wallet
+
+You need a Base wallet private key that holds USDC. There is no API key and no signup. Payments are gasless EIP-3009 transfers signed locally by the [`clawfetch`](https://pypi.org/project/clawfetch/) SDK, so the wallet does not need ETH. Use a dedicated wallet with a small balance.
+
+```bash
+export CLAWFETCH_PRIVATE_KEY=0x...
+```
+
+## Quickstart
+
+```python
+from langchain_clawfetch import ClawFetchToolkit
+
+tools = ClawFetchToolkit().get_tools()  # reads CLAWFETCH_PRIVATE_KEY
+# or: ClawFetchToolkit(private_key="0x...", max_chars=8000)
+
+fetch = tools[0]
+print(fetch.invoke({"url": "https://example.com"}))
+```
+
+To use the tools with an agent:
+
+```python
+from langchain.agents import create_agent
+
+agent = create_agent(llm, tools=tools)  # llm: any LangChain chat model
+agent.invoke({"messages": [{"role": "user", "content": "What's new on news.ycombinator.com?"}]})
+```
+
+You can also create a single tool, or pass an existing client:
+
+```python
+from clawfetch import ClawFetch, AsyncClawFetch
+from langchain_clawfetch import ClawFetchResearch
+
+research = ClawFetchResearch(client=ClawFetch(private_key="0x..."), async_client=AsyncClawFetch(private_key="0x..."))
+```
+
+Every tool supports `invoke` and `ainvoke`. Async calls use `AsyncClawFetch`.
+
+## Tools
+
+| Tool | Name | Price per call | What it does |
+|---|---|---|---|
+| `ClawFetchFetch` | `clawfetch_fetch` | $0.001 | URL to readable text (no JavaScript) |
+| `ClawFetchRender` | `clawfetch_render` | $0.005 | JavaScript-rendered page to text |
+| `ClawFetchExtract` | `clawfetch_extract` | $0.008 | Typed JSON from 17 supported sites |
+| `ClawFetchResearch` | `clawfetch_research` | $0.02 | Web search plus source texts for citations |
+| `ClawFetchParse` | `clawfetch_parse` | $0.005 | Office document or PDF at a URL to Markdown (no OCR) |
+| `ClawFetchDomainsCheck` | `clawfetch_domains_check` | $0.003 | Domain availability |
+| `ClawFetchDomainsSuggest` | `clawfetch_domains_suggest` | $0.003 | Generate and check domain names from keywords |
+
+Supported `clawfetch_extract` sites: twitter, coingecko, github, news, npm, pypi, crates, hackernews, youtube, wikipedia, producthunt, imdb, amazon, crunchbase, sec-edgar, zillow, redfin.
+
+## Output and errors
+
+Tools return a string. Fetch and render return the page title, URL and text. Parse returns Markdown. The other tools return the API response as JSON. Output is cut at `max_chars` (default 10,000).
+
+SDK errors (`PaymentError`, `RateLimitError`, `ApiError`, `NetworkError`) are raised as `ToolException`. To hand the message to the model instead of raising, pass `handle_tool_error=True` when you create a tool.
+
+## License
+
+MIT

langchain_clawfetch-0.1.0/README.md

@@ -0,0 +1,73 @@
+# langchain-clawfetch
+
+LangChain tools for [ClawFetch](https://api.clawfetch.ai), a pay-per-call web intelligence API for AI agents. Each call is paid with an x402 micropayment in USDC on Base.
+
+## Install
+
+```bash
+pip install langchain-clawfetch
+```
+
+## Wallet
+
+You need a Base wallet private key that holds USDC. There is no API key and no signup. Payments are gasless EIP-3009 transfers signed locally by the [`clawfetch`](https://pypi.org/project/clawfetch/) SDK, so the wallet does not need ETH. Use a dedicated wallet with a small balance.
+
+```bash
+export CLAWFETCH_PRIVATE_KEY=0x...
+```
+
+## Quickstart
+
+```python
+from langchain_clawfetch import ClawFetchToolkit
+
+tools = ClawFetchToolkit().get_tools()  # reads CLAWFETCH_PRIVATE_KEY
+# or: ClawFetchToolkit(private_key="0x...", max_chars=8000)
+
+fetch = tools[0]
+print(fetch.invoke({"url": "https://example.com"}))
+```
+
+To use the tools with an agent:
+
+```python
+from langchain.agents import create_agent
+
+agent = create_agent(llm, tools=tools)  # llm: any LangChain chat model
+agent.invoke({"messages": [{"role": "user", "content": "What's new on news.ycombinator.com?"}]})
+```
+
+You can also create a single tool, or pass an existing client:
+
+```python
+from clawfetch import ClawFetch, AsyncClawFetch
+from langchain_clawfetch import ClawFetchResearch
+
+research = ClawFetchResearch(client=ClawFetch(private_key="0x..."), async_client=AsyncClawFetch(private_key="0x..."))
+```
+
+Every tool supports `invoke` and `ainvoke`. Async calls use `AsyncClawFetch`.
+
+## Tools
+
+| Tool | Name | Price per call | What it does |
+|---|---|---|---|
+| `ClawFetchFetch` | `clawfetch_fetch` | $0.001 | URL to readable text (no JavaScript) |
+| `ClawFetchRender` | `clawfetch_render` | $0.005 | JavaScript-rendered page to text |
+| `ClawFetchExtract` | `clawfetch_extract` | $0.008 | Typed JSON from 17 supported sites |
+| `ClawFetchResearch` | `clawfetch_research` | $0.02 | Web search plus source texts for citations |
+| `ClawFetchParse` | `clawfetch_parse` | $0.005 | Office document or PDF at a URL to Markdown (no OCR) |
+| `ClawFetchDomainsCheck` | `clawfetch_domains_check` | $0.003 | Domain availability |
+| `ClawFetchDomainsSuggest` | `clawfetch_domains_suggest` | $0.003 | Generate and check domain names from keywords |
+
+Supported `clawfetch_extract` sites: twitter, coingecko, github, news, npm, pypi, crates, hackernews, youtube, wikipedia, producthunt, imdb, amazon, crunchbase, sec-edgar, zillow, redfin.
+
+## Output and errors
+
+Tools return a string. Fetch and render return the page title, URL and text. Parse returns Markdown. The other tools return the API response as JSON. Output is cut at `max_chars` (default 10,000).
+
+SDK errors (`PaymentError`, `RateLimitError`, `ApiError`, `NetworkError`) are raised as `ToolException`. To hand the message to the model instead of raising, pass `handle_tool_error=True` when you create a tool.
+
+## License
+
+MIT

langchain_clawfetch-0.1.0/langchain_clawfetch/__init__.py

@@ -0,0 +1,24 @@
+"""LangChain integration for ClawFetch — pay-per-call web intelligence for AI agents."""
+
+from langchain_clawfetch.tools import (
+    ClawFetchDomainsCheck,
+    ClawFetchDomainsSuggest,
+    ClawFetchExtract,
+    ClawFetchFetch,
+    ClawFetchParse,
+    ClawFetchRender,
+    ClawFetchResearch,
+    ClawFetchToolkit,
+)
+
+__all__ = [
+    "ClawFetchFetch",
+    "ClawFetchRender",
+    "ClawFetchExtract",
+    "ClawFetchResearch",
+    "ClawFetchParse",
+    "ClawFetchDomainsCheck",
+    "ClawFetchDomainsSuggest",
+    "ClawFetchToolkit",
+]
+__version__ = "0.1.0"

langchain_clawfetch-0.1.0/langchain_clawfetch/tools.py

@@ -0,0 +1,272 @@
+"""LangChain tools for the ClawFetch web intelligence API (x402, USDC on Base)."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, List, Optional, Tuple, Type
+
+from clawfetch import AsyncClawFetch, ClawFetch, ClawFetchError
+from langchain_core.tools import BaseTool, BaseToolkit, ToolException
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+DEFAULT_MAX_CHARS = 10_000
+
+EXTRACT_TYPES = (
+    "twitter, coingecko, github, news, npm, pypi, crates, hackernews, youtube, "
+    "wikipedia, producthunt, imdb, amazon, crunchbase, sec-edgar, zillow, redfin"
+)
+
+
+def _make_clients(private_key: Optional[SecretStr]) -> Tuple[ClawFetch, AsyncClawFetch]:
+    key = private_key.get_secret_value() if private_key else os.environ.get("CLAWFETCH_PRIVATE_KEY")
+    if not key:
+        raise ValueError("Pass private_key=..., set CLAWFETCH_PRIVATE_KEY, or pass client=ClawFetch(...).")
+    return ClawFetch(private_key=key), AsyncClawFetch(private_key=key)
+
+
+def _truncate(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + f"\n...[truncated {len(text) - max_chars} chars]"
+
+
+def _json(result: Any) -> str:
+    return json.dumps(result, ensure_ascii=False)
+
+
+def _page(result: dict) -> str:
+    """Format a /fetch or /render result as markdown-ish text."""
+    title = result.get("title") or ""
+    url = result.get("url") or ""
+    text = result.get("text") or ""
+    return f"# {title}\nURL: {url}\n\n{text}"
+
+
+# ─── Input schemas ────────────────────────────────────────────────
+
+
+class FetchInput(BaseModel):
+    url: str = Field(description="Absolute http(s) URL of the page to fetch.")
+
+
+class RenderInput(BaseModel):
+    url: str = Field(description="Absolute http(s) URL of the JavaScript-heavy page.")
+    wait_for: Optional[str] = Field(
+        default=None, description="Optional CSS selector to wait for before reading the page."
+    )
+
+
+class ExtractInput(BaseModel):
+    url: str = Field(description="URL on a supported site (e.g. a GitHub repo or CoinGecko coin page).")
+    type: Optional[str] = Field(
+        default=None,
+        description=f"Optional extractor name; auto-detected from the URL when omitted. One of: {EXTRACT_TYPES}.",
+    )
+
+
+class ResearchInput(BaseModel):
+    query: str = Field(description="Research question or topic.")
+    max_results: Optional[int] = Field(
+        default=None, ge=1, le=10, description="Number of sources to read (1-10, default 5)."
+    )
+
+
+class ParseInput(BaseModel):
+    url: str = Field(description="Absolute http(s) URL of an office document or PDF.")
+    format: Optional[str] = Field(
+        default=None,
+        description="Optional format override (doc, docx, odt, pdf, ppt, pptx, rtf, epub, xlsx, ods, odp, csv).",
+    )
+
+
+class DomainsCheckInput(BaseModel):
+    domains: List[str] = Field(description="Fully qualified domain names to check, e.g. ['acme.ai', 'acme.com'] (max 20).")
+
+
+class DomainsSuggestInput(BaseModel):
+    keywords: List[str] = Field(description="Keywords to combine into domain names, e.g. ['agent', 'grid'].")
+    tlds: Optional[List[str]] = Field(
+        default=None, description="TLDs to try without dots, e.g. ['com', 'ai']. Default: com, ai, io."
+    )
+    max_check: Optional[int] = Field(
+        default=None, ge=1, le=50, description="How many generated names to check for availability (1-50, default 30)."
+    )
+
+
+# ─── Tools ────────────────────────────────────────────────────────
+
+
+class _ClawFetchTool(BaseTool):
+    """Shared client wiring, error mapping and output formatting."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    private_key: Optional[SecretStr] = Field(default=None, exclude=True)
+    client: Optional[ClawFetch] = Field(default=None, exclude=True)
+    async_client: Optional[AsyncClawFetch] = Field(default=None, exclude=True)
+    max_chars: int = DEFAULT_MAX_CHARS
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.client is None and self.async_client is None:
+            self.client, self.async_client = _make_clients(self.private_key)
+
+    def _invoke(self, client: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _format(self, result: Any) -> str:
+        return _json(result)
+
+    def _run(self, run_manager: Any = None, **kwargs: Any) -> str:
+        if self.client is None:
+            raise ToolException(f"{self.name}: no sync ClawFetch client configured; use the async API.")
+        try:
+            result = self._invoke(self.client, **kwargs)
+        except ClawFetchError as exc:
+            raise ToolException(f"{self.name} failed ({type(exc).__name__}): {exc}") from exc
+        return _truncate(self._format(result), self.max_chars)
+
+    async def _arun(self, run_manager: Any = None, **kwargs: Any) -> str:
+        if self.async_client is None:
+            return await super()._arun(**kwargs)
+        try:
+            result = await self._invoke(self.async_client, **kwargs)
+        except ClawFetchError as exc:
+            raise ToolException(f"{self.name} failed ({type(exc).__name__}): {exc}") from exc
+        return _truncate(self._format(result), self.max_chars)
+
+
+class ClawFetchFetch(_ClawFetchTool):
+    name: str = "clawfetch_fetch"
+    description: str = (
+        "Fetch a web page and return its readable text with title and URL. "
+        "Fast, no JavaScript execution; use clawfetch_render for JS-heavy pages. "
+        "Costs $0.001 USDC per call."
+    )
+    args_schema: Type[BaseModel] = FetchInput
+
+    def _invoke(self, client: Any, url: str) -> Any:
+        return client.fetch(url, max_chars=self.max_chars)
+
+    def _format(self, result: Any) -> str:
+        return _page(result)
+
+
+class ClawFetchRender(_ClawFetchTool):
+    name: str = "clawfetch_render"
+    description: str = (
+        "Render a JavaScript-heavy page in a headless browser and return its visible text. "
+        "Use when clawfetch_fetch returns empty or incomplete content. Costs $0.005 USDC per call."
+    )
+    args_schema: Type[BaseModel] = RenderInput
+
+    def _invoke(self, client: Any, url: str, wait_for: Optional[str] = None) -> Any:
+        return client.render(url, max_chars=self.max_chars, wait_for=wait_for)
+
+    def _format(self, result: Any) -> str:
+        return _page(result)
+
+
+class ClawFetchExtract(_ClawFetchTool):
+    name: str = "clawfetch_extract"
+    description: str = (
+        "Extract typed structured data (JSON) from a page on a supported site: "
+        f"{EXTRACT_TYPES}. Costs $0.008 USDC per call."
+    )
+    args_schema: Type[BaseModel] = ExtractInput
+
+    def _invoke(self, client: Any, url: str, type: Optional[str] = None) -> Any:
+        return client.extract(url, type=type)
+
+
+class ClawFetchResearch(_ClawFetchTool):
+    name: str = "clawfetch_research"
+    description: str = (
+        "Search the web for a query and return the text of the top sources with their URLs "
+        "(for citations). Costs $0.02 USDC per call."
+    )
+    args_schema: Type[BaseModel] = ResearchInput
+
+    def _invoke(self, client: Any, query: str, max_results: Optional[int] = None) -> Any:
+        return client.research(query, max_results=max_results)
+
+
+class ClawFetchParse(_ClawFetchTool):
+    name: str = "clawfetch_parse"
+    description: str = (
+        "Convert an office document or PDF at a URL (docx, pptx, xlsx, pdf, odt, rtf, epub, csv, ...) "
+        "to Markdown. No OCR: scanned PDFs fail. Costs $0.005 USDC per call."
+    )
+    args_schema: Type[BaseModel] = ParseInput
+
+    def _invoke(self, client: Any, url: str, format: Optional[str] = None) -> Any:
+        return client.parse(url, format=format)
+
+    def _format(self, result: Any) -> str:
+        return result.get("markdown") or ""
+
+
+class ClawFetchDomainsCheck(_ClawFetchTool):
+    name: str = "clawfetch_domains_check"
+    description: str = (
+        "Check whether specific domain names are available to register. Returns JSON with a "
+        "result per domain (available true/false, or null with an error). Costs $0.003 USDC per call."
+    )
+    args_schema: Type[BaseModel] = DomainsCheckInput
+
+    def _invoke(self, client: Any, domains: List[str]) -> Any:
+        return client.domains_check(domains)
+
+
+class ClawFetchDomainsSuggest(_ClawFetchTool):
+    name: str = "clawfetch_domains_suggest"
+    description: str = (
+        "Generate domain names from keywords and check which are available. Returns JSON with the "
+        "list of available domains and every checked result. Costs $0.003 USDC per call."
+    )
+    args_schema: Type[BaseModel] = DomainsSuggestInput
+
+    def _invoke(
+        self,
+        client: Any,
+        keywords: List[str],
+        tlds: Optional[List[str]] = None,
+        max_check: Optional[int] = None,
+    ) -> Any:
+        return client.domains_suggest(keywords, tlds=tlds, max_check=max_check)
+
+
+TOOL_CLASSES = (
+    ClawFetchFetch,
+    ClawFetchRender,
+    ClawFetchExtract,
+    ClawFetchResearch,
+    ClawFetchParse,
+    ClawFetchDomainsCheck,
+    ClawFetchDomainsSuggest,
+)
+
+
+class ClawFetchToolkit(BaseToolkit):
+    """All ClawFetch tools sharing one sync and one async client.
+
+    Build from ``private_key=`` (or the ``CLAWFETCH_PRIVATE_KEY`` env var), or
+    pass existing ``client=`` / ``async_client=`` instances.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    private_key: Optional[SecretStr] = Field(default=None, exclude=True)
+    client: Optional[ClawFetch] = Field(default=None, exclude=True)
+    async_client: Optional[AsyncClawFetch] = Field(default=None, exclude=True)
+    max_chars: int = DEFAULT_MAX_CHARS
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.client is None and self.async_client is None:
+            self.client, self.async_client = _make_clients(self.private_key)
+
+    def get_tools(self) -> List[BaseTool]:
+        return [
+            cls(client=self.client, async_client=self.async_client, max_chars=self.max_chars)
+            for cls in TOOL_CLASSES
+        ]

langchain_clawfetch-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-clawfetch"
+version = "0.1.0"
+description = "LangChain tools for ClawFetch — pay-per-call web intelligence for AI agents (x402, USDC on Base)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["langchain", "clawfetch", "x402", "web-scraping", "ai-agents", "tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "clawfetch>=0.2.2,<0.3",
+    "langchain-core>=0.3,<2",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[project.urls]
+Homepage = "https://api.clawfetch.ai"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_clawfetch"]
+
+[tool.hatch.build.targets.sdist]
+include = ["langchain_clawfetch/", "tests/", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

langchain_clawfetch-0.1.0/tests/test_tools.py

@@ -0,0 +1,129 @@
+"""Unit tests — the ClawFetch client is mocked: no network, no payments."""
+
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from clawfetch import AsyncClawFetch, ClawFetch, PaymentError
+from langchain_core.tools import ToolException
+
+from langchain_clawfetch import (
+    ClawFetchDomainsCheck,
+    ClawFetchDomainsSuggest,
+    ClawFetchExtract,
+    ClawFetchFetch,
+    ClawFetchParse,
+    ClawFetchRender,
+    ClawFetchResearch,
+    ClawFetchToolkit,
+)
+
+DUMMY_KEY = "0x0000000000000000000000000000000000000000000000000000000000000001"
+PAGE = {"url": "https://a.b", "title": "T", "text": "hello"}
+
+# (tool class, tool input, sdk method, expected positional args, expected kwargs, sdk result, expected output)
+CASES = [
+    (ClawFetchFetch, {"url": "https://a.b"}, "fetch", ("https://a.b",), {"max_chars": 10_000},
+     PAGE, "# T\nURL: https://a.b\n\nhello"),
+    (ClawFetchRender, {"url": "https://a.b", "wait_for": "#app"}, "render", ("https://a.b",),
+     {"max_chars": 10_000, "wait_for": "#app"}, PAGE, "# T\nURL: https://a.b\n\nhello"),
+    (ClawFetchExtract, {"url": "https://github.com/a/b"}, "extract", ("https://github.com/a/b",),
+     {"type": None}, {"type": "github", "stars": 1}, json.dumps({"type": "github", "stars": 1})),
+    (ClawFetchResearch, {"query": "x402", "max_results": 3}, "research", ("x402",), {"max_results": 3},
+     {"query": "x402", "sources": 0, "results": []}, json.dumps({"query": "x402", "sources": 0, "results": []})),
+    (ClawFetchParse, {"url": "https://a.b/x.docx"}, "parse", ("https://a.b/x.docx",), {"format": None},
+     {"markdown": "# Doc", "format": "docx", "chars": 5}, "# Doc"),
+    (ClawFetchDomainsCheck, {"domains": ["a.ai"]}, "domains_check", (["a.ai"],), {},
+     {"checked": 1, "available": 1, "taken": 0, "results": [{"domain": "a.ai", "available": True}]},
+     json.dumps({"checked": 1, "available": 1, "taken": 0, "results": [{"domain": "a.ai", "available": True}]})),
+    (ClawFetchDomainsSuggest, {"keywords": ["agent"], "tlds": ["ai"], "max_check": 5}, "domains_suggest",
+     (["agent"],), {"tlds": ["ai"], "max_check": 5},
+     {"keywords": ["agent"], "available": ["agent.ai"]}, json.dumps({"keywords": ["agent"], "available": ["agent.ai"]})),
+]
+
+
+def _clients():
+    return MagicMock(spec=ClawFetch), MagicMock(spec=AsyncClawFetch)
+
+
+@pytest.mark.parametrize("cls,tool_input,method,args,kwargs,result,expected", CASES)
+def test_sync_tool_calls_sdk_and_formats(cls, tool_input, method, args, kwargs, result, expected):
+    client, aclient = _clients()
+    getattr(client, method).return_value = result
+    tool = cls(client=client, async_client=aclient)
+    assert tool.invoke(tool_input) == expected
+    getattr(client, method).assert_called_once_with(*args, **kwargs)
+
+
+@pytest.mark.parametrize("cls,tool_input,method,args,kwargs,result,expected", CASES)
+async def test_async_tool_calls_async_sdk(cls, tool_input, method, args, kwargs, result, expected):
+    client, aclient = _clients()
+    setattr(aclient, method, AsyncMock(return_value=result))
+    tool = cls(client=client, async_client=aclient)
+    assert await tool.ainvoke(tool_input) == expected
+    getattr(aclient, method).assert_awaited_once_with(*args, **kwargs)
+    getattr(client, method).assert_not_called()
+
+
+async def test_async_falls_back_to_sync_client():
+    client = MagicMock(spec=ClawFetch)
+    client.fetch.return_value = PAGE
+    tool = ClawFetchFetch(client=client)
+    assert await tool.ainvoke({"url": "https://a.b"}) == "# T\nURL: https://a.b\n\nhello"
+
+
+def test_output_truncated_to_max_chars():
+    client, aclient = _clients()
+    client.parse.return_value = {"markdown": "x" * 50}
+    out = ClawFetchParse(client=client, async_client=aclient, max_chars=10).invoke({"url": "https://a.b/x.pdf"})
+    assert out == "x" * 10 + "\n...[truncated 40 chars]"
+
+
+def test_sdk_error_becomes_tool_exception():
+    client, aclient = _clients()
+    client.research.side_effect = PaymentError("insufficient USDC", endpoint="/research")
+    with pytest.raises(ToolException, match="clawfetch_research failed \\(PaymentError\\): insufficient USDC"):
+        ClawFetchResearch(client=client, async_client=aclient).invoke({"query": "x"})
+
+
+def test_sdk_error_returned_as_text_when_handle_tool_error():
+    client, aclient = _clients()
+    client.fetch.side_effect = PaymentError("insufficient USDC", endpoint="/fetch")
+    tool = ClawFetchFetch(client=client, async_client=aclient, handle_tool_error=True)
+    assert "insufficient USDC" in tool.invoke({"url": "https://a.b"})
+
+
+def test_tool_metadata():
+    client, aclient = _clients()
+    tools = ClawFetchToolkit(client=client, async_client=aclient).get_tools()
+    assert [t.name for t in tools] == [
+        "clawfetch_fetch", "clawfetch_render", "clawfetch_extract", "clawfetch_research",
+        "clawfetch_parse", "clawfetch_domains_check", "clawfetch_domains_suggest",
+    ]
+    for t in tools:
+        assert "$0." in t.description and "USDC" in t.description
+        assert t.client is client and t.async_client is aclient
+
+
+def test_toolkit_from_private_key():
+    tools = ClawFetchToolkit(private_key=DUMMY_KEY, max_chars=500).get_tools()
+    assert isinstance(tools[0].client, ClawFetch)
+    assert isinstance(tools[0].async_client, AsyncClawFetch)
+    assert tools[0].client is tools[-1].client
+    assert all(t.max_chars == 500 for t in tools)
+
+
+def test_toolkit_from_env(monkeypatch):
+    monkeypatch.setenv("CLAWFETCH_PRIVATE_KEY", DUMMY_KEY)
+    assert isinstance(ClawFetchFetch().client, ClawFetch)
+
+
+def test_missing_key_raises(monkeypatch):
+    monkeypatch.delenv("CLAWFETCH_PRIVATE_KEY", raising=False)
+    with pytest.raises(ValueError, match="CLAWFETCH_PRIVATE_KEY"):
+        ClawFetchToolkit()
+
+
+def test_private_key_not_serialized():
+    tool = ClawFetchFetch(private_key=DUMMY_KEY)
+    assert DUMMY_KEY not in repr(tool) and DUMMY_KEY not in str(tool.model_dump())