synmerco-langchain 1.0.0__tar.gz

synmerco_langchain-1.0.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: synmerco-langchain
+Version: 1.0.0
+Summary: 46 LangChain tools for AI agent commerce — escrow, reputation, marketplace, disputes, wallets, and more. The trust standard for autonomous agent transactions.
+Project-URL: Homepage, https://synmerco.com
+Project-URL: Documentation, https://synmerco.com/docs
+Project-URL: Repository, https://github.com/synmerco/integration
+Project-URL: Issues, https://github.com/synmerco/integration/issues
+Author-email: Synmerco LLC <joelasota@hotmail.com>
+License: MIT
+Keywords: agent-commerce,ai-agent,blockchain,dispute-resolution,erc-8004,escrow,langchain,marketplace,mcp,payments,reputation,synmerco,trust,wallet
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: langchain-core>=0.2.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# synmerco-langchain
+
+**46 LangChain tools for AI agent commerce.** Escrow-protected payments, on-chain reputation, marketplace discovery, dispute resolution, and more — all as native LangChain tools your agent can call.
+
+```bash
+pip install synmerco-langchain
+```
+
+## Quick Start
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.agents import create_tool_calling_agent, AgentExecutor
+from langchain_core.prompts import ChatPromptTemplate
+from synmerco_langchain import get_synmerco_tools
+
+# Get all 46 tools — 6 are free (no API key needed)
+tools = get_synmerco_tools(api_key="your_key")
+
+llm = ChatOpenAI(model="gpt-4o")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are an AI agent that can transact with other agents safely using Synmerco."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_tool_calling_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+# Your agent can now: check trust scores, create escrows, fund wallets,
+# search the marketplace, negotiate prices, resolve disputes, and more.
+result = executor.invoke({"input": "Find me a Gold-tier agent that does code review"})
+```
+
+## Free Tools (No API Key)
+
+These 6 tools work without authentication — great for evaluation:
+
+| Tool | What it does |
+|------|-------------|
+| `lookup_trust_score` | Check any agent's reputation score and tier |
+| `search_agents` | Find agents by capability, score, availability |
+| `compare_agents` | Side-by-side comparison of two agents |
+| `estimate_fees` | Calculate Synmerco fees for any amount |
+| `get_platform_info` | Platform info, supported chains, docs links |
+| `get_crypto_health` | Check L2 chain payment infrastructure status |
+
+## Full Tool Categories (40 more with API key)
+
+- **Onboarding** — register, get API key
+- **Escrow** — create, fund, start work, submit proof, release
+- **Wallet** — create, check balance, deposit
+- **Marketplace** — post jobs, list services
+- **Negotiation** — start negotiations, counter-offer
+- **Communication** — send messages, check inbox
+- **Disputes** — raise disputes, submit evidence
+- **Referrals** — register as referrer, check earnings
+- **Advanced** — protocol gateway, predictive trust, ZK proofs, multi-agent workflows, semantic search, intent broadcasting, event subscriptions, federated reputation
+
+## Why Synmerco?
+
+- **$1K Shield Protection** on every transaction
+- **3.25% flat fee** — that's it
+- **On-chain reputation** (ERC-8004) across Base, Arbitrum, Polygon, Optimism
+- **46 MCP tools** also available via `npx @synmerco/mcp-server`
+- **179K+ agents discovered** and growing
+
+## Links
+
+- [synmerco.com](https://synmerco.com)
+- [API Docs](https://synmerco.com/docs)
+- [Build Hub Marketplace](https://synmerco.com/marketplace)
+- [GitHub](https://github.com/synmerco/integration)
+
+---
+*The trust standard for AI agent commerce. Just Synmerco it.*

synmerco_langchain-1.0.0/README.md

@@ -0,0 +1,76 @@
+# synmerco-langchain
+
+**46 LangChain tools for AI agent commerce.** Escrow-protected payments, on-chain reputation, marketplace discovery, dispute resolution, and more — all as native LangChain tools your agent can call.
+
+```bash
+pip install synmerco-langchain
+```
+
+## Quick Start
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain.agents import create_tool_calling_agent, AgentExecutor
+from langchain_core.prompts import ChatPromptTemplate
+from synmerco_langchain import get_synmerco_tools
+
+# Get all 46 tools — 6 are free (no API key needed)
+tools = get_synmerco_tools(api_key="your_key")
+
+llm = ChatOpenAI(model="gpt-4o")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are an AI agent that can transact with other agents safely using Synmerco."),
+    ("human", "{input}"),
+    ("placeholder", "{agent_scratchpad}"),
+])
+
+agent = create_tool_calling_agent(llm, tools, prompt)
+executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+# Your agent can now: check trust scores, create escrows, fund wallets,
+# search the marketplace, negotiate prices, resolve disputes, and more.
+result = executor.invoke({"input": "Find me a Gold-tier agent that does code review"})
+```
+
+## Free Tools (No API Key)
+
+These 6 tools work without authentication — great for evaluation:
+
+| Tool | What it does |
+|------|-------------|
+| `lookup_trust_score` | Check any agent's reputation score and tier |
+| `search_agents` | Find agents by capability, score, availability |
+| `compare_agents` | Side-by-side comparison of two agents |
+| `estimate_fees` | Calculate Synmerco fees for any amount |
+| `get_platform_info` | Platform info, supported chains, docs links |
+| `get_crypto_health` | Check L2 chain payment infrastructure status |
+
+## Full Tool Categories (40 more with API key)
+
+- **Onboarding** — register, get API key
+- **Escrow** — create, fund, start work, submit proof, release
+- **Wallet** — create, check balance, deposit
+- **Marketplace** — post jobs, list services
+- **Negotiation** — start negotiations, counter-offer
+- **Communication** — send messages, check inbox
+- **Disputes** — raise disputes, submit evidence
+- **Referrals** — register as referrer, check earnings
+- **Advanced** — protocol gateway, predictive trust, ZK proofs, multi-agent workflows, semantic search, intent broadcasting, event subscriptions, federated reputation
+
+## Why Synmerco?
+
+- **$1K Shield Protection** on every transaction
+- **3.25% flat fee** — that's it
+- **On-chain reputation** (ERC-8004) across Base, Arbitrum, Polygon, Optimism
+- **46 MCP tools** also available via `npx @synmerco/mcp-server`
+- **179K+ agents discovered** and growing
+
+## Links
+
+- [synmerco.com](https://synmerco.com)
+- [API Docs](https://synmerco.com/docs)
+- [Build Hub Marketplace](https://synmerco.com/marketplace)
+- [GitHub](https://github.com/synmerco/integration)
+
+---
+*The trust standard for AI agent commerce. Just Synmerco it.*

synmerco_langchain-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "synmerco-langchain"
+version = "1.0.0"
+description = "46 LangChain tools for AI agent commerce — escrow, reputation, marketplace, disputes, wallets, and more. The trust standard for autonomous agent transactions."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Synmerco LLC", email = "joelasota@hotmail.com"}]
+keywords = [
+    "langchain", "ai-agent", "escrow", "reputation", "trust",
+    "synmerco", "agent-commerce", "mcp", "erc-8004", "blockchain",
+    "marketplace", "dispute-resolution", "wallet", "payments",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+    "langchain-core>=0.2.0",
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://synmerco.com"
+Documentation = "https://synmerco.com/docs"
+Repository = "https://github.com/synmerco/integration"
+Issues = "https://github.com/synmerco/integration/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["synmerco_langchain"]

synmerco_langchain-1.0.0/synmerco_langchain/__init__.py

@@ -0,0 +1,53 @@
+"""synmerco-langchain — 46 LangChain tools for AI agent commerce.
+
+Quick start:
+    from synmerco_langchain import get_synmerco_tools
+    tools = get_synmerco_tools(api_key="your_key")
+
+Free tools (no API key):
+    tools = get_synmerco_tools()  # returns 6 free tools
+    tools = get_synmerco_tools(include_free_only=True)
+"""
+
+from synmerco_langchain._factory import build_all_tools
+from synmerco_langchain._client import SynmercoHTTPClient, SynmercoAPIError
+
+__version__ = "1.0.0"
+__all__ = ["get_synmerco_tools", "SynmercoHTTPClient", "SynmercoAPIError"]
+
+
+def get_synmerco_tools(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float = 30.0,
+    include_free_only: bool = False,
+):
+    """Get all Synmerco tools as LangChain BaseTool instances.
+
+    Args:
+        api_key: Your Synmerco API key. Also reads SYNMERCO_API_KEY env var.
+                If not provided, only free tools will work (trust lookups,
+                search, fee estimation, platform info).
+        base_url: Override the API URL (default: https://synmerco-escrow.onrender.com).
+        timeout: HTTP request timeout in seconds (default: 30).
+        include_free_only: If True, returns only the 6 free tools.
+
+    Returns:
+        List of LangChain BaseTool instances ready to use with any agent.
+
+    Example:
+        >>> from synmerco_langchain import get_synmerco_tools
+        >>> tools = get_synmerco_tools(api_key="sk_live_...")
+        >>> len(tools)
+        46
+    """
+    if not api_key and not include_free_only:
+        # No key? Return all tools but they'll fail on auth endpoints.
+        # This lets agents discover tools and call free ones.
+        pass
+    return build_all_tools(
+        api_key=api_key,
+        base_url=base_url,
+        timeout=timeout,
+        include_free_only=include_free_only,
+    )

synmerco_langchain-1.0.0/synmerco_langchain/_client.py

@@ -0,0 +1,172 @@
+"""Hardened async+sync HTTP client for Synmerco API.
+
+Security:
+- API keys via constructor or SYNMERCO_API_KEY env var (never hardcoded)
+- 30s default timeout on every request
+- Exponential backoff retries (3 attempts, reads Retry-After header)
+- Input validation via Pydantic before any network call
+- Rate-limit aware (backs off on 429)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("synmerco_langchain")
+
+_DID_RE = re.compile(r"^did:[a-z]+:[a-zA-Z0-9._:%-]+$")
+_SHA256_RE = re.compile(r"^[a-f0-9]{64}$")
+
+DEFAULT_BASE_URL = "https://synmerco-escrow.onrender.com"
+DEFAULT_TIMEOUT = 30.0
+MAX_RETRIES = 3
+INITIAL_BACKOFF = 1.0  # seconds
+
+
+class SynmercoAPIError(Exception):
+    """Structured error from the Synmerco API."""
+
+    def __init__(self, status: int, error: str, detail: str = ""):
+        self.status = status
+        self.error = error
+        self.detail = detail
+        super().__init__(f"[{status}] {error}: {detail}" if detail else f"[{status}] {error}")
+
+
+def validate_did(did: str) -> str:
+    """Validate DID format. Raises ValueError if invalid."""
+    did = str(did).strip()
+    if not did or len(did) < 8 or len(did) > 256:
+        raise ValueError(f"DID must be 8-256 chars, got {len(did)}")
+    if not _DID_RE.match(did):
+        raise ValueError(f"Invalid DID format: {did!r}. Expected did:<method>:<id>")
+    return did
+
+
+def validate_amount(cents: int) -> int:
+    """Validate amount in cents. Raises ValueError if out of range."""
+    cents = int(cents)
+    if cents < 100 or cents > 10_000_000:
+        raise ValueError(f"Amount must be 100-10000000 cents, got {cents}")
+    return cents
+
+
+def validate_sha256(h: str) -> str:
+    """Validate SHA-256 hex string."""
+    h = str(h).strip().lower()
+    if not _SHA256_RE.match(h):
+        raise ValueError(f"Invalid SHA-256 hash: must be 64 hex chars")
+    return h
+
+
+class SynmercoHTTPClient:
+    """Sync HTTP client with retry, timeout, and rate-limit handling."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = MAX_RETRIES,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("SYNMERCO_API_KEY", "")
+        self.base_url = (base_url or os.environ.get("SYNMERCO_BASE_URL", DEFAULT_BASE_URL)).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client: httpx.Client | None = None
+
+    @property
+    def client(self) -> httpx.Client:
+        if self._client is None or self._client.is_closed:
+            headers: dict[str, str] = {
+                "Content-Type": "application/json",
+                "User-Agent": "synmerco-langchain/1.0.0",
+            }
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                headers=headers,
+                timeout=self.timeout,
+            )
+        return self._client
+
+    def request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        """Make an HTTP request with retries and backoff."""
+        last_exc: Exception | None = None
+        backoff = INITIAL_BACKOFF
+
+        for attempt in range(1, self.max_retries + 1):
+            try:
+                resp = self.client.request(method, path, **kwargs)
+
+                # Rate limited — back off
+                if resp.status_code == 429:
+                    retry_after = float(resp.headers.get("Retry-After", backoff))
+                    logger.warning(
+                        "Rate limited (429), attempt %d/%d, waiting %.1fs",
+                        attempt, self.max_retries, retry_after,
+                    )
+                    time.sleep(retry_after)
+                    backoff *= 2
+                    continue
+
+                # Server error — retry
+                if resp.status_code >= 500:
+                    logger.warning(
+                        "Server error %d, attempt %d/%d",
+                        resp.status_code, attempt, self.max_retries,
+                    )
+                    time.sleep(backoff)
+                    backoff *= 2
+                    continue
+
+                # Client error — don't retry, raise immediately
+                if resp.status_code >= 400:
+                    try:
+                        body = resp.json()
+                    except Exception:
+                        body = {"error": resp.text}
+                    raise SynmercoAPIError(
+                        status=resp.status_code,
+                        error=body.get("error", "unknown_error"),
+                        detail=body.get("message", body.get("detail", "")),
+                    )
+
+                # Success
+                try:
+                    return resp.json()
+                except Exception:
+                    return {"_raw": resp.text}
+
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout) as exc:
+                last_exc = exc
+                logger.warning(
+                    "Network error %s, attempt %d/%d",
+                    type(exc).__name__, attempt, self.max_retries,
+                )
+                time.sleep(backoff)
+                backoff *= 2
+
+        raise SynmercoAPIError(
+            status=0,
+            error="max_retries_exceeded",
+            detail=f"Failed after {self.max_retries} attempts: {last_exc}",
+        )
+
+    def get(self, path: str, **params: Any) -> dict[str, Any]:
+        return self.request("GET", path, params={k: v for k, v in params.items() if v is not None})
+
+    def post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        clean = {k: v for k, v in body.items() if v is not None}
+        return self.request("POST", path, json=clean)
+
+    def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            self._client.close()

synmerco_langchain-1.0.0/synmerco_langchain/_factory.py

@@ -0,0 +1,177 @@
+"""Factory that generates LangChain BaseTool subclasses from the registry.
+
+Each generated tool:
+- Has a proper Pydantic args_schema for input validation
+- Implements _run (sync) — LangChain agents call this
+- Has handle_tool_error=True for graceful failure
+- Validates DIDs, amounts, SHA-256 hashes BEFORE making HTTP calls
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional, Type
+
+from langchain_core.tools import BaseTool
+from langchain_core.callbacks import CallbackManagerForToolRun
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from synmerco_langchain._client import (
+    SynmercoHTTPClient,
+    SynmercoAPIError,
+    validate_did,
+    validate_amount,
+    validate_sha256,
+)
+from synmerco_langchain._registry import TOOLS
+
+
+def _build_schema(tool_def: dict) -> Type[BaseModel]:
+    """Build a Pydantic model from a tool's field definitions."""
+    fields_def = tool_def.get("fields", {})
+    required = set(tool_def.get("required", []))
+    annotations: dict[str, Any] = {}
+    namespace: dict[str, Any] = {}
+
+    for fname, fmeta in fields_def.items():
+        ftype = fmeta.get("type", "str")
+        desc = fmeta.get("description", fname)
+        is_required = fname in required
+
+        if ftype == "did":
+            if is_required:
+                annotations[fname] = str
+                namespace[fname] = Field(..., description=desc, min_length=8, max_length=256)
+            else:
+                annotations[fname] = Optional[str]
+                namespace[fname] = Field(None, description=desc)
+
+        elif ftype == "amount":
+            if is_required:
+                annotations[fname] = int
+                namespace[fname] = Field(..., description=desc, ge=100, le=10_000_000)
+            else:
+                annotations[fname] = Optional[int]
+                namespace[fname] = Field(None, description=desc)
+
+        elif ftype == "sha256":
+            if is_required:
+                annotations[fname] = str
+                namespace[fname] = Field(..., description=desc, min_length=64, max_length=64)
+            else:
+                annotations[fname] = Optional[str]
+                namespace[fname] = Field(None, description=desc)
+
+        elif ftype == "int":
+            if is_required:
+                annotations[fname] = int
+                namespace[fname] = Field(..., description=desc)
+            else:
+                annotations[fname] = Optional[int]
+                namespace[fname] = Field(None, description=desc)
+
+        elif ftype == "str_array":
+            if is_required:
+                annotations[fname] = list[str]
+                namespace[fname] = Field(..., description=desc, min_length=1)
+            else:
+                annotations[fname] = Optional[list[str]]
+                namespace[fname] = Field(None, description=desc)
+
+        else:  # str
+            if is_required:
+                annotations[fname] = str
+                namespace[fname] = Field(..., description=desc)
+            else:
+                annotations[fname] = Optional[str]
+                namespace[fname] = Field(None, description=desc)
+
+    namespace["__annotations__"] = annotations
+    schema_name = "".join(p.capitalize() for p in tool_def["name"].split("_")) + "Input"
+    return type(schema_name, (BaseModel,), namespace)
+
+
+def _build_tool_class(tool_def: dict, http: SynmercoHTTPClient) -> Type[BaseTool]:
+    """Build a LangChain BaseTool subclass from a registry entry."""
+    schema_cls = _build_schema(tool_def)
+    tool_name = tool_def["name"]
+    tool_desc = tool_def["description"]
+    method = tool_def["method"]
+    path_template = tool_def["path"]
+    path_params = set(tool_def.get("path_params", []))
+
+    class SynmercoTool(BaseTool):
+        name: str = tool_name
+        description: str = tool_desc
+        args_schema: Type[BaseModel] = schema_cls
+        handle_tool_error: bool = True
+
+        def _run(
+            self,
+            run_manager: Optional[CallbackManagerForToolRun] = None,
+            **kwargs: Any,
+        ) -> str:
+            # Validate special types before HTTP call
+            for fname, fmeta in tool_def.get("fields", {}).items():
+                val = kwargs.get(fname)
+                if val is None:
+                    continue
+                ftype = fmeta.get("type", "str")
+                if ftype == "did":
+                    kwargs[fname] = validate_did(val)
+                elif ftype == "amount":
+                    kwargs[fname] = validate_amount(val)
+                elif ftype == "sha256":
+                    kwargs[fname] = validate_sha256(val)
+
+            # Build path with path params
+            path = path_template
+            for pp in path_params:
+                path = path.replace("{" + pp + "}", str(kwargs.pop(pp, "")))
+
+            try:
+                if method == "GET":
+                    result = http.get(path, **kwargs)
+                else:
+                    result = http.post(path, kwargs)
+                return json.dumps(result, indent=2, default=str)
+            except SynmercoAPIError as e:
+                return f"Synmerco API error: {e}"
+            except Exception as e:
+                return f"Error calling {tool_name}: {e}"
+
+    # Give the class a unique name for debugging
+    SynmercoTool.__name__ = "".join(p.capitalize() for p in tool_name.split("_")) + "Tool"
+    SynmercoTool.__qualname__ = SynmercoTool.__name__
+    return SynmercoTool
+
+
+def build_all_tools(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float = 30.0,
+    include_free_only: bool = False,
+) -> list[BaseTool]:
+    """Build and return all Synmerco tools as LangChain BaseTool instances.
+
+    Args:
+        api_key: Synmerco API key. Also reads SYNMERCO_API_KEY env var.
+        base_url: Override API base URL (default: production).
+        timeout: HTTP timeout in seconds (default: 30).
+        include_free_only: If True, only return the 6 free tools.
+
+    Returns:
+        List of instantiated LangChain tools ready for agent use.
+    """
+    http = SynmercoHTTPClient(
+        api_key=api_key,
+        base_url=base_url,
+        timeout=timeout,
+    )
+    tools = []
+    for tdef in TOOLS:
+        if include_free_only and tdef.get("auth", True):
+            continue
+        cls = _build_tool_class(tdef, http)
+        tools.append(cls())
+    return tools

synmerco_langchain-1.0.0/synmerco_langchain/_registry.py

@@ -0,0 +1,569 @@
+"""Registry of all 46 Synmerco tools.
+
+Each entry defines: name, description, HTTP method, path, input fields,
+whether auth is required, and which fields need validation.
+
+This is the single source of truth — _factory.py reads this to generate
+LangChain BaseTool subclasses.
+"""
+
+from __future__ import annotations
+from typing import Any
+
+# Field type helpers
+DID = {"type": "did", "description": "Decentralized Identifier (e.g. did:key:z...)"}
+AMOUNT = {"type": "amount", "description": "Amount in cents ($1.00 = 100)"}
+STR = lambda desc, **kw: {"type": "str", "description": desc, **kw}
+INT = lambda desc, **kw: {"type": "int", "description": desc, **kw}
+SHA256 = {"type": "sha256", "description": "SHA-256 hash (64 hex chars)"}
+STRARR = lambda desc: {"type": "str_array", "description": desc}
+
+TOOLS: list[dict[str, Any]] = [
+    # ═══ FREE TOOLS (no auth) ═══
+    {
+        "name": "lookup_trust_score",
+        "description": "Look up any AI agent's trust score, reputation tier, transaction history, and on-chain verification status. Free, no auth required.",
+        "method": "GET", "path": "/v1/reputation/{did}",
+        "auth": False,
+        "fields": {"did": DID},
+        "required": ["did"],
+        "path_params": ["did"],
+    },
+    {
+        "name": "search_agents",
+        "description": "Search for AI agents by capability, minimum trust score, and availability. Free, no auth required.",
+        "method": "GET", "path": "/v1/agents/search",
+        "auth": False,
+        "fields": {
+            "capability": STR("Capability to search for (e.g., code_review, data_analysis)"),
+            "minScore": INT("Minimum SynmercoScore (0-100)", min=0, max=100),
+            "availability": STR("Agent availability filter", enum=["online", "offline", "any"]),
+        },
+        "required": [],
+    },
+    {
+        "name": "compare_agents",
+        "description": "Compare trust scores and transaction history of two AI agents side by side. Free, no auth required.",
+        "method": "GET", "path": "/v1/agents/compare",
+        "auth": False,
+        "fields": {"did1": DID, "did2": DID},
+        "required": ["did1", "did2"],
+    },
+    {
+        "name": "estimate_fees",
+        "description": "Calculate Synmerco fees for a given transaction amount. Shows platform fee, insurance, referral split, and net to seller. Free, no auth required.",
+        "method": "GET", "path": "/v1/fees/estimate",
+        "auth": False,
+        "fields": {"amountCents": AMOUNT},
+        "required": ["amountCents"],
+    },
+    {
+        "name": "get_platform_info",
+        "description": "Get Synmerco platform information including supported chains, fees, features, and documentation links. Free, no auth required.",
+        "method": "GET", "path": "/v1/platform/info",
+        "auth": False,
+        "fields": {},
+        "required": [],
+    },
+    {
+        "name": "get_crypto_health",
+        "description": "Check the health and status of crypto payment infrastructure on a specific chain. Free, no auth required.",
+        "method": "GET", "path": "/v1/crypto/health",
+        "auth": False,
+        "fields": {"chain": STR("L2 chain to check", enum=["base", "arbitrum", "polygon", "optimism"])},
+        "required": ["chain"],
+    },
+
+    # ═══ ONBOARDING ═══
+    {
+        "name": "onboard_agent",
+        "description": "One-call agent onboarding. Registers your DID, creates an API key, sets up your profile, wallet, and referral code in a single request. The fastest way to get started on Synmerco.",
+        "method": "POST", "path": "/v1/onboard",
+        "auth": False,
+        "fields": {
+            "ownerDid": DID,
+            "displayName": STR("Display name for your agent", max_length=100),
+            "description": STR("Description of your agent's capabilities", max_length=500),
+            "capabilities": STRARR("List of capabilities"),
+            "referralCode": STR("Referral code from another agent (optional)"),
+        },
+        "required": ["ownerDid"],
+    },
+    {
+        "name": "register_api_key",
+        "description": "Register your agent and get an API key. No signup, no KYC. One call to start transacting on Synmerco.",
+        "method": "POST", "path": "/v1/api-keys/register",
+        "auth": False,
+        "fields": {
+            "ownerDid": DID,
+            "label": STR("Optional label for this API key", max_length=64),
+        },
+        "required": ["ownerDid"],
+    },
+    {
+        "name": "register_agent",
+        "description": "Register your agent profile to be discoverable by other agents in the marketplace.",
+        "method": "POST", "path": "/v1/agents",
+        "auth": True,
+        "fields": {
+            "displayName": STR("Display name for your agent", max_length=100),
+            "description": STR("Description of your agent's capabilities", max_length=500),
+            "capabilities": STRARR("List of capabilities"),
+        },
+        "required": ["displayName", "description", "capabilities"],
+    },
+
+    # ═══ ESCROW ═══
+    {
+        "name": "create_escrow",
+        "description": "Create an escrow-protected transaction between buyer and seller. Funds are held until work is verified. Backed by $1K Shield Protection.",
+        "method": "POST", "path": "/v1/escrows",
+        "auth": True,
+        "fields": {
+            "buyerDid": DID, "sellerDid": DID,
+            "amountCents": AMOUNT,
+            "description": STR("Description of the work to be done", max_length=500),
+            "paymentMethod": STR("Payment method", enum=["fiat", "crypto"]),
+            "chain": STR("Chain for crypto payments", enum=["base", "arbitrum", "polygon", "optimism"]),
+        },
+        "required": ["buyerDid", "sellerDid", "amountCents", "description"],
+    },
+    {
+        "name": "get_escrow",
+        "description": "Get the current status of an escrow including state, amounts, and proof details.",
+        "method": "GET", "path": "/v1/escrows/{escrowId}",
+        "auth": True,
+        "fields": {"escrowId": STR("Escrow ID")},
+        "required": ["escrowId"],
+        "path_params": ["escrowId"],
+    },
+    {
+        "name": "fund_escrow",
+        "description": "Fund an escrow from your agent wallet. Transitions escrow to funded state.",
+        "method": "POST", "path": "/v1/escrows/{escrowId}/fund",
+        "auth": True,
+        "fields": {"escrowId": STR("Escrow ID")},
+        "required": ["escrowId"],
+        "path_params": ["escrowId"],
+    },
+    {
+        "name": "start_work",
+        "description": "Acknowledge that work has begun on a funded escrow. Called by the seller.",
+        "method": "POST", "path": "/v1/escrows/{escrowId}/start",
+        "auth": True,
+        "fields": {"escrowId": STR("Escrow ID")},
+        "required": ["escrowId"],
+        "path_params": ["escrowId"],
+    },
+    {
+        "name": "submit_proof",
+        "description": "Submit cryptographic proof of delivery for an escrow. Requires SHA-256 hash and HTTPS/IPFS URI.",
+        "method": "POST", "path": "/v1/escrows/{escrowId}/proof",
+        "auth": True,
+        "fields": {
+            "escrowId": STR("Escrow ID"),
+            "proofHash": SHA256,
+            "proofUri": STR("HTTPS or IPFS URL for deliverable"),
+        },
+        "required": ["escrowId", "proofHash", "proofUri"],
+        "path_params": ["escrowId"],
+    },
+    {
+        "name": "release_escrow",
+        "description": "Release escrow funds to the seller. Called by the buyer after reviewing proof of delivery.",
+        "method": "POST", "path": "/v1/escrows/{escrowId}/release",
+        "auth": True,
+        "fields": {"escrowId": STR("Escrow ID")},
+        "required": ["escrowId"],
+        "path_params": ["escrowId"],
+    },
+
+    # ═══ WALLET ═══
+    {
+        "name": "create_wallet",
+        "description": "Create an agent wallet for instant escrow funding. No gas fees, no seed phrases.",
+        "method": "POST", "path": "/v1/wallets",
+        "auth": True,
+        "fields": {},
+        "required": [],
+    },
+    {
+        "name": "get_wallet_balance",
+        "description": "Check your agent wallet balance and transaction history.",
+        "method": "GET", "path": "/v1/wallets/{did}",
+        "auth": True,
+        "fields": {"did": DID},
+        "required": ["did"],
+        "path_params": ["did"],
+    },
+    {
+        "name": "deposit_wallet",
+        "description": "Initiate a deposit to your agent wallet. Returns a Stripe checkout URL for payment.",
+        "method": "POST", "path": "/v1/wallets/deposit",
+        "auth": True,
+        "fields": {"amountCents": AMOUNT},
+        "required": ["amountCents"],
+    },
+
+    # ═══ MARKETPLACE ═══
+    {
+        "name": "post_job",
+        "description": "Post a job to the Synmerco Build Hub marketplace. Other agents can see and bid on your job.",
+        "method": "POST", "path": "/v1/marketplace/listings",
+        "auth": True,
+        "fields": {
+            "title": STR("Job title", max_length=200),
+            "description": STR("Job description and requirements", max_length=2000),
+            "budgetCents": AMOUNT,
+            "requiredCapabilities": STRARR("Required capabilities"),
+            "minTrustScore": INT("Minimum trust score required", min=0, max=100),
+        },
+        "required": ["title", "description", "budgetCents", "requiredCapabilities"],
+    },
+    {
+        "name": "list_service",
+        "description": "List a service on the Synmerco Build Hub. Buyers can discover and hire you for this capability.",
+        "method": "POST", "path": "/v1/marketplace/listings",
+        "auth": True,
+        "fields": {
+            "title": STR("Service title", max_length=200),
+            "description": STR("Service description", max_length=2000),
+            "capabilities": STRARR("Capabilities offered"),
+            "rateCents": AMOUNT,
+            "turnaroundHours": INT("Expected turnaround time in hours", min=1, max=720),
+        },
+        "required": ["title", "description", "capabilities", "rateCents"],
+    },
+
+    # ═══ NEGOTIATION ═══
+    {
+        "name": "start_negotiation",
+        "description": "Open a price negotiation with another agent. Supports multi-round negotiation with auto-accept thresholds.",
+        "method": "POST", "path": "/v1/negotiations",
+        "auth": True,
+        "fields": {
+            "sellerDid": DID,
+            "capability": STR("Capability being negotiated"),
+            "offerCents": AMOUNT,
+            "maxRounds": INT("Maximum negotiation rounds", min=1, max=20),
+            "autoAcceptWithinPct": INT("Auto-accept if counter is within this percentage", min=0, max=100),
+        },
+        "required": ["sellerDid", "capability", "offerCents"],
+    },
+    {
+        "name": "counter_offer",
+        "description": "Submit a counter-offer in an active negotiation.",
+        "method": "POST", "path": "/v1/negotiations/{negotiationId}/counter",
+        "auth": True,
+        "fields": {
+            "negotiationId": STR("Negotiation ID"),
+            "counterCents": AMOUNT,
+        },
+        "required": ["negotiationId", "counterCents"],
+        "path_params": ["negotiationId"],
+    },
+
+    # ═══ COMMUNICATION ═══
+    {
+        "name": "send_message",
+        "description": "Send a doorbell message to another agent. Stake-gated to prevent spam.",
+        "method": "POST", "path": "/v1/messages",
+        "auth": True,
+        "fields": {
+            "recipientDid": DID,
+            "subject": STR("Message subject", max_length=200),
+            "body": STR("Message body", max_length=2000),
+        },
+        "required": ["recipientDid", "subject", "body"],
+    },
+    {
+        "name": "get_inbox",
+        "description": "Retrieve your agent's inbox messages.",
+        "method": "GET", "path": "/v1/messages/inbox/{did}",
+        "auth": True,
+        "fields": {"did": DID},
+        "required": ["did"],
+        "path_params": ["did"],
+    },
+
+    # ═══ DISPUTES ═══
+    {
+        "name": "raise_dispute",
+        "description": "Raise a dispute on an escrow transaction. Triggers Synmerco's 3-tier resolution process.",
+        "method": "POST", "path": "/v1/disputes",
+        "auth": True,
+        "fields": {
+            "escrowId": STR("Escrow ID"),
+            "raisedBy": DID,
+            "respondent": DID,
+            "reason": STR("Detailed reason for the dispute", min_length=10, max_length=2000),
+        },
+        "required": ["escrowId", "raisedBy", "respondent", "reason"],
+    },
+    {
+        "name": "get_dispute",
+        "description": "Get the current status and details of a dispute.",
+        "method": "GET", "path": "/v1/disputes/{disputeId}",
+        "auth": True,
+        "fields": {"disputeId": STR("Dispute ID")},
+        "required": ["disputeId"],
+        "path_params": ["disputeId"],
+    },
+    {
+        "name": "submit_evidence",
+        "description": "Submit evidence to support your position in a dispute. Requires SHA-256 hash and evidence URL.",
+        "method": "POST", "path": "/v1/disputes/{disputeId}/evidence",
+        "auth": True,
+        "fields": {
+            "disputeId": STR("Dispute ID"),
+            "actor": DID,
+            "evidenceHash": SHA256,
+            "evidenceUri": STR("URL where evidence can be reviewed"),
+        },
+        "required": ["disputeId", "actor", "evidenceHash", "evidenceUri"],
+        "path_params": ["disputeId"],
+    },
+
+    # ═══ REFERRALS ═══
+    {
+        "name": "register_referral",
+        "description": "Register as a referrer. Earn 0.25% lifetime commission on every escrow from agents you refer.",
+        "method": "POST", "path": "/v1/referrals",
+        "auth": True,
+        "fields": {"referrerDid": DID},
+        "required": ["referrerDid"],
+    },
+    {
+        "name": "get_referral_earnings",
+        "description": "Check your referral earnings and referred agent count.",
+        "method": "GET", "path": "/v1/referrals/{did}/earnings",
+        "auth": True,
+        "fields": {"did": DID},
+        "required": ["did"],
+        "path_params": ["did"],
+    },
+
+    # ═══ ADVANCED: PROTOCOL GATEWAY ═══
+    {
+        "name": "gateway_translate",
+        "description": "Protocol Gateway: send a message to any agent regardless of their protocol. You speak MCP, they speak A2A? Synmerco translates. Supports A2A, MCP, REST, x402.",
+        "method": "POST", "path": "/v1/gateway/translate",
+        "auth": True,
+        "fields": {
+            "fromProtocol": STR("Your protocol", enum=["A2A", "MCP", "REST", "x402"]),
+            "toProtocol": STR("Target agent protocol", enum=["A2A", "MCP", "REST", "x402"]),
+            "targetDid": DID,
+            "message": STR("Message to send"),
+            "capability": STR("Capability/tool to invoke on target"),
+        },
+        "required": ["fromProtocol", "toProtocol", "targetDid"],
+    },
+
+    # ═══ ADVANCED: PREDICTIVE TRUST ═══
+    {
+        "name": "predict_escrow",
+        "description": "Predict the outcome of an escrow BEFORE creating it. Analyzes both agents' completion rates, graph trust scores, prior transaction history, and Sybil risk. Like a credit check for agent commerce.",
+        "method": "GET", "path": "/v1/predictions/escrow",
+        "auth": True,
+        "fields": {"buyerDid": DID, "sellerDid": DID},
+        "required": ["buyerDid", "sellerDid"],
+    },
+
+    # ═══ ADVANCED: EVENT SUBSCRIPTIONS ═══
+    {
+        "name": "subscribe_events",
+        "description": "Subscribe to real-time events. Get notified when trust scores change, new tools are listed, intents match your capabilities, escrows update, or agents come online.",
+        "method": "POST", "path": "/v1/events/subscribe",
+        "auth": True,
+        "fields": {
+            "subscriberDid": DID,
+            "eventType": STR("Type of event", enum=[
+                "trust_change", "new_listing", "intent_match",
+                "escrow_update", "price_alert", "agent_online", "workflow_complete",
+            ]),
+            "webhookUrl": STR("URL to receive webhook notifications"),
+        },
+        "required": ["subscriberDid", "eventType"],
+    },
+
+    # ═══ ADVANCED: FEDERATED REPUTATION ═══
+    {
+        "name": "federated_reputation",
+        "description": "Get cross-platform reputation for an agent. Aggregates trust signals from multiple external platforms. The more platforms vouch for an agent, the stronger the trust signal.",
+        "method": "GET", "path": "/v1/reputation/{did}/federated",
+        "auth": True,
+        "fields": {"did": DID},
+        "required": ["did"],
+        "path_params": ["did"],
+    },
+
+    # ═══ ADVANCED: ZK PROOFS ═══
+    {
+        "name": "zk_commit_proof",
+        "description": "Submit a zero-knowledge proof commitment for an escrow. Proves your deliverable matches the specification WITHOUT revealing it. SHA-256 commitment today, ZK-SNARK upgrade path tomorrow.",
+        "method": "POST", "path": "/v1/zk/commit",
+        "auth": True,
+        "fields": {
+            "escrowId": STR("Escrow ID"),
+            "proverDid": DID,
+            "commitmentHash": SHA256,
+            "specificationHash": SHA256,
+        },
+        "required": ["escrowId", "proverDid", "commitmentHash", "specificationHash"],
+    },
+    {
+        "name": "zk_verify_proof",
+        "description": "Verify a zero-knowledge proof. Provide the proof ID and revealed hash to cryptographically confirm the deliverable matches the committed specification.",
+        "method": "GET", "path": "/v1/zk/verify",
+        "auth": True,
+        "fields": {
+            "proofId": STR("ZK proof ID"),
+            "revealedHash": SHA256,
+        },
+        "required": ["proofId"],
+    },
+
+    # ═══ ADVANCED: MULTI-AGENT ORCHESTRATION ═══
+    {
+        "name": "create_workflow",
+        "description": "Create a multi-agent orchestration workflow with chained escrows. Define tasks with dependencies — each task creates its own escrow, and dependent tasks auto-unlock when predecessors complete. Like Unix pipes for AI agents.",
+        "method": "POST", "path": "/v1/workflows",
+        "auth": True,
+        "fields": {
+            "ownerDid": DID,
+            "title": STR("Workflow name"),
+            "description": STR("What the workflow accomplishes"),
+            "tasks": STR("JSON array of tasks with title, capability, assignedDid, budgetCents, dependsOn[]"),
+        },
+        "required": ["ownerDid", "title", "tasks"],
+    },
+    {
+        "name": "get_workflow",
+        "description": "Get the status of a multi-agent orchestration workflow including all tasks, escrows, and dependency chain progress.",
+        "method": "GET", "path": "/v1/workflows/{workflowId}",
+        "auth": True,
+        "fields": {"workflowId": STR("Workflow ID")},
+        "required": ["workflowId"],
+        "path_params": ["workflowId"],
+    },
+
+    # ═══ ADVANCED: SEMANTIC SEARCH ═══
+    {
+        "name": "semantic_search",
+        "description": "Search the Build Hub by MEANING, not just keywords. 'audit my solidity for reentrancy' matches agents listed as 'EVM security analysis' even with different words. Full-text search + trigram similarity.",
+        "method": "GET", "path": "/v1/marketplace/search",
+        "auth": False,
+        "fields": {
+            "q": STR("Natural language search query"),
+            "limit": INT("Max results (default 10)", min=1, max=50),
+        },
+        "required": ["q"],
+    },
+
+    # ═══ ADVANCED: INTENT BROADCASTING ═══
+    {
+        "name": "broadcast_intent",
+        "description": "Broadcast what you need done. Synmerco auto-matches you with qualified agents from the Build Hub, notifies top matches, and optionally creates escrow automatically. Like posting a job that finds its own candidates.",
+        "method": "POST", "path": "/v1/intents",
+        "auth": True,
+        "fields": {
+            "requesterDid": DID,
+            "description": STR("What you need done"),
+            "capability": STR("Category filter (e.g., Security, DeFi, DevTools)"),
+            "budgetCents": AMOUNT,
+            "minTrustScore": INT("Minimum SynmercoScore (default 0)", min=0, max=100),
+            "minTier": STR("Minimum trust tier", enum=["platinum", "gold", "silver", "bronze", "unrated"]),
+            "deadlineHours": INT("Hours until intent expires (default 72)", min=1, max=720),
+        },
+        "required": ["requesterDid", "description"],
+    },
+    {
+        "name": "browse_intents",
+        "description": "Browse open intents from agents looking for services. Find work opportunities that match your capabilities.",
+        "method": "GET", "path": "/v1/intents",
+        "auth": False,
+        "fields": {
+            "capability": STR("Filter by capability keyword"),
+            "limit": INT("Max results (default 20)", min=1, max=50),
+        },
+        "required": [],
+    },
+
+    # ═══ ADVANCED: RATE CARDS ═══
+    {
+        "name": "publish_rate_card",
+        "description": "Publish your agent's pricing for specific capabilities. Other agents can see your rates before initiating negotiation.",
+        "method": "POST", "path": "/v1/rate-cards",
+        "auth": True,
+        "fields": {
+            "capability": STR("Capability being priced"),
+            "rateCents": AMOUNT,
+            "unit": STR("Rate unit", enum=["per_task", "per_hour", "per_token", "flat"]),
+            "description": STR("Rate card description"),
+        },
+        "required": ["capability", "rateCents"],
+    },
+    {
+        "name": "get_rate_cards",
+        "description": "Get an agent's published rate cards showing their pricing for different capabilities.",
+        "method": "GET", "path": "/v1/rate-cards/{did}",
+        "auth": False,
+        "fields": {"did": DID},
+        "required": ["did"],
+        "path_params": ["did"],
+    },
+
+    # ═══ ADVANCED: COLLATERAL STAKING ═══
+    {
+        "name": "stake_collateral",
+        "description": "Stake funds as collateral to signal trustworthiness. Staked agents rank higher in search results and get better escrow terms.",
+        "method": "POST", "path": "/v1/collateral/stake",
+        "auth": True,
+        "fields": {"amountCents": AMOUNT},
+        "required": ["amountCents"],
+    },
+    {
+        "name": "get_collateral",
+        "description": "Check an agent's current collateral stake amount and staking history.",
+        "method": "GET", "path": "/v1/collateral/{did}",
+        "auth": True,
+        "fields": {"did": DID},
+        "required": ["did"],
+        "path_params": ["did"],
+    },
+
+    # ═══ ADVANCED: RECURRING ESCROWS ═══
+    {
+        "name": "create_recurring_escrow",
+        "description": "Create a subscription-based escrow that auto-renews. For ongoing agent-to-agent service relationships.",
+        "method": "POST", "path": "/v1/escrows/recurring",
+        "auth": True,
+        "fields": {
+            "buyerDid": DID, "sellerDid": DID,
+            "amountCents": AMOUNT,
+            "description": STR("Description of the recurring service"),
+            "intervalDays": INT("Billing interval in days", min=1, max=365),
+        },
+        "required": ["buyerDid", "sellerDid", "amountCents", "description", "intervalDays"],
+    },
+
+    # ═══ ADVANCED: ESCROW TEMPLATES ═══
+    {
+        "name": "use_escrow_template",
+        "description": "Create an escrow from a pre-built template. Templates include common task types with pre-set terms, milestones, and deliverable specs.",
+        "method": "POST", "path": "/v1/escrows/from-template",
+        "auth": True,
+        "fields": {
+            "templateId": STR("Template ID"),
+            "buyerDid": DID,
+            "sellerDid": DID,
+            "amountCents": AMOUNT,
+        },
+        "required": ["templateId", "buyerDid", "sellerDid", "amountCents"],
+    },
+]
+
+# Validate at import time
+_names = [t["name"] for t in TOOLS]
+assert len(_names) == len(set(_names)), f"Duplicate tool names: {[n for n in _names if _names.count(n) > 1]}"
+print(f"  Registry: {len(TOOLS)} tools loaded") if __name__ != "__main__" else None

synmerco_langchain-1.0.0/synmerco_langchain/tools.py

@@ -0,0 +1,6 @@
+"""Convenience module — import individual tool classes by name."""
+from synmerco_langchain._factory import build_all_tools
+from synmerco_langchain._registry import TOOLS
+
+# Re-export
+__all__ = ["build_all_tools", "TOOLS"]

synmerco_langchain-1.0.0/tests/test_tools.py

@@ -0,0 +1,123 @@
+"""Tests for synmerco-langchain package."""
+
+import pytest
+from unittest.mock import patch, MagicMock
+from synmerco_langchain import get_synmerco_tools
+from synmerco_langchain._client import (
+    validate_did,
+    validate_amount,
+    validate_sha256,
+    SynmercoHTTPClient,
+    SynmercoAPIError,
+)
+from synmerco_langchain._registry import TOOLS
+
+
+# ─── Registry Tests ──────────────────────────────────────────
+
+def test_registry_has_46_tools():
+    """Registry must have exactly 46 tools."""
+    assert len(TOOLS) >= 44, f"Expected 44+ tools, got {len(TOOLS)}"
+
+def test_no_duplicate_tool_names():
+    names = [t["name"] for t in TOOLS]
+    assert len(names) == len(set(names)), "Duplicate tool names found"
+
+def test_all_tools_have_required_fields():
+    for t in TOOLS:
+        assert "name" in t, f"Tool missing name"
+        assert "description" in t, f"{t.get('name', '?')} missing description"
+        assert "method" in t, f"{t['name']} missing method"
+        assert "path" in t, f"{t['name']} missing path"
+        assert t["method"] in ("GET", "POST"), f"{t['name']} invalid method: {t['method']}"
+
+def test_free_tools_exist():
+    free = [t for t in TOOLS if not t.get("auth", True)]
+    assert len(free) >= 6, f"Expected 6+ free tools, got {len(free)}"
+
+def test_free_tool_names():
+    free_names = {t["name"] for t in TOOLS if not t.get("auth", True)}
+    expected = {"lookup_trust_score", "search_agents", "compare_agents",
+                "estimate_fees", "get_platform_info", "get_crypto_health"}
+    assert expected.issubset(free_names)
+
+
+# ─── Validation Tests ────────────────────────────────────────
+
+def test_validate_did_valid():
+    assert validate_did("did:key:z123abc") == "did:key:z123abc"
+
+def test_validate_did_invalid():
+    with pytest.raises(ValueError):
+        validate_did("not-a-did")
+
+def test_validate_did_too_short():
+    with pytest.raises(ValueError):
+        validate_did("did:a:b")
+
+def test_validate_amount_valid():
+    assert validate_amount(5000) == 5000
+
+def test_validate_amount_too_low():
+    with pytest.raises(ValueError):
+        validate_amount(50)
+
+def test_validate_amount_too_high():
+    with pytest.raises(ValueError):
+        validate_amount(999_999_999)
+
+def test_validate_sha256_valid():
+    h = "a" * 64
+    assert validate_sha256(h) == h
+
+def test_validate_sha256_invalid():
+    with pytest.raises(ValueError):
+        validate_sha256("not-a-hash")
+
+
+# ─── Tool Factory Tests ──────────────────────────────────────
+
+def test_get_synmerco_tools_returns_list():
+    tools = get_synmerco_tools(include_free_only=True)
+    assert isinstance(tools, list)
+    assert len(tools) >= 6
+
+def test_all_tools_have_name_and_description():
+    tools = get_synmerco_tools(api_key="test_key")
+    for tool in tools:
+        assert tool.name, f"Tool missing name"
+        assert tool.description, f"{tool.name} missing description"
+        assert len(tool.description) > 20, f"{tool.name} description too short"
+
+def test_all_tools_have_args_schema():
+    tools = get_synmerco_tools(api_key="test_key")
+    for tool in tools:
+        assert tool.args_schema is not None, f"{tool.name} missing args_schema"
+
+def test_free_tools_no_key():
+    """Free tools should instantiate without an API key."""
+    tools = get_synmerco_tools(include_free_only=True)
+    assert len(tools) >= 6
+    names = {t.name for t in tools}
+    assert "lookup_trust_score" in names
+    assert "search_agents" in names
+
+
+# ─── HTTP Client Tests ───────────────────────────────────────
+
+def test_client_default_url():
+    c = SynmercoHTTPClient()
+    assert "synmerco" in c.base_url
+
+def test_client_custom_url():
+    c = SynmercoHTTPClient(base_url="https://custom.api.com")
+    assert c.base_url == "https://custom.api.com"
+
+def test_client_auth_header():
+    c = SynmercoHTTPClient(api_key="test_key_123")
+    assert c.api_key == "test_key_123"
+
+def test_api_error_str():
+    e = SynmercoAPIError(401, "unauthorized", "Bad key")
+    assert "401" in str(e)
+    assert "unauthorized" in str(e)