ChainOptics User Guide

01 — Dashboard Orientation

The dashboard is your live command center. Here's exactly what you're looking at when you first log in.

The Ticker Strip

The scrolling bar at the top of every page shows all 7 assets with their current price and 24-hour change. Green = up. Red = down. It updates automatically every 30 seconds — you don't need to refresh.

The Asset Cards

The main grid shows one card per asset. Each card displays:

• Symbol & Name — e.g., XRP / Ripple
• Current Price — live USD price from aggregated market data
• 24h Change — percentage change from 24 hours ago. Green = positive, red = negative
• 24h Volume — total USD trading volume in the last 24 hours
• Chain Health Badge — Pro/API tier. Indicates network status (Healthy / Degraded / Unknown)

Navigating the App

• Dashboard — all 7 assets, live grid view
• Assets — click any asset for full detail: price history chart, chain health metrics, transaction volume trends
• Portfolio — track your personal holdings against live prices
• Alerts — set price threshold notifications delivered to your email

Asset Detail Page

Click any asset card to open its detail page. You'll see:

• Price History Chart — 7-day default (Pro/API: up to 365 days). Toggle timeframe with the buttons above the chart.
• Chain Health Metrics — TPS (transactions per second), finality time, validator count, ledger status. This is the data that matters for infrastructure evaluation, not just price.
• OHLC Data — daily open/high/low/close with volume breakdown

Light / Dark Mode

The 🌙 / ☀️ button in the top-right of every page toggles your theme. Your preference is saved to your browser and persists across sessions.

02 — Settings & API Key

Finding Your API Key

1. Log in at /login
2. Your API key is displayed immediately on your dashboard under your account information
3. Click the key to copy it to your clipboard

Plan Tiers

Your tier determines what you can access:

• Free — Live prices for all 7 assets. 7-day history. 60 requests/min. No alerts. Great for exploration.
• Pro — Everything in Free, plus 365-day history, chain health metrics, 5 price alerts, and 300 requests/min.
• API Tier — Everything in Pro, plus unlimited alerts, webhook delivery, and 1,000 requests/min. Built for production integrations.

Compare plans and upgrade →

Using Your API Key

Pass your key in one of two ways:

# Option 1 — Header (recommended)
curl https://api.chainoptics.io/api/prices \
  -H "X-Api-Key: co_your_key_here"

# Option 2 — Bearer token
curl https://api.chainoptics.io/api/prices \
  -H "Authorization: Bearer co_your_key_here"

03 — Portfolio Tracker

The portfolio tracker lets you monitor your personal holdings against live ChainOptics price data — without ever sending your position data to our servers.

How to Add Holdings

Privacy — Your Data Stays Local

Portfolio holdings are stored in your browser's localStorage only. They never leave your device and are never sent to ChainOptics servers. This means:

• Clearing your browser data will clear your portfolio — export it first if needed
• Your holdings are private by design — we have no access to them
• Portfolio data does not sync across devices or browsers

04 — Price Alerts

Price alerts notify you by email when any asset crosses your specified threshold. Available on Pro and API tiers.

Creating an Alert

Alert Limits by Plan

• Free — 0 alerts (upgrade to Pro to unlock)
• Pro — 5 simultaneous active alerts
• API Tier — Unlimited alerts + webhook delivery

Managing Alerts

All active alerts are listed on the Alerts page. Click the delete icon next to any alert to remove it. Alerts auto-deactivate after triggering once — recreate them if you want ongoing monitoring.

05 — API Quick Start

Get live data into your application in under 5 minutes.

Step 1 — Get Your API Key

Sign up free at chainoptics.io/login → your API key is displayed immediately after account creation. It starts with co_.

Step 2 — Make Your First Call

curl https://api.chainoptics.io/api/prices \
  -H "X-Api-Key: co_your_key_here"

Step 3 — Parse the Response

{
  "success": true,
  "timestamp": "2026-03-02T18:00:00.000Z",
  "data": {
    "assets": [
      {
        "symbol": "XRP",
        "name": "Ripple",
        "price": 1.36899,
        "change24h": -1.52,
        "volume24h": 44949198.96,
        "marketCap": 78234000000,
        "chainHealth": "Healthy"
      }
      // ... 6 more assets
    ]
  }
}

JavaScript Example

const res = await fetch('https://api.chainoptics.io/api/prices', {
  headers: { 'X-Api-Key': 'co_your_key_here' }
});
const { data } = await res.json();
const xrp = data.assets.find(a => a.symbol === 'XRP');
console.log(`XRP: $${xrp.price} (${xrp.change24h}% 24h)`);

Python Example

import requests

headers = {'X-Api-Key': 'co_your_key_here'}
r = requests.get('https://api.chainoptics.io/api/prices', headers=headers)
assets = r.json()['data']['assets']
for a in assets:
    print(f"{a['symbol']}: ${a['price']:.5f} ({a['change24h']:+.2f}%)")

06 — API Endpoints Reference

Base URL: https://api.chainoptics.io — All requests require X-Api-Key header or Authorization: Bearer token.

Prices

Chain Health

Portfolio

Alerts

Account

Error Responses

// 401 — Missing or invalid API key
{ "success": false, "error": "Unauthorized" }

// 403 — Feature requires higher tier
{ "success": false, "error": "Pro plan required for chain health data" }

// 429 — Rate limit exceeded
{ "success": false, "error": "Rate limit exceeded", "retryAfter": 12 }

// 400 — Bad request
{ "success": false, "error": "symbol is required" }

07 — Rate Limits & Tiers

Rate limits apply per API key, per minute. Exceeding the limit returns a 429 response with a retryAfter value in seconds.

Handling Rate Limits

// When you receive a 429, wait before retrying
const res = await fetch('https://api.chainoptics.io/api/prices', {
  headers: { 'X-Api-Key': 'co_your_key_here' }
});

if (res.status === 429) {
  const { retryAfter } = await res.json();
  await new Promise(r => setTimeout(r, retryAfter * 1000));
  // retry your request
}

08 — Webhook Setup API Tier only

Webhooks push alert notifications directly to your endpoint the moment a price threshold is crossed. No polling required.

Configure Your Webhook URL

1. Log in and open Settings (top-right user menu)
2. Go to the Alerts tab
3. Enter your endpoint URL in the Webhook URL field
4. Click Save — webhooks activate immediately for all future alert triggers

Payload Format

ChainOptics sends a POST request to your endpoint with a JSON body:

{
  "event": "alert.triggered",
  "symbol": "XRP",
  "price": 2.01,
  "direction": "above",
  "threshold": 2.00,
  "triggeredAt": "2026-03-02T18:00:00.000Z",
  "alertId": "alrt_abc123"
}

Validating Requests

Every webhook request includes your API key in the X-ChainOptics-Key header. Validate this on your server to confirm the request is genuine:

// Node.js / Express example
app.post('/webhook', (req, res) => {
  const key = req.headers['x-chainoptics-key'];
  if (key !== process.env.CHAINOPTICS_API_KEY) {
    return res.status(401).send('Unauthorized');
  }
  const { symbol, price, direction } = req.body;
  console.log(`Alert: ${symbol} is ${direction} $${price}`);
  res.sendStatus(200);
});

Retry Behavior

If your endpoint returns anything other than a 2xx status, ChainOptics retries the delivery:

• Attempt 1 — Immediate on trigger
• Attempt 2 — 30 seconds after first failure
• Attempt 3 — 2 minutes after second failure

After 3 failed attempts, the webhook event is dropped. Your endpoint must respond within 5 seconds to avoid timeout.

10 — How to Read the Correlation Cascade

The correlation indicator on each asset detail page answers a specific question: is this asset moving because of macro pressure, or because of something happening in its own ecosystem? Understanding the answer changes how you interpret every price move.

What the Number Means

The Pearson correlation coefficient (r) runs from -1.0 to +1.0:

• +1.0 — Lockstep. The asset moves identically to the reference asset. Every BTC pump and dump is reflected in the price.
• 0.0 — Independent. The two assets are moving without relationship to each other.
• -1.0 — Inverse. When one goes up, the other goes down.

In practice, you rarely see the extremes. What matters is direction and magnitude over time.

The Two-Layer Cascade Logic

ChainOptics uses a deliberate two-layer reference hierarchy:

Layer 1 — XRP page: BTC/XRP correlation

Question it answers: Is XRP moving on general crypto sentiment, or on its own institutional thesis?

BTC is the macro benchmark for all crypto. When XRP is tightly correlated with BTC, the price action is being driven by the same forces moving everything — risk-on/risk-off, Fed policy, carry trade dynamics. When XRP starts diverging from BTC, something specific to Ripple's ecosystem is at work: regulatory progress, ODL volume spikes, RLUSD adoption, institutional accumulation, or new partnership announcements.

• High BTC/XRP correlation (red, ≥0.85): Watch macro — BTC leads, XRP follows. No edge in XRP-specific analysis right now.
• Moderate correlation (yellow, 0.60–0.84): Both forces are at work. Useful time to look for ecosystem-specific catalysts.
• Low correlation (green, <0.30): XRP is trading on its own fundamentals. This is when Ripple news, ODL volume reports, and regulatory developments are the signal — not BTC charts.

Layer 2 — Rail asset pages (XLM, HBAR, QNT, FLR, XDC, ALGO): XRP/[asset] correlation

Question it answers: Is this asset gaining independent strength within the digital rail narrative, or just riding XRP's momentum?

XRP is the dominant digital rail asset. When a smaller rail asset holds strong correlation with XRP, it means that asset is participating in the same institutional adoption story — not just general crypto sentiment. It suggests institutional and analyst attention is broadening across the category.

• High XRP/[asset] correlation (red): The asset is moving with XRP — likely caught in the same thesis wave. Not independently earning its move.
• Diverging (blue): The asset is starting to trade on its own fundamentals. Could indicate an asset-specific development or early accumulation.
• Decoupled (green): This asset is largely independent of XRP. Could be ecosystem-specific catalyst — or could be underperforming the category entirely. Context matters.

Reading the Cascade Together

The real signal comes from reading both layers at the same time:

7-Day vs 30-Day (Pro/API)

The 7-day coefficient is reactive — it captures recent momentum shifts and short-term divergence events. Use it to gauge current market behavior.

The 30-day coefficient (Pro/API) is structural — it smooths out noise and reveals whether a correlation shift is a genuine trend or a short-term anomaly. When the 7-day and 30-day diverge from each other, pay attention: the 7-day may be signaling a change in structural correlation that hasn't yet shown up in the 30-day.

09 — Support

Common Issues

• 401 Unauthorized — API key is missing, wrong, or revoked. Find your key in the dashboard.
• 403 Forbidden — The feature requires a higher tier. Upgrade here.
• 429 Too Many Requests — You've exceeded your rate limit. Wait for the retryAfter period or upgrade your plan.
• Alerts not arriving — Check your spam folder. Add support@chainoptics.io to your contacts.
• Portfolio cleared — Portfolio data is stored in browser localStorage. It does not sync across devices or survive a browser data clear.