langchain-collar

LangChain tools for Collar Guardrail — deterministic pre-trade risk checks for AI trading agents on Robinhood Chain.

What is this?

This package wraps the Collar Guardrail MCP server as native LangChain tools. Any LangChain agent can evaluate proposed trades against a deterministic risk policy before executing them — with allow / warn / deny verdicts, a 0–100 risk score, and a tamper-evident SHA-256 audit hash.

If you're building a trading agent that needs to respect rate limits, tier ceilings, honeypot checks, or market-hours rules, these tools enforce those constraints outside your agent's own runtime.

Installation

pip install langchain-collar

Requires Python 3.10+ and langchain-core>=0.3.0.

Quick Start

Add tools to a LangChain agent

from langchain_collar import get_tools
from langchain.agents import create_agent

tools = get_tools()
agent = create_agent("gpt-4o", tools)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": (
            "Before executing a 10 NVDA buy from wallet "
            "0x1234567890abcdef1234567890abcdef12345678, "
            "run a pre-trade risk check."
        ),
    }]
})
print(result)

Or call a tool directly

from langchain_collar import evaluate_trade

verdict = evaluate_trade.invoke({
    "wallet": "0x1234567890abcdef1234567890abcdef12345678",
    "asset": "NVDA",
    "contract_address": "0x<official_registry_address>",
    "side": "buy",
    "amount": 10.0,
})
print(verdict)

Available Tools

How It Works

Each tool is a thin wrapper around the Collar Guardrail MCP server at:

https://api.collarguardrail.com/mcp-http/mcp

The MCP transport is Streamable HTTP (protocol version 2025-06-18). No API key is required for the MCP endpoint — every call is evaluated at a fixed Tier 1 ceiling ($5,000 notional).

For higher limits ($25K / $100K), use the REST API with wallet-signature authentication. See the Collar agent docs.

Decision Semantics

Safety rule: If a verdict contains an error key, no verdict was produced. Treat it as a hard stop. If decision == "deny", do not execute the trade.

Example: Full Pre-Trade Flow

import json

from langchain_collar import (
    evaluate_trade,
    get_supported_assets,
    check_token_safety,
)

# 1. Resolve the symbol to its canonical contract address
assets = get_supported_assets.invoke({})
print(assets)  # → list of {symbol, contract_address, is_native}

# 2. Check the token for honeypot risk BEFORE evaluating the trade
safety = json.loads(check_token_safety.invoke({
    "contract_address": "0x<token_address>",
}))
if safety.get("severity") == "danger":
    raise RuntimeError(
        f"Token is flagged as dangerous: {safety.get('risk_factors')}"
    )

# 3. Run the pre-trade risk check
verdict = evaluate_trade.invoke({
    "wallet": "0x1234567890abcdef1234567890abcdef12345678",
    "asset": "NVDA",
    "contract_address": "0x<official_registry_address>",
    "side": "buy",
    "amount": 10.0,
    "max_slippage_bps": 100,
})

if '"decision": "deny"' in verdict:
    raise RuntimeError("Trade denied by Collar Guardrail")

# Proceed with the trade only if the verdict is allow or warn

Paid Tier (x402)

For high-volume agent traffic, Collar exposes an x402 payment endpoint at POST /api/x402/analyze — $0.01 USDG per call on Robinhood Chain, no signup required. See the x402 discovery document.

Configuration

The package talks to the public Collar MCP endpoint by default. To self-host Collar, override the base URL:

import langchain_collar.tools as tools

tools._BASE_URL = "https://your-colar-instance.example.com"
tools._MCP_ENDPOINT = f"{tools._BASE_URL}/mcp-http/mcp"

Related Resources

Contributing

Issues and pull requests are welcome. Please open an issue first to discuss larger changes.

Disclosure

Collar is independent third-party infrastructure. Not built, operated, or endorsed by Robinhood. COLR is a separate token, not affiliated with Robinhood Markets, Inc.

License

MIT — see LICENSE.