Opalith documentation

What Opalith is

Opalith is a research workspace for Robinhood Chain. You ask a question; an agent calls read-only tools that fetch live data from named sources; a model writes an answer that cites those sources. Every run shows the tools it called, what they returned, the sources with fetch times, and what the run cost.

It is not a trading app, a wallet or financial advice. Nothing in Opalith can send a transaction.

Tools

All tools are read-only. You can try each one on the Tools page without signing in.

Prices from the Robinhood API are per underlying share. Token-equivalent values multiply by the registry's current multiplier and are labeled as such. A token is a canonical Robinhood Stock Token only if its contract address is in the Robinhood registry; a matching name or ticker proves nothing.

The evidence envelope

Every tool returns the same shape, in the web app, in agent runs and over MCP:

{
  "tool": "stock_quotes",
  "data": { "quotes": [ { "symbol": "…", "bid": "…", "ask": "…", "generatedAt": "…" } ] },
  "summary": "1 of 1 quotes read. …",
  "sources": [ { "id": "robinhood-price-…", "name": "Robinhood quote …", "url": "…", "fetchedAt": "ISO-8601", "chainId": 4663 } ],
  "stale": false,
  "partial": false,
  "warnings": [],
  "units": { "bid": "USD per underlying share" },
  "error": { "code": "upstream_timeout", "message": "…", "retryable": true }   // only when the tool failed
}

• stale: at least one figure is older than the freshness limit for its source.
• partial: some sources answered and some did not; the warnings say which.
• units: what each number means. Amounts are decimal strings, never rounded floats.

Agent runs and limits

An agent is a name, instructions, a list of permitted tools, a model and a budget. Runs need a wallet sign-in. Each run moves through queued → connecting → reading → generating and ends as complete, partial, cancelled, failed or quota_exceeded.

Citations like [S1] point to the run's numbered sources. If the model cites a source that does not exist, the citation is replaced with “source missing” and a warning is shown.

Connecting your AI (MCP)

Sign in, open Connections, create a key with the tools it may use and an expiry, and paste the snippet for your client. The endpoint uses the Streamable HTTP transport, statelessly, with JSON responses. The key goes in the Authorization: Bearer header (or an environment variable your client reads), never in a URL. Each tool call counts against your hourly MCP quota.

Your data and privacy

• Agents, runs, watchlists and settings are stored in your browser (IndexedDB). Export and import them as JSON from Settings.
• The server keeps your address, session records, MCP key hashes, quota counters and run events needed to stream and audit runs.
• Questions you run are sent to the configured model provider together with the tool results.
• Addresses you look up are public chain data; Opalith does not link them to you beyond your own runs.

Security model

• Sign-in uses Sign-In with Ethereum: a one-time nonce, this site's domain, the chain id and a 10-minute expiry. Replays and wrong-domain messages are rejected.
• Sessions are HttpOnly cookies on this site's own domain; state-changing requests must come from an allowed origin.
• MCP keys are random, shown once, stored only as hashes, scoped to tools, expire, and can be rotated or revoked.
• No tool has a write path to the chain. The model only sees tool output, and tool inputs are validated before any request.

Known limitations

• No background monitoring or alerts. Watchlists refresh only when you press Refresh.
• new_pools works only when a pool indexer network is configured on the server.
• wallet_approvals scans a bounded block range; the result says which range was covered.
• Assets without a price source are shown as unpriced, not as zero.
• Stock-token quotes follow market hours; outside them they can be stale or halted.
• Answers are generated by a model and can be wrong. Check the sources before you act.

See Status for live source checks.