A deterministic risk layer for autonomous trading agents.

Quickstart

The script below authenticates a wallet and runs a pre-trade risk check in four steps. It is complete and runnable as-is.

import requests
from eth_account import Account
from eth_account.messages import encode_defunct

BASE_URL = "https://api.collarguardrail.com"
PRIVATE_KEY = "0x..."  # your agent's private key
account = Account.from_key(PRIVATE_KEY)
wallet_address = account.address

# 1. Request a one-time nonce (returns the exact message to sign)
res = requests.get(
    f"{BASE_URL}/api/v1/auth/nonce",
    params={"address": wallet_address},
)
res.raise_for_status()
message_to_sign = res.json()["message"]

# 2. Sign the returned message (EIP-191)
signature = Account.sign_message(
    encode_defunct(text=message_to_sign),
    private_key=PRIVATE_KEY,
).signature.hex()

# 3. Exchange signature for a JWT
auth = requests.post(
    f"{BASE_URL}/api/v1/auth/wallet",
    json={"address": wallet_address, "signature": signature},
)
auth.raise_for_status()
token = auth.json()["access_token"]

# 4. Evaluate a proposed trade before signing it
verdict = requests.post(
    f"{BASE_URL}/api/v1/analyze/trade",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "wallet": wallet_address,
        "asset": "NVDA",
        "side": "buy",
        "amount": 10.0,
        "contract_address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
        "request_id": "quickstart-test-001",
    },
)
print(verdict.json())

Why the examples use NVDA

Robinhood Chain's distinguishing feature is tokenized US equities. NVDA is the canonical example throughout this document because it is a registered asset on the official registry, has a live Chainlink oracle, and exercises every stock-specific check (market hours, oraclePaused(), staleness windows). Using a generic ERC-20 would make the stock-token behavior invisible. The address shown is the real canonical contract — if you are integrating a different token, resolve its address from /api/v1/assets rather than copying this one.

Why Collar exists

Robinhood Chain is a blockchain built for autonomous trading agents. Those agents are fast, tireless, and increasingly handling real capital.

They are also probabilistic. An LLM-based agent can hallucinate a contract address, drift from its own risk rules under pressure, or be steered by a prompt injection embedded in data it happened to read. When that happens, the agent does not pause. It executes.

Existing risk tooling was not built for this. Most platforms use machine learning to monitor activity across many chains — the right model for institutional security, but not for an independent agent developer who needs a deterministic second opinion in one HTTP call.

Collar does not try to be smarter than the agent. It tries to be predictable in a way the agent cannot be. It sits outside the agent's runtime, at the last point before a trade is signed, and returns one of three verdicts.

When to use Collar

Design choices

Several tools already watch on-chain activity — most are excellent for their intended audience. Collar is built around five specific choices.

Overview

Network

What is evaluated

Each request is checked against the following dimensions in a fixed order:

• USD notional limit for the caller's access tier.
• Real-time Chainlink oracle price for the asset.
• Uniswap V4 pool price as a fallback when the oracle is unavailable.
• Corporate-action pause state (oraclePaused()) for tokenized equities.
• Feed staleness relative to the current market session.
• Oracle-vs-pool divergence (slippage / MEV guard).
• Per-wallet blocked-asset configuration.
• Cluster request frequency (runaway-agent detection).
• Cluster 24-hour realized P&L (daily-loss guard).
• Contract-address match against the official registry.
• Token safety heuristics for unregistered contracts.

Token safety heuristics are advisory-only. They surface findings as ADVISORY: reasons and do not by themselves produce a deny. The dedicated token-safety endpoint exposes the raw check on demand.

COLR and access tiers

COLR is an access and tier-gating token, not the trade currency. Trades may involve any supported asset (ETH, USDG, tokenized equities). The wallet's COLR balance determines the maximum notional per trade.

COLR is an 18-decimal ERC-20. Tier minimums above are expressed in whole COLR, not base units.

Verdicts

Verdicts are advisory. Collar does not currently enforce the decision at the blockchain or sequencer level.

Price resolution

Prices are resolved in a strict order. The first source that produces a valid value wins:

1. Chainlink oracle — primary source. A feed is rejected if oraclePaused() is true, if the answer is zero or negative, or if it is older than the freshness window (120 s during US market hours).
2. Uniswap V4 pool — fallback. If the oracle is unavailable, Collar reads the token's V4 pool directly. For registered assets the contract address has already been validated against the registry, so the pool queried is for the canonical token.
3. Refusal — if neither source produces a price, the verdict is deny. Collar does not substitute a hardcoded number; a fabricated price would make the notional check meaningless.

The price_source field identifies which path was taken:

Unregistered tokens

Contracts that are not on the official Robinhood RWA registry are evaluated under a stricter policy. By default, a trade on an unregistered contract is deny. The caller can opt in per request with allow_unregistered: true.

Token intelligence for unregistered contracts is sourced from an external security provider and cached for five minutes. Contracts that fail both the registry check and the external intelligence check are deny.

Slippage and MEV guard

When the reference price comes from the oracle, Collar also reads the live V4 pool spot and compares the two.

Set max_slippage_bps in the request body to declare a tolerance. Default is 100 bps; maximum is 1000. The 500 bps floor overrides any wider tolerance.

Asset registry

Returns every supported symbol and its canonical contract address. Robinhood adds tokens over time — refresh periodically rather than caching indefinitely.

[
  {
    "symbol": "NVDA",
    "contract_address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
    "is_native": false
  },
  {
    "symbol": "ETH",
    "contract_address": "NATIVE",
    "is_native": true
  }
]

Blocked-asset policy (Tier 2 and above)

Returns the caller's current policy configuration.

{
  "blocked_assets": ["MEME", "XYZ"],
  "editable": true
}

Replaces the blocked-asset list. Editable only for Tier 2 and Tier 3 wallets.

{ "blocked_assets": ["MEME", "XYZ"] }

Any trade request against a blocked asset receives a deny verdict.

Rate limiting and runaway-agent detection

Collar enforces two independent categories of rate limiting. The first governs API access. The second governs trade behavior.

API access limits (per client IP)

A 429 response includes Retry-After and X-RateLimit-* headers so clients can back off correctly.

Runaway-agent detection (per wallet cluster)

Trade evaluation frequency is tracked on a rolling 60-second window, keyed on the wallet's funding cluster rather than its address. A cluster is derived from the EOA addresses that funded the wallet in the previous seven days. Deriving a fresh wallet funded from the same source does not reset the counter.

There is no separate per-endpoint limit on /analyze/trade beyond this table — the cluster check is the runaway protection.

While COLR has not launched, every authenticated wallet is evaluated at Tier 1. To exercise Tier 2 or Tier 3 rate limits before launch, send the X-Preview-Tier: 2 (or 3) header on an authenticated request. This header is honored only on requests carrying a valid JWT and is ignored on the free and x402 endpoints. It is retired automatically once COLR is deployed.

Daily-loss guard

Collar reads the wallet cluster's on-chain net flow over the previous 24 hours and compares it against two thresholds.

Like the runaway check, this runs on the wallet cluster rather than the individual address. If cluster resolution fails, the check falls back to the individual wallet's P&L rather than skipping — a resolution failure is never a path to reset the counter.

Market hours

US equity markets are open Monday–Friday, 14:30–21:00 UTC. Collar adjusts staleness tolerance accordingly and applies early-close windows.

• Weekends: fully closed.
• Full-day holidays: New Year, MLK Day, Presidents Day, Memorial Day, Juneteenth, Independence Day, Labor Day, Thanksgiving, and Christmas — with the standard observed-on-Friday / observed-on-Monday shift.
• Early close: the day after Thanksgiving and Christmas Eve (weekday) — the market closes at 18:00 UTC instead of 21:00 UTC.

Outside market hours the staleness bound widens from 120 seconds to five days: the last oracle mark is still correct when the underlying exchange is closed.

Authentication

Authentication uses wallet signatures rather than API keys. The same private key the agent uses to sign trades is used to sign a one-time login challenge. No gas, no on-chain transaction, no approvals.

Returns a one-time nonce and the exact message to sign. The nonce expires in five minutes and is single-use — deleted atomically on the first verification attempt, so a second attempt against the same nonce always fails.

The message that must be signed

The message has the following shape (line endings are \n):

Sign in to the AI Trading Guardrail SaaS.

Wallet: 0x1234567890123456789012345678901234567890
Nonce: 3f9c1a2b4d5e6f708192a3b4c5d6e7f8
This request will not trigger a blockchain transaction or cost gas.

The wallet address in the message is always lowercase.

Submit the address and an EIP-191 signature of the message.

{
  "address": "0x1234567890123456789012345678901234567890",
  "signature": "0x..."
}

{
  "access_token": "eyJ...",
  "expires_in_seconds": 3600,
  "preview_mode": true
}

preview_mode: true indicates COLR has not launched and the balance gate is disabled. This becomes false after deployment.

Use the token on every subsequent request as:

Authorization: Bearer <access_token>

Immediately invalidates the caller's current token. Calling revoke with an already-expired or malformed token returns {"revoked": true} — the caller's goal (this token no longer works) is satisfied either way.

Analyze a trade

Evaluates a proposed trade under the caller's access tier. Requires authentication.

Request

{
  "wallet": "0x1234567890123456789012345678901234567890",
  "asset": "NVDA",
  "side": "buy",
  "amount": 12.5,
  "contract_address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
  "max_slippage_bps": 100,
  "request_id": "a1b2c3d4-..."
}

Fields

Response

{
  "decision": "allow",
  "reasons": ["All guardrail checks passed"],
  "tier": 1,
  "max_trade_usd": 5000.0,
  "calculated_notional_usd": 2728.72,
  "price_usd": 218.298,
  "price_source": "oracle",
  "risk_score": 18,
  "timestamp": 1757520000,
  "daily_pnl_usd": 0.0,
  "request_id": "a1b2c3d4-...",
  "audit_hash": "0x...",
  "audit_seq": 4821
}

Reason format

Advisory notes are prefixed with ADVISORY:. Any other entry contributed to the decision. When the verdict is deny, surface the first non-advisory reason as the cause.

Free endpoint

Accepts the same request body as /api/v1/analyze/trade but requires no JWT. Intended for the demo terminal, smoke tests, and the fallback path used by MCP and by agents that hold no wallet identity.

• Evaluated at a fixed Tier 1 ceiling ($5,000 notional).
• The X-Preview-Tier header is ignored on this endpoint.
• Returns the same response shape as the authenticated endpoint.
• Subject to a per-IP rate limit (see Rate Limiting).
• The request_id idempotency cache is shared with the authenticated endpoint. A repeated (wallet, request_id) pair within five minutes returns the cached verdict regardless of which endpoint produced it.

Public endpoints

The following endpoints are unauthenticated and rate-limited per IP. Each mirrors an MCP tool of the same name. All are evaluated under a Tier 1 ceiling and do not themselves unlock higher tiers.

Honeypot and contract-safety check for an ERC-20 contract. Combines a bytecode scan with a simulated sell. Rate limit: 20 requests / 60 s / IP.

// Request
{ "contract_address": "0x..." }

// Response
{
  "severity": "safe" | "warn" | "danger",
  "risk_factors": [ ... ]
}

Simulates an ERC-20 balance after a hypothetical trade using eth_call state override. No transaction is sent. Rate limit: 30 requests / 60 s / IP.

// Request
{
  "token_address": "0x...",
  "holder": "0x...",
  "delta": -12.5,
  "balance_slot": 3,          // optional; auto-discovered if omitted
  "decimals": 18
}

// Response
{
  "token_address": "0x...",
  "holder": "0x...",
  "balance_slot": 3,
  "current": 100.0,
  "delta": -12.5,
  "post_trade": 87.5
}

Audit trail

Every decision is appended to a tamper-evident hash chain. Each record's SHA-256 hash includes the previous record's hash, so editing, deleting, or reordering any entry breaks the chain for every subsequent entry.

All four accept a ?limit=N parameter (1–1000). Verify endpoints return a summary { total, tampered, healthy } alongside per-record results.

x402 — agent-native payments

Agents that do not hold a wallet identity can pay per call using the x402 protocol. Instead of signing a JWT, the agent settles a small USDG payment on Robinhood Chain and receives the verdict in the same round trip.

Same request body as /v1/analyze/trade. No JWT required. The endpoint enforces a $0.10 USDG payment on Robinhood Chain (chain ID 4663).

Flow

1. Send the trade request without a payment header. The server responds 402 Payment Required with the accepted payment options.
2. Sign an EIP-3009 transferWithAuthorization for $0.10 USDG to the pay-to address.
3. Resend the same request with the signed payload in the X-PAYMENT header.
4. The facilitator verifies the signature, settles on-chain, and the endpoint returns the verdict at Tier 2 limits.

Client example

from decimal import Decimal
from uvd_x402_sdk import X402Client

client = X402Client(recipient_address="0xYourWallet...")

header = client.create_authorization(
    pay_to="0xdD3596F3eE3BE02d4C6AFd23dC9E1833aDc47934",
    amount_usd=Decimal("0.10"),
    chain_name="robinhood",
    token_type="usdg",
    valid_duration=300,
)

# POST to /api/x402/analyze with X-PAYMENT: header

The uvd-x402-sdk handles the EIP-712 domain for the robinhood network automatically. Integrators do not need to construct it by hand.

GET probe

Some x402 discovery tools issue a bare GET to a resource before they know it expects a POST body. Collar exposes GET /api/x402/analyze that still enforces the payment challenge, so an unpaid probe sees the standard 402 rather than a bare 405. A paid GET returns a method_not_supported error, not a verdict — the analysis requires POST.

MCP server

Collar speaks Model Context Protocol natively, so any MCP-compatible agent — Claude Desktop, Cursor, Cline, Windsurf, or a custom client — can call the guardrail without writing integration code.

Streamable HTTP transport, MCP protocol version 2025-06-18. The root endpoint reports MCP status:

{ "status": "ok", "mcp_enabled": true, "mcp_http_endpoint": "/mcp-http" }

Tools

Authentication model

MCP carries no per-user wallet signature, so MCP callers are evaluated at a fixed Tier 1 ceiling ($5,000 notional), regardless of COLR balance. To reach higher tier limits, use either:

• the REST API with wallet-signature authentication (/v1/analyze/trade), which enforces the wallet's real tier, or
• the x402 paid endpoint (/api/x402/analyze), which grants Tier 2 limits per settled call.

Client configuration

Most MCP clients accept a JSON config. Point them at the Streamable HTTP endpoint:

{
  "mcpServers": {
    "collar": {
      "url": "https://api.collarguardrail.com/mcp-http/mcp"
    }
  }
}

A machine-readable summary of every tool is available at /llms.txt.

Agent discovery

Collar exposes machine-readable discovery files so autonomous agents can find, understand, and call the guardrail without manual integration.

How an agent discovers Collar

1. The crawler reaches api.collarguardrail.com.
2. Checks /robots.txt — allowed.
3. Reads /sitemap.xml for the page set.
4. Reads /llms.txt or /.well-known/llms.txt for the full contract.
5. Reads /.well-known/agent-card.json for A2A skills.
6. If MCP-native, connects to /mcp-http/mcp and lists tools.
7. If using x402, discovers Collar through the x402 Bazaar catalog and pays per call.

Verifying discovery

curl -s https://api.collarguardrail.com/llms.txt | head -20
curl -s https://api.collarguardrail.com/.well-known/llms.txt | head -5
curl -s https://api.collarguardrail.com/robots.txt
curl -s https://api.collarguardrail.com/sitemap.xml | head -20
curl -s https://api.collarguardrail.com/.well-known/agent-card.json
curl -s https://api.collarguardrail.com/.well-known/mcp/server-card.json

Health

Returns {"status": "ok"} when the service and its datastore are reachable, 503 otherwise. Use as a liveness probe.

Returns the service name, version, and MCP endpoint URLs. Useful for agents that hit the bare domain first.

Error responses

Roadmap

Verification

The oracle path has been exercised end-to-end against live Chainlink feeds on Robinhood Chain. Stock-token prices, oraclePaused() state, and staleness windows have all been validated against real mainnet data.

The V4 fallback, slippage guard, cluster rate limiting, and daily-loss guard are covered by the repository's automated test suite, which runs before every deployment.

Independence

Collar Guardrail is an independent third-party application built to provide a risk layer for autonomous trading workflows.

It is not built, operated, sponsored, or endorsed by Robinhood.

Robinhood Chain is the underlying network referenced by the integration. COLR is a separate token used for access and tier gating, launched on PONS v2.