A deterministic risk layer for autonomous trading agents.

Quickstart

Get up and running in under 2 minutes. This complete Python script demonstrates how to request a nonce, sign it, authenticate, and run a pre-trade risk check.

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

# Configuration
BASE_URL = "https://backendai-x4m1.onrender.com"
PRIVATE_KEY = "0x..."  # Your agent's private key
account = Account.from_key(PRIVATE_KEY)
wallet_address = account.address

# Step 1: Get authentication nonce
res = requests.get(f"{BASE_URL}/api/v1/auth/nonce", params={"address": wallet_address})
res.raise_for_status()
message_to_sign = res.json()["message"]

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

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

# Step 4: Analyze a trade before submission
headers = {"Authorization": f"Bearer {token}"}
trade_payload = {
    "wallet": wallet_address,
    "asset": "NVDA",
    "side": "buy",
    "amount": 10.0,
    "contract_address": "0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC",
    "request_id": "quickstart-test-001"
}

trade_res = requests.post(f"{BASE_URL}/api/v1/analyze/trade", json=trade_payload, headers=headers)
print("Trade Verdict Response:", trade_res.json())

Why Collar exists

Robinhood Chain is a blockchain built for autonomous trading agents. Agents on it are fast, tireless, and increasingly handling real money.

They are also probabilistic. Every LLM-based agent can hallucinate a token address, ignore its own risk rules under pressure, or be talked into a bad trade by a prompt injection hidden in some piece of data it happened to read. When that happens, the agent does not stop. It executes.

The existing risk tooling was not built for this. Most platforms in the space use machine learning to monitor activity across many chains. That is the right model for institutional security. It is not designed for the 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 answers.

When to use Collar

How Collar differs

There are already tools that watch on-chain activity. Most of them are excellent — for their intended audience. Collar is built around four choices that put it in a different shape.

Collar is not claiming to be the first risk tool on Robinhood Chain. It is claiming to be a specific shape of one: API-first, deterministic, and stock-token aware.

Overview

Collar evaluates trade requests against a deterministic policy before the integrating agent submits them for execution. Each request is checked against:

• USD trade notional limits based on wallet COLR tier.
• Real-time Chainlink oracle prices for the traded asset.
• Uniswap V4 pool prices as a fallback when the oracle is unavailable.
• Corporate-action pause state (oraclePaused()) for tokenized equities.
• Feed staleness relative to heartbeat, including US market hours and holidays.
• Oracle-vs-pool divergence (slippage / MEV guard).
• Asset restrictions configured for eligible tiers.
• Cluster-based request frequency (runaway-agent detection).
• Cluster-based 24h P&L (daily-loss guardrail).
• Contract-address mismatch against the official registry.
• Honeypot heuristics for unregistered tokens.

COLR is an access and tier-gating token

COLR is not the trade currency. Agents can submit trades involving other supported assets, such as ETH, USDG, or tokenized equities. The wallet's COLR balance determines the access tier:

While COLR has not launched, the API grants a default Tier 1 to every authenticated wallet. See preview-tier testing below.

Verdicts

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

Price resolution

Every trade is priced by a strict resolution order. The first source that yields a valid price wins:

1. Chainlink oracle — the primary source. The 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 — the fallback. If the oracle is unavailable, Collar reads the token's V4 pool directly. Registered assets also use this path; the contract address has already been validated against the official registry, so the pool we look up is for the real token.
3. Refusal — if neither source produces a price, the verdict is deny. Collar does not fall back to a hardcoded number: a fabricated price would make the tier-limit decision meaningless.

The price_source field in the response tells you which path was taken: oracle, uniswap_v4, or unavailable.

Slippage / MEV guard

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

Pass max_slippage_bps in the request body to set your tolerance (default 100 bps, max 1000). The hard 500 bps floor overrides any wider tolerance.

Asset registry

Returns every symbol and its official contract address. Robinhood adds new tokens over time — refresh this 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+)

Returns the wallet's current policy configuration.

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

Updates the blocked-asset list for Tier 2 and Tier 3 wallets.

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

Trade requests against a blocked asset receive a deny verdict.

Rate limiting and runaway-agent detection

Collar tracks request frequency over a rolling 60-second window, per wallet cluster, in Redis. A cluster is derived from the set of EOA addresses that funded the wallet in the last 7 days — rotating to a fresh wallet funded from the same source does not reset the counter.

• Tier 1: warn above 5 trades/min, deny above 15.
• Tier 2: warn above 10, deny above 25.
• Tier 3: warn above 20, deny above 50.

There is no separate API-level rate limit on /analyze/trade beyond this — it is the runaway-agent protection.

While COLR has not launched, every wallet is granted a default Tier 1. To test Tier 2 or Tier 3 behavior, add the header X-Preview-Tier: 2 (or 3). This header is silently ignored once COLR launches and a real balance check takes over.

Daily-loss guard

Collar reads the wallet's on-chain net flow over the last 24 hours from Blockscout and compares it against two thresholds:

Like the rate limiter, this check runs on the wallet cluster, not the individual address. If the cluster lookup fails, Collar falls back to per-wallet P&L rather than skipping the check — a failed lookup is never a path to reset the counter.

Market hours

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

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

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

Authentication

Authentication uses wallet signatures rather than API keys. The same private key the agent already holds for trading is used to sign a one-time challenge.

Request a one-time nonce and the exact message to sign. The nonce expires in 5 minutes and can only be used once.

Submit the wallet address and an EIP-191 signature of the message from the previous step.

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

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

Authenticated API requests use Authorization: Bearer <access_token>. To end a session immediately, call:

Analyze a trade

Submit a trade request for deterministic policy evaluation. 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:. All other entries are the reasons that actually drove the decision. When a trade is deny, the integrating agent should surface the first non-advisory reason as the cause.

x402 — agent-native payments

Agents that don't hold a wallet identity can pay per call using the x402 protocol. Instead of signing a JWT, the agent pays a small amount of USDG 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.01 USDG payment on Robinhood Chain (chain ID 4663).

Flow

1. Agent sends the trade request without any payment header. The server responds with 402 Payment Required and a list of accepted payment options.
2. Agent signs an EIP-3009 transferWithAuthorization (gasless) for $0.01 USDG to the Collar recipient address.
3. Agent resends 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.

USDG uses the EIP-712 domain {"name": "Global Dollar", "version": "1"}. The uvd-x402-sdk Python package handles the domain automatically for the robinhood network — integrators do not need to construct it by hand.

Client example

from decimal import Decimal
from uvd_x402_sdk import X402Client

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

# 1. Get the 402 challenge, then build the payment header
header = client.create_authorization(
    pay_to="0xdD3596F3eE3BE02d4C6AFd23dC9E1833aDc47934",
    amount_usd=Decimal("0.01"),
    chain_name="robinhood",
    token_type="usdg",
    valid_duration=300,
)

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

x402 is optional. Agents that already hold a wallet signature and JWT continue to use /v1/analyze/trade without any payment.

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). Collar uses the standalone fastmcp package, which supports structured outputs (outputSchema) and tool annotations. The root endpoint reports whether MCP is live:

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

Tools exposed

Authentication model

MCP has no way to carry a per-user wallet signature, so MCP callers are evaluated at a fixed Tier 1 ceiling ($5,000 notional), regardless of their COLR balance. Tier gating requires the REST API with wallet-signature authentication.

The per-wallet rate limiter keys on whatever wallet string the caller supplies, so the runaway-agent protection is only as strong as the caller's honesty here. This is acceptable for an advisory guardrail but must not be described as authenticated access.

Client configuration example

Claude Desktop, Cursor, and most MCP clients accept a JSON config. Point them at the Streamable HTTP endpoint:

{
  "mcpServers": {
    "collar": {
      "url": "https://backendai-x4m1.onrender.com/mcp-http/mcp"
    }
  }
}

For a machine-readable summary of every MCP tool, see /llms.txt. Agents that do not speak MCP can still use the REST API, and agents that hold no wallet can pay per call via x402.

Agent discovery

Collar exposes machine-readable discovery files so autonomous agents can find, understand, and call the guardrail without any manual integration on the developer's side.

How an agent finds Collar

1. An agent crawler hits backendai-x4m1.onrender.com.
2. It checks /robots.txt → allowed.
3. It checks /sitemap.xml → discovers the full page set.
4. It checks /llms.txt or /.well-known/llms.txt → reads the full API contract.
5. It checks /.well-known/agent-card.json → sees the A2A skills.
6. If it is MCP-native, it connects to /mcp-http/mcp and lists the tools.
7. If it prefers x402, it discovers Collar through the x402 Bazaar catalog and pays per call.

Verify discovery is live

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

The llms.txt, robots.txt, and sitemap.xml endpoints are excluded from the Swagger UI schema (include_in_schema=false) so they do not clutter /docs.

Error responses

What's next

Verified against mainnet

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

The V4 fallback, slippage guard, cluster rate limiting, and daily-loss guard are all 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.