# 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

## Discovery

| Path | Purpose |
|---|---|
| `/.well-known/mcp-server-card.json` | MCP server card (canonical, flat) |
| `/.well-known/mcp/server-card.json` | Alias of the above (nested) |
| `/.well-known/mcp.json` | Alias of the above |
| `/.well-known/agent-card.json` | A2A agent card |
| `/.well-known/agents.json` | Alias of agent-card.json |
| `/agents.json` | Alias of agent-card.json (root) |
| `/.well-known/x402.json` | x402 payment discovery |
| `/.well-known/glama.json` | Glama directory metadata |
| `/.well-known/ai-catalog.json` | AI catalog entry |
| `/.well-known/methodology.md` | Risk score methodology (agent-readable) |
| `/methodology.html` | Same methodology, human-readable |
| `/status.json` | Live service status (machine-readable) |
| `/status` | Same status, human-readable |
| `/latency.html` | Live latency percentiles (p50/p95/p99) |
| `/metrics/latency.json` | Latency snapshot, machine-readable |
| `/.well-known/known-issues.json` | Public known-issues list |
| `/llms.txt` | This file |
| `/skill.md` | Skill-oriented summary |
| `/robots.txt` | Crawler rules |
| `/sitemap.xml` | Site map |

## 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)
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.
      If the response contains an "error" key, no verdict was produced.
      Treat it as a hard stop; do not execute the trade.
      IMPORTANT: honeypot findings (severity=danger) from
      check_token_safety automatically force a DENY.

  evaluate_trade_paid(wallet, asset, contract_address, side, amount,
                      max_slippage_bps=100, request_id=None,
                      payment_proof=None)
      Pre-trade risk check gated by an x402 payment. Evaluated as Tier 2
      ($25,000 ceiling, 10/25 per-minute rate limits). No COLR holdings
      are required — the on-chain payment is the credential.
      FLOW:
        1. Call WITHOUT payment_proof → returns a PaymentRequiredOutput
           describing the on-chain payment (network, asset, amount,
           payTo, resource).
        2. Settle the payment on-chain using an x402-capable client.
        3. Call again with payment_proof=<proof> → returns a full
           EvaluateTradeOutput with tier=2.
      If the response contains an "error" key, no verdict was produced
      and you must not trade.

  check_token_safety(contract_address)
      Honeypot / contract safety check for any ERC-20.
      Returns severity (safe / warn / danger), risk factors,
      sell-simulation result.
      CRITICAL: when severity=danger, evaluate_trade will auto-DENY
      the trade regardless of other checks. This is a hard stop.
      If the response contains an "error" key, the check failed —
      do not assume "safe".

  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.
      If the response contains an "error" key, the simulation failed.

  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.
      If the response contains an "error" key, verification could not
      run — do not assume the chain is intact.

## 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 — or the x402 paid
endpoint, which grants Tier 2 for a per-call fee without requiring the
caller to hold any COLR. See the x402 section below.

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

## COLR token

COLR is the utility token that unlocks higher tiers on the REST API.
It is NOT required for the MCP channel (MCP is always Tier 1).

- **Name:** Collar
- **Ticker:** COLR
- **Chain:** Robinhood Chain (eip155:4663)
- **Launch venue:** Pons Launchpad v2 only. No other DEX, launchpad, or CEX.
- **Creator tax:** 0% — we are not adding any optional creator tax on top
  of Pons v2's standard mechanics.
- **Contract address:** <TO BE ANNOUNCED AT LAUNCH>

Any token claiming to be COLR on any other venue is not ours. Always
verify the contract address before interacting.

## 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. severity=danger forces a DENY
on the next evaluate_trade for the same contract.

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.10 USDG per call.
Network: Robinhood Chain (eip155:4663).
Facilitator: https://robinhood-chain-x402.onrender.com
Discovery document: /.well-known/x402.json
Registered in x402 Bazaar for automatic agent discovery.

x402 payments are evaluated at Tier 2 ($25,000 max trade, 10/25
per-minute rate limits) WITHOUT requiring the caller to hold COLR.
On-chain payment is the credential.

Note: this endpoint is POST-only. A GET returns 405 by design.

## 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.
         Honeypot findings (severity=danger) always produce a deny.

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

If a tool response contains an "error" key, no verdict was produced.
Treat it as a hard stop and do not execute the trade.

## How the risk score is computed

The score is an integer 0-100 and is deterministic — same inputs,
same score. It is the sum of five categories:

  1. Registry & identity           max 30
  2. Contract safety               max 30
  3. Price & market data quality   max 15
  4. Wallet behavior               max 15
  5. Trade parameters              max 10

Bands:   0-30 allow | 31-70 warn | 71-100 deny

Hard overrides bypass the bands and force deny:
  - asset/contract_address mismatch (suspected fake token)
  - check_token_safety returned severity=danger recently
  - price_source=unavailable above the tier's advisory floor
  - any response with an "error" key

Exact per-signal weights within each category are intentionally not
published — publishing them enables adversarial tuning. The categories
and bands above are stable; the internal weights are not.

Full methodology (agent-readable):
  https://api.collarguardrail.com/.well-known/methodology.md
Human-readable:
  https://api.collarguardrail.com/methodology.html

## Service status, known issues and latency

Live status, known issues and latency:

  https://api.collarguardrail.com/status.json     (machine-readable)
  https://api.collarguardrail.com/status          (human-readable)
  https://api.collarguardrail.com/.well-known/known-issues.json
  https://api.collarguardrail.com/latency.html    (p50/p95/p99, human)
  https://api.collarguardrail.com/metrics/latency.json (machine)

Before reporting a problem, check /status first — if the issue is
already listed there, no action is needed from you.

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

The x402 paid endpoint is evaluated as Tier 2 regardless of COLR
balance — payment is the credential.

## 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 MCP endpoint, the demo endpoint, and the analyze endpoint share a
60-second sliding window rate limit per wallet address. Back-to-back
calls from the same wallet may affect each other. This is real behavior,
not an error — treat a 429 as "slow down", not "server broken".

The MCP endpoint additionally enforces a per-IP limit of 30 requests
per 60 seconds, advertised in /.well-known/mcp-server-card.json and
enforced in front of the MCP transport. Over-limit requests get HTTP
429 with a Retry-After header.

Recommended client behavior:
- Reuse the SAME request_id when retrying a request whose response you
  never saw. Use a NEW request_id for every genuinely new trade.
- On 429, honor the Retry-After header before retrying.
- Do not send more than 1 request per second per wallet in steady state.
- Reuse MCP sessions; do not open a new transport per request.

If your agent needs higher throughput, use the REST API with a wallet
signature (tier-gated) or the x402 paid endpoint (Tier 2) instead of
the MCP channel.

## Contact and docs

X (Twitter):    https://x.com/collarguardrail
Agent docs:     https://collarguardrail.com/agent-docs.html
MCP card:       https://api.collarguardrail.com/.well-known/mcp-server-card.json
Methodology:    https://api.collarguardrail.com/methodology.html
API status:     https://api.collarguardrail.com/status
Latency:        https://api.collarguardrail.com/latency.html
MCP on Smithery: https://smithery.ai (search "collar")

## Disclosure

Collar is the risk layer for autonomous finance on Robinhood Chain.
Deterministic, auditable, and independent.

COLR is our own utility token, issued and operated by the Collar team.
It is not affiliated with, endorsed by, or issued by Robinhood Markets,
Inc. or any Robinhood entity. Robinhood Chain is a public blockchain we
build on — using it does not imply any relationship with Robinhood.