# Collar Guardrail

> Pre-trade risk layer for autonomous AI trading agents on Robinhood Chain
> (chain ID 4663). Deterministic policy checks BEFORE execution. Returns
> allow / warn / deny with machine-readable reasons, a risk score, and a
> tamper-evident SHA-256 audit hash.

## What this service does

Collar evaluates a proposed trade against a risk policy and returns a
verdict before the trade is executed. It sits between an autonomous agent
and any execution venue (DEX, lending protocol, perpetual) on Robinhood
Chain. Also provides token safety checks, balance simulation, and
verifiable audit trails.

## When to use it

Call Collar before submitting any trade on Robinhood Chain if you are:
- An autonomous trading agent
- A programmatic wallet or bot
- A system that needs rate limiting, asset restrictions, or runaway-agent
  detection enforced outside your own runtime

## MCP server (recommended for agents)

MCP endpoint:      /mcp-http/mcp
Server name:       colr-guardrail
Transport:         Streamable HTTP (MCP protocol 2025-06-18)
Authentication:    none required
Fixed tier:        Tier 1 ($5,000 notional ceiling)
Discovery card:    /.well-known/mcp/server-card.json
Registry listings: Smithery (smithery.ai), official MCP Registry

Tools exposed (each declares inputSchema, outputSchema, and annotations):

  evaluate_trade(wallet, asset, contract_address, side, amount,
                 max_slippage_bps=100, request_id=None)
      Pre-trade risk check. Call BEFORE executing any trade.
      Treat a "deny" decision as a hard stop.
      Returns: decision, reasons, notional, price, price_source,
      risk_score, audit_hash.

  check_token_safety(contract_address)
      Honeypot / contract safety check for any ERC-20.
      Returns severity (safe / warn / danger), risk factors,
      sell-simulation result.

  simulate_balance(token_address, holder, delta, decimals=18)
      Read-only eth_call state override. Simulate a wallet's ERC-20
      balance after a hypothetical trade. No transaction is sent.

  get_supported_assets()
      List every asset in the official Robinhood Chain registry, with
      canonical contract addresses. Resolve symbol -> contract_address
      BEFORE calling evaluate_trade. Mismatched addresses are treated
      as fake-token attempts and denied.

  verify_audit_trail(wallet, limit=100)
      Recompute every past decision's SHA-256 hash and verify the
      hash-chain links. healthy=true only if unbroken.

## MCP authentication model (read this)

MCP has no way to carry a per-wallet signature, so MCP callers are
evaluated at a FIXED TIER 1 ceiling ($5,000 notional). MCP callers do
NOT get COLR tier gating. The per-wallet rate limiter keys on whatever
wallet string you pass.

If you need real tier limits (Tier 2 $25,000 or Tier 3 $100,000), use
the REST API with wallet-signature authentication. See the Auth section
below.

This is deliberate: MCP is an ADVISORY channel. A verdict is advice.
Your own runtime is responsible for executing or not executing.

## REST API (authenticated, tier-gated)

POST /api/v1/analyze/trade
Authorization: Bearer <jwt>
Content-Type: application/json

Request body:
{
  "wallet": "0x...",
  "asset": "NVDA",
  "side": "buy",
  "amount": 1.0,
  "contract_address": "0x...",
  "request_id": "uuid-v4"    (optional, idempotency key)
}

Response:
{
  "decision": "allow" | "warn" | "deny",
  "reasons": ["...", "ADVISORY: ..."],
  "tier": 1 | 2 | 3,
  "max_trade_usd": 5000,
  "risk_score": 12,
  "price_usd": 145.23,
  "price_source": "oracle" | "uniswap_v4" | "fallback_default" | "unavailable",
  "request_id": "uuid-v4",
  "audit_hash": "sha256:..."
}

POST /api/v1/demo/analyze
Public, unauthenticated. Same body. Fixed Tier 1. Rate-limited.

GET /api/v1/assets
Full official asset registry.

POST /api/v1/token-safety
Honeypot / contract safety check.

POST /api/v1/simulate-balance
ERC-20 balance simulation via state override.

GET /api/v1/audit/verify/{wallet}?limit=N
Recompute audit trail hashes and verify chain integrity.

## x402 paid endpoint

POST /api/x402/analyze
Same body as /api/v1/analyze/trade. Requires x402 payment header.
Price: 0.01 USDG per call.
Network: Robinhood Chain (eip155:4663).
Facilitator: https://facilitator.ultravioletadao.xyz
Registered in x402 Bazaar for automatic agent discovery.

## Decision semantics

  allow: policy passed, safe to execute.
  warn:  policy soft-violated. Trade may proceed but is flagged.
         Reasons are advisory.
  deny:  policy hard-violated. Do NOT execute. Reasons are blocking.

Any reason string starting with "ADVISORY:" is non-blocking. All other
reasons inherit their weight from the overall decision.

## Tier limits (REST API only)

  Tier 1 (1,000+ COLR): $5,000 max per trade
  Tier 2 (2,500+ COLR): $25,000 max per trade
  Tier 3 (5,000+ COLR): $100,000 max per trade

Wallets without COLR get Tier 1 automatically.

## Authentication flow (REST API)

1. GET /api/v1/auth/nonce?address=0x...
   -> { "message": "..." }
2. Sign the message with EIP-191 (personal_sign). No gas, no approval.
3. POST /api/v1/auth/wallet
   Body: { "address": "0x...", "signature": "0x..." }
   -> { "access_token": "jwt...", "preview_mode": bool }
4. Use Authorization: Bearer <access_token> on /api/v1/analyze/trade.

## Rate limits

The demo endpoint and analyze endpoint share a 60-second sliding window
rate limit per wallet address. Back-to-back calls may affect each other.
This is real behavior, not an error.

## Contact and docs

X (Twitter):    https://x.com/collarfamily
Docs:           https://backendai-x4m1.onrender.com/docs.html
Agent docs:     https://backendai-x4m1.onrender.com/agent-docs.html
Spec:           https://backendai-x4m1.onrender.com/spec.html
Test vectors:   https://backendai-x4m1.onrender.com/test-vectors.html
API status:     https://backendai-x4m1.onrender.com/
MCP on Smithery: https://smithery.ai (search "collar")

## 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.