11 — Learn
Insight documentation · Product logic, risk methodology, architecture, data sources, and integration references
Follow an oracle price from collection through consensus, health analysis, risk interpretation, and signed verification. Then connect the same evidence to your application or agent.
Index — Documentation map
Start with a task, inspect the method behind it, then move into the implementation reference when you are ready to integrate.
Get started with Insight in three steps. The platform aggregates price data from major oracle providers across 40+ blockchain networks for comprehensive market intelligence.
Select an oracle provider, blockchain, and token to get current prices with on-chain verification metadata.
Cross-oracle comparison with consensus price, cross-chain heatmap, and divergence signals.
Track oracle reputation over time and track stablecoin or wrapped-asset depeg risks.
Explore the core capabilities of the Insight oracle data platform.
Calculate the exact oracle price deviation that would trigger liquidation for your DeFi lending positions across multiple protocols.
Always-on cross-oracle trust signal (NORMAL / CAUTION / DANGER) that AI agents running long-lived strategies can poll and gate on between trades.
15-minute stablecoin depeg tracking across oracle providers and chains with protocol impact analysis.
Track WBTC, wstETH, cbETH, and other wrapped or liquid-staking tokens for deviations against their underlying assets.
Query current prices from any oracle provider with on-chain data, confidence intervals, and auto-refresh.
Compare oracle prices across providers and blockchains with consensus price, divergence signals, and risk analysis.
Persistent 7-day rolling reputation scores with accuracy, uptime, reliability, latency, and freshness metrics.
Daily aggregated oracle market snapshots with consensus prices, provider rankings, and stablecoin or wrapped-asset peg risk highlights.
Auto-Refresh
Live on-demand price polling
10 Oracle Providers
Chainlink, API3, RedStone, DIA, and more
Safety & Risk
Position, stablecoin, and wrapped asset tracking
Multi-format Export
CSV, JSON, Excel, PDF, PNG
Each pre-trade check is signed as an EIP-712 attestation (v1 11 fields, v2 26, v3 27). The public verify endpoint checks the signature against the published attester key and routes by the attestation's own schemaVersion. At v3 both safety gates are recomputable from the bytes alone, because both policy constants are inside the signed struct; the constants are also pinned in a machine-readable declaration.
No install, no API key. Open /verify and the page fetches a public sample receipt plus the published key registry, then re-checks the EIP-712 signature entirely on your device using verify-insight-receipt. Insight never sees the result.
For agents and protocols that need an independent verification path, the repository includes a standalone npm package — published as verify-insight-receipt (v0.2.0). It verifies pre-trade and execution receipts, including closed-loop pairs, by recomputing the EIP-712 hashes and recovering signers locally; it does not need an API key, database access, or a network request.
# Published package (recommended)
npm install verify-insight-receipt
# Or from the Insight repository
npm install ./verifier
import { verifyReceipt } from 'verify-insight-receipt';
const result = await verifyReceipt(receipt, { keyRegistry });
if (result.code !== 'ok') {
throw new Error(result.code);
}Verification is not endorsement. A valid result proves the signed bytes and signer relationship, not that the underlying trade or verdict was correct.
# fetch a real signed sample
curl -s https://www.oracleinsight.xyz/api/v1/safety/attestation/sample \
| jq .data.attestation > receipt.json
# verify it (public, no API key)
curl -s https://www.oracleinsight.xyz/api/v1/safety/attestation/verify \
-H 'Content-Type: application/json' \
-d "{\"attestation\": $(cat receipt.json | jq -c)}"
# cross-check the pinned declaration (sha256 035144d0...)
curl -s https://www.oracleinsight.xyz/.well-known/vrt1-scale-declaration.json \
| shasum -a 256Deep dive into implementation details, data sources, and architecture.
Data collection, validation rules, and consensus algorithms that power Insight price intelligence.
Interactive API explorer with OpenAPI 3.1. Try endpoints live, generate code snippets, and import into Postman.
Next.js App Router with Supabase, React Query, Zustand, and 10 oracle client implementations.
10 oracle providers including Chainlink, API3, RedStone, DIA, WINkLink, Supra, TWAP, Reflector, Flare, and Switchboard.
Connect Claude, Cursor, and other MCP clients to oracle prices, risk summaries, pre-trade safety checks, Oracle Watch monitoring, liquidation stress tests, and more.
Use the complete execution workflow: two-sided pre-trade gates, Oracle Watch halt handling, and VERIFIED execution receipts.
Insight combines 15-minute oracle data with rigorous validation, multi-algorithm consensus, and a 7-day rolling reputation framework to produce reliable cross-provider price intelligence.
Prices are fetched from 10 oracle providers across 40+ blockchains. Each request reads either an on-chain contract or a verified API endpoint, then normalizes the result into a common PriceData structure that includes price, timestamp, decimals, confidence, and verification metadata.
Every raw price is validated before entering consensus or storage. Failures are not silently dropped; they are classified so the reputation system can distinguish between stale data, network errors, unsupported symbols, and fallback metadata.
Four consensus methods are computed for every symbol. The recommended method is chosen automatically based on asset category: stablecoins, major assets, altcoins, and micro-cap assets each get the method best suited to their typical volatility and provider coverage.
Middle value of sorted prices. Robust against extreme outliers when provider coverage is limited.
Mean after removing the top and bottom 25% of prices. Balances outlier resistance with responsiveness.
Median weighted by provider confidence (40%), price freshness (35%), and confidence-interval tightness (25%).
Removes outliers outside the interquartile range, then takes the median. Ideal for tight peg tracking.
Outliers are detected using Z-score over 2.5 standard deviations, dual-source arbitration when only two prices exist, and history-aware checks against the last 10 consensus points. Excluded providers are surfaced in the divergence UI and used to adjust confidence scoring.
Provider reputation is recomputed hourly from a 7-day rolling window of sampled price fetches. Each provider is benchmarked against a latency baseline that depends on whether it is an on-chain or API provider, so slower on-chain calls are not unfairly penalized.
Measures how close a provider's price is to the consensus. Scored as 100 − min(|deviation| × 15, 85), with a consistency bonus for low deviation variance.
Percentage of successful price fetches over a 7-day rolling window. Failed fetches are classified by failure mode for debugging.
Penalizes large deviations more aggressively than Accuracy (100 − min(|deviation| × 20, 80)). Same consistency bonus applies.
Scores how recently the on-chain / API data was updated. Degrades by 4 points per minute of stale data, capped at 90 points lost.
Response time against a provider-type baseline: on-chain providers typically get ~1,000 ms, API providers ~350–500 ms.
Average absolute deviation from consensus, bucketed into 0.1%, 0.5%, 1%, 2%, and >2% tiers.
A sample-size factor (0.85–1.0) is applied when fewer than 100 samples exist, and a consistency bonus of up to 4 points rewards providers with low deviation variance across at least 5 successful consensus comparisons.
Insight is a full-stack oracle analytics platform built for reliability, 15-minute assessment, and multi-provider comparison across blockchains.
Server-first rendering with App Router, colocated API routes, and optimized static generation for marketing and docs pages. Client components handle interactive dashboards.
React Query caches and synchronizes server state (prices, reputations, reports). Zustand manages lightweight UI state such as auth session and user preferences.
PostgreSQL stores price records, oracle feeds, API keys, reputation history, and daily reports. Row Level Security, database functions, and cron jobs run inside the database.
A unified abstraction wraps 10 oracle providers. Each client handles chain-specific calls, retries, TTL caching, and normalization into a common PriceData format.
Public v1 endpoints expose prices, batch queries, history, and reports. Internal endpoints power stablecoin depeg, wrapped-asset tracking, and protocol-health features.
Supabase pg_cron dispatches six product-critical workflows through pg_net using a token encrypted in Vault. Dependency-free GitHub runners perform the heavy work, guarded native schedules provide fallback, and a 30-day ledger records completion. Vercel is not used for background compute.
| Table | Purpose |
|---|---|
| price_records | Raw and normalized prices with TTL |
| oracle_feeds | Active feed metadata per provider + chain |
| hourly_price_snapshots | Hourly-grain snapshots (upsert, 120-day retention) |
| price_snapshots | 15-min-grain snapshots for ML / anomaly detection (120-day retention) |
| reputation_history | Per-fetch samples for scoring |
| oracle_reputation | Aggregated 7-day provider scores |
| api_keys | Key-based API authentication |
| daily_reports | Generated market snapshots |
The OracleClientFactory creates singleton provider clients that inherit from BaseOracleClient. Each implementation translates provider-specific identifiers (feed addresses, price IDs, dAPI names) into the unified PriceData shape.
Collect price snapshots from all oracle feeds (dual-writes hourly + 15-min tables)
Persist the Oracle Watch credibility history and trust signal
Fetch provider samples and recompute 7-day rolling scores (GitHub Actions)
Refresh per-feed observed staleness baselines (GitHub Actions)
Backfill outcome labels for pre-trade safety checks
Sync protocol TVL from DefiLlama
Sync per-asset risk parameters from lending protocols
Re-probe deactivated feeds and revive recovered ones
Generate and persist the daily report
Grant subscription credit allowances, downgrade expired subs, clean up zombie invoices
Discover new oracle feeds from each provider’s official API
Retrain the oracle-risk ML model and trigger a Vercel redeploy
Zod schemas validate PriceData and API requests. Invalid payloads are rejected before reaching business logic.
AppError and OracleServiceError classify failures (network, timeout, unsupported symbol, stale data) for observability and retries.
Each API key carries a plan-based rate limit. Usage is logged per endpoint for billing and abuse detection.
Supabase RLS policies ensure users can only read their own API keys and profile data.
Insight aggregates price data from leading oracle providers across 40+ blockchain networks, normalizing every feed into a common format for comparison and analysis.
| Provider | Type | Chains |
|---|---|---|
| Chainlink | On-chain | EVM L1s & L2s |
| API3 | On-chain dAPIs | Ethereum, Arbitrum, Base, Polygon, others |
| RedStone | API / On-chain | EVM L1s & L2s |
| DIA | API / On-chain | EVM L1s & L2s |
| WINkLink | On-chain | TRON |
| Supra | API / On-chain | EVM, Move, Cosmos ecosystems |
| TWAP | On-chain | DEX TWAP oracles |
| Reflector | On-chain | Stellar / Soroban |
| Flare | On-chain | Flare Network |
| Switchboard | API / On-chain | EVM, Solana, Sui, Aptos (Crossbar) |
Every on-chain feed includes contract addresses and explorer links so you can verify the source directly. API feeds are labeled as API Verified and include the source display name.
Integration guides, code examples, and answers to common questions.
Programmatic access to oracle prices, history, and batch queries with API keys.
Add two-sided pre-trade gates, Oracle Watch halt handling, and verified execution receipts to a DeFi agent.
Verify pre-trade and execution receipts locally — published on npm as verify-insight-receipt (v0.2.0). No API key, database access, or dependency on Insight being online.
Connect AI agents like Claude and Cursor via the Model Context Protocol — with pre-trade oracle safety checks and the always-on Oracle Watch signal.
View data fetching and analysis examples in JavaScript and TypeScript.
Common developer questions about symbols, providers, and historical data.
We support 10 oracle providers: chainlink, api3, redstone, dia, winklink, supra, twap, reflector, flare, and switchboard. Each provider supports different blockchains and trading pairs.
We support 4 consensus methods: median, trimmed_mean, weighted_median, and iqr_filtered. The best method is auto-selected based on data characteristics.
Symbols containing "/" must be URL-encoded. For example, BTC/USD should be sent as BTC%2FUSD in the URL path.
Historical data is provider-specific and cannot be aggregated across oracles. You must specify which oracle provider to query, e.g., ?provider=chainlink.
The verifier is published on npm as verify-insight-receipt (v0.2.0): run npm install verify-insight-receipt, then call verifyReceipt(), verifyExecutionReceipt(), or verifyExecutionPair(). It recomputes the EIP-712 hashes and recovers signers locally without an API key, database access, or network request. Pass the published oracle-keys.json document separately when you also want key-window status. You can also install directly from the repository verifier/ directory.