Skip to content
BranchesTags

Latest commit

 

History

14 Commits

Folders and files

NameName
Last commit message
Last commit date
.github/workflows
.github/workflows
 
 
cryptodesk
cryptodesk
 
 
.gitignore
.gitignore
 
 
DEPLOYMENT.md
DEPLOYMENT.md
 
 
README.md
README.md
 
 

Repository files navigation

CryptoDesk

CryptoDesk is an AI-powered on-chain intelligence terminal that turns raw crypto market data into actionable trading decisions.

Instead of acting like a standard news aggregator or signal bot, CryptoDesk works as a full data-to-decision pipeline. It fetches real market data from SoSoValue, classifies signals with Grok AI, generates ranked opportunities with explainability, runs multi-agent investment committee reviews, and previews execution on SoDEX. The frontend is a single-page React app; a thin serverless proxy (Netlify Functions) holds the SoSoValue and Grok API keys server-side so no secret ever reaches the browser.

CryptoDesk gives solo researchers and retail traders a Bloomberg-grade intelligence loop without the Bloomberg budget.

Table of Contents

Core Logic Flow

flowchart TD
    A["Raw Market Data Ingestion"] --> B{"AI Sentiment Analysis"}
    B -- "Bullish" --> C["Rank as Opportunity"]
    B -- "Bearish" --> D["Risk Warning / Block"]
    B -- "Neutral" --> E["Contextual Monitoring"]

    C --> F["Investment Committee Review"]
    F --> G["Execution Preview on SoDEX"]
    G --> H["Final Order Preparation"]
    
    D --> I[Signal Archive]
    E --> I
    H --> I
    I --> J["Track Record — Live Price Grading"]
    J --> K["Hit Rate + Avg Return, Not AI Output"]
Loading

Overview

CryptoDesk is designed for:

  • Solo crypto researchers
  • Retail traders
  • DeFi users
  • Signal groups
  • Market analysts
  • Portfolio managers
  • DAO contributors
  • Trading communities

The product provides a complete intelligence terminal experience:

Open the app — SoSoValue + Grok already run on server-side keys, no setup required
↓
Live news feed → AI signal classification → Ranked opportunities
↓
Investment committee review → Strategy playbook → SoDEX execution preview
↓
Track Record grades every signal against live prices, no AI involved

CryptoDesk delivers:

5 live articles → 2 AI signals → 40% bullish sentiment
Top Opportunity: ETH — Buy — 78% confidence
Committee: Analyst  Risk  Macro  Execution 
Strategy: Ethereum ETF Momentum — 14 days — Medium risk
Execution: Preview on SoDEX testnet — 0.12% slippage

Problem

Crypto users make trading decisions with fragmented tools and incomplete data.

Common problems include:

  • News, signals, and execution are spread across different platforms.
  • Traders act on hype without understanding risk context.
  • Signal bots provide recommendations with no explainability.
  • No connection exists between market intelligence and trade execution.
  • Retail traders cannot access institutional-grade analysis workflows.
  • Portfolio construction is disconnected from real-time market data.
  • Market narrative shifts are invisible until it is too late.

Most crypto tools solve one piece of the puzzle.

CryptoDesk connects every piece — from data ingestion to execution preview.

Solution

CryptoDesk creates a unified intelligence terminal that handles the entire trading decision workflow.

It helps users answer:

  • What is happening in the market right now?
  • Which news items are actionable signals?
  • What opportunities exist and why?
  • What do multiple AI agents think about this trade?
  • What is the optimal portfolio allocation?
  • Which narratives are rotating?
  • What does the execution look like on SoDEX?
  • What is my signal history and audit trail?

Core Features

1. Real-Time News Feed

CryptoDesk pulls live crypto news from SoSoValue's OpenAPI.

Sources:

  • Latest news (/news)
  • Hot news (/news/hot)
  • Featured news (/news/featured)

Features:

  • Category filtering (Breaking, Research, Institutional, KOL)
  • Tab switching (Latest, Hot, Featured)
  • Article count badges
  • Real-time reload

2. AI Signal Classification

Grok AI automatically classifies the top 5 news articles on every feed load.

Each signal includes:

Field Output
Sentiment Bullish, Bearish, or Neutral
Confidence 0–100%
Affected Assets ETH, BTC, SOL, etc.
Impact High, Medium, or Low
Time Horizon Short, Medium, or Long
Recommendation Buy, Sell, or Hold
Risk Low, Medium, or High
Reason One-sentence explanation

3. Opportunity Discovery Engine

CryptoDesk builds ranked opportunities from classified signals and news data.

Each opportunity card shows:

  • Asset and recommendation
  • Confidence score
  • Why? bullets — explainability for every recommendation
  • Risks — risk drivers from AI assessment
  • One-click actions: Risk Assess, Committee Review, Strategy, Execute on SoDEX

4. Investment Committee

A multi-agent AI review system that simulates an institutional investment committee.

Agent Role
Analyst Market view and thesis
Risk Agent Risk assessment and drivers
Macro Agent Macro context and conditions
Execution Agent SoDEX readiness and slippage

Output:

  • Final recommendation (Buy / Sell / Hold)
  • Confidence score
  • Risk level
  • Allocation percentage
  • Slippage estimate
  • Supporting reasons

5. Portfolio Intelligence Agent

Users configure:

  • Capital amount
  • Risk tolerance (Conservative / Balanced / Aggressive)
  • Goal (Growth / Income / Preservation)

CryptoDesk generates:

  • Asset allocations with percentages
  • Per-asset reasoning
  • Portfolio thesis
  • Risk control note

6. Narrative Rotation Scanner

Detects capital rotation between crypto narratives and sectors.

Output:

  • Current dominant narrative
  • Current momentum (Strengthening / Stable / Weakening)
  • Emerging narrative
  • Emerging momentum
  • Rotation insight

7. SSI Index Builder

Designs custom thematic indices aligned with SoSoValue's SSI Protocol.

Features:

  • Theme selection (AI Index, DeFi, L1/L2, etc.)
  • Grok-designed constituents with weights
  • Live alignment with SoSoValue SSI data when connected
  • Methodology and rebalance rules

8. Research Copilot

Free-form conversational research assistant.

Users ask any crypto question and receive structured, actionable answers grounded in the current SoSoValue news feed.

9. Strategy Generator

Generates trade strategy playbooks from any opportunity.

Output:

  • Strategy name
  • Entry guidance
  • Risk level
  • Time horizon
  • Action (Buy / Sell / Hold / Accumulate)
  • Thesis
  • Exit criteria

10. SoDEX Trading Terminal

Full market data terminal connected to SoDEX testnet:

  • Live ticker data (15s refresh)
  • Orderbook depth visualization
  • Dual kline charts (SoDEX + SoSoValue)
  • Recent trades feed
  • Execution preview card (bound to opportunity + committee data)
  • EIP-712 order builder (JSON body, typed data, curl preview)

11. Watchlist with Alerts

  • Add any token to watchlist
  • Cross-reference with live signals and opportunities
  • Automatic alerts when watchlist assets have high-severity signals
  • Toast notifications for watchlist events

12. Signal Archive & Order Audit

  • Persistent signal archive (session history)
  • Export signal history as JSON
  • Order audit trail for prepared SoDEX orders
  • Export order audit as JSON

13. Track Record (Quantitative Validation)

The one panel in CryptoDesk that produces no AI output — it grades the AI's own calls.

  • Live entry price captured the moment a signal enters the archive
  • Graded ≥1h later against the live SoSoValue price (±1% neutral band)
  • Hit rate, average return, and sample size — sliced by confidence bucket
  • No simulated or backfilled data: ungraded signals are labeled "pending" or "awaiting baseline," never silently dropped

How CryptoDesk Works

flowchart TD
    A["App Loads — Server-Side Keys Already Live"] --> B["Fetch SoSoValue News Feed via Proxy"]
    B --> C["Grok Auto-Classifies Top 5 Signals via Proxy"]
    C --> D[Build Ranked Opportunities]
    D --> E["Show Opportunity Cards with Explainability"]
    E --> F{"User Action"}
    F --> G["Risk Assessment"]
    F --> H["Investment Committee Review"]
    F --> I["Strategy Playbook"]
    F --> J["Execute on SoDEX"]
    G --> H
    H --> J
    I --> J
    J --> K["Execution Preview Card"]
    K --> L["EIP-712 Order Builder"]
    L --> M["Order Audit Trail"]
    D --> N["Signal Archive — Entry Price Captured Live"]
    N --> O["Track Record — Graded ≥1h Later vs Live Price"]
Loading

System Architecture

flowchart LR
    subgraph Frontend["Frontend — Vite + React"]
        A["Masthead + Trust Bar"]
        B["News Feed"]
        C["Intelligence Panel"]
        D["SoDEX Terminal"]
        E["Settings Modal"]
        TR["Track Record Panel"]
    end

    subgraph Backend["Backend — Netlify Functions"]
        PX1["grok.js proxy"]
        PX2["soso.js proxy"]
    end

    subgraph AILayer["AI Layer — Grok"]
        F[Signal Classifier]
        G[Opportunity Explainer]
        H[Investment Committee]
        I[Research Copilot]
        J[Portfolio Agent]
        K[Narrative Scanner]
        L[SSI Index Builder]
        M[Strategy Generator]
        N[Daily Briefing]
    end

    subgraph DataSources["External Data Sources"]
        O[SoSoValue OpenAPI v1]
        O2[api.x.ai — Grok]
        P[SoDEX Spot REST API v1]
    end

    subgraph Storage["Client Storage — sessionStorage"]
        Q[Optional BYOK Override + Preferences]
        R[Watchlist + Order Audit]
        S[Signal Archive + Entry Prices]
    end

    B --> PX2
    TR --> PX2
    D --> P
    C --> F
    C --> G
    C --> H
    C --> I
    C --> J
    C --> K
    C --> L
    C --> M
    C --> N
    F --> PX1
    G --> PX1
    H --> PX1
    I --> PX1
    J --> PX1
    K --> PX1
    L --> PX1
    M --> PX1
    N --> PX1
    PX1 -- "GROK_API_KEY, server env" --> O2
    PX2 -- "SOSO_API_KEY, server env" --> O
    A --> PX2
    E --> Q
    TR --> S
Loading

User Flow

sequenceDiagram
    participant User
    participant UI as CryptoDesk UI
    participant Proxy as Netlify Functions
    participant SoSo as SoSoValue API
    participant Grok as Grok AI
    participant SoDEX as SoDEX API
    participant Store as sessionStorage

    Note over UI,Proxy: No key entry required — Proxy already holds server-side keys
    UI->>Proxy: POST /.netlify/functions/soso { path: /news }
    Proxy->>SoSo: GET /news (SOSO_API_KEY attached server-side)
    SoSo-->>Proxy: News articles
    Proxy-->>UI: News articles
    UI->>Proxy: POST /.netlify/functions/grok { classify top 5 }
    Proxy->>Grok: Classify top 5 articles (GROK_API_KEY attached server-side)
    Grok-->>Proxy: Signal classifications
    Proxy-->>UI: Signal classifications
    UI->>UI: Build ranked opportunities
    UI->>Store: Archive signal + capture live entry price
    UI-->>User: Display news + signals + opportunities

    alt User clicks Risk Assess
        UI->>Proxy: Assess opportunity risk
        Proxy->>Grok: Assess opportunity risk
        Grok-->>UI: Risk drivers + conviction
    end

    alt User clicks Committee Review
        UI->>Proxy: Run 4-agent committee
        Proxy->>Grok: Run 4-agent committee
        Grok-->>UI: Committee verdict + allocation
    end

    alt User clicks Execute on SoDEX
        UI->>SoDEX: Fetch ticker + orderbook + klines
        SoDEX-->>UI: Market data
        UI-->>User: Show execution preview
    end

    alt User opens Track Record (≥1h after archiving)
        UI->>Proxy: Fetch live price for archived asset
        Proxy->>SoSo: GET /currencies/{id}/market-snapshot
        SoSo-->>UI: Live price
        UI->>UI: Grade entry price vs live price
        UI-->>User: Hit rate + avg return, real data only
    end

    alt User adds to Watchlist
        User->>UI: Add token
        UI->>Store: Save to sessionStorage
    end
Loading

Data Flow

flowchart TD
    A[SoSoValue News Feed] --> B[Signal Classification — Grok]
    A --> C[Lexicon Scoring — Local]

    B --> D[Classified Signals]
    C --> D

    D --> E["Opportunity Builder"]
    E --> F["Ranked Opportunity Cards"]

    F --> G["Explainability — Grok"]
    F --> H["Risk Assessment — Grok"]
    F --> I["Committee Review — Grok"]
    F --> J["Strategy Generator — Grok"]

    G --> F
    H --> F
    I --> K["Execution Context Builder"]
    J --> K

    K --> L[SoDEX Terminal]
    L --> M[Order Builder — EIP-712]
    M --> N[Order Audit Trail]

    F --> O[Signal Archive]
    F --> P[Watchlist Cross-Reference]

    O --> Q["Live Entry Price Captured"]
    Q --> R["Track Record — Graded ≥1h vs Live Price"]
    R --> S["Hit Rate + Avg Return by Confidence Bucket"]
Loading

AI Agent Layer

CryptoDesk uses Grok (via api.x.ai) as its AI backbone. All AI calls are routed through netlify/functions/grok.js, a serverless proxy that attaches the server-side GROK_API_KEY — the browser never holds or sends the key.

flowchart TD
    A[Grok AI Layer] --> B[Auto Classifier]
    A --> C[Opportunity Explainer]
    A --> D[Risk Assessor]
    A --> E[Investment Committee]
    A --> F[Research Copilot]
    A --> G[Narrative Scanner]
    A --> H[Portfolio Agent]
    A --> I[SSI Index Builder]
    A --> J[Strategy Generator]
    A --> K[Daily Briefing]

    B --> L["Top 5 signals on every feed load"]
    C --> M["Why? + Risks bullets on every card"]
    D --> N["Risk drivers + conviction + mitigation"]
    E --> O["4-agent verdict + allocation + slippage"]
    F --> P["Free-form research Q&A"]
    G --> Q["Current vs emerging narrative rotation"]
    H --> R["Capital allocation from live feed"]
    I --> S["Custom index aligned to SSI Protocol"]
    J --> T["Trade playbook with exit criteria"]
    K --> U["Structured market report"]
Loading

AI Agent Details

Agent Trigger Input Output
Auto Classifier Every feed load Top 5 news articles Sentiment, confidence, assets, recommendation
Opportunity Explainer Background after classify All opportunities + news Why? and Risks bullets on each card
Risk Assessor User clicks "Risk Assess" Article + recommendation Risk level, drivers, conviction, mitigation
Investment Committee User clicks "Committee" Article + opportunity 4-agent vote, allocation %, slippage
Research Copilot User types query News feed + question Structured research answer
Narrative Scanner User opens Narratives News + sector data + indices Current/emerging narratives + rotation insight
Portfolio Agent User configures portfolio News + capital/risk/goal Allocations with reasoning
SSI Index Builder User selects theme News + SSI reference data Themed index with weights + methodology
Strategy Generator User clicks "Strategy" Article + opportunity Named playbook with exit criteria
Daily Briefing User clicks "AI Briefing" Full news feed Executive summary, signals, risk watch

Track Record is intentionally not in this table — see Quantitative Validation (Track Record). It grades the agents above against live prices; it doesn't call any of them.

SoSoValue Integration

SoSoValue is the primary market data layer. All data is fetched via the SoSoValue OpenAPI v1, proxied server-side through netlify/functions/soso.js.

Endpoints Used

flowchart TD
    A["SoSoValue OpenAPI v1"] --> B["GET /news"]
    A --> C["GET /news/hot"]
    A --> D["GET /news/featured"]
    A --> E["GET /currencies"]
    A --> F["GET /currencies/{id}/market-snapshot"]
    A --> G["GET /currencies/{id}/klines"]
    A --> H["GET /currencies/sector-spotlight"]
    A --> I["GET /etfs/summary-history"]
    A --> J["GET /etfs"]
    A --> K["GET /indices"]
    A --> L["GET /indices/{ticker}/constituents"]
    A --> M["GET /indices/{ticker}/market-snapshot"]
    A --> N["GET /btc-treasuries"]
    A --> O["GET /fundraising/projects"]
    A --> P["GET /macro/events"]
    A --> Q["GET /analyses"]

    B --> R["News Feed"]
    E --> S["Masthead Tickers"]
    F --> Z["Track Record Live Price Grading"]
    H --> T["Sector Spotlight + Narratives"]
    I --> U["ETF Flow Monitor"]
    K --> V["SSI Index Builder"]
    N --> W["BTC Treasuries Panel"]
    O --> X["Fundraising Panel"]
    P --> Y["Macro Events Panel"]
Loading

SoSoValue Hub

The SoSoValue Hub tab fires 8 parallel GETs on open:

Endpoint Panel
/currencies/sector-spotlight Sectors
/etfs/summary-history ETF Flows
/indices SSI Indices
/btc-treasuries BTC Treasuries
/fundraising/projects Fundraising
/macro/events Macro Calendar
/etfs ETF List
/analyses On-Chain Analytics

SoDEX Integration

SoDEX is the market microstructure and execution preview layer. Public market data does not require authentication.

Endpoints Used

flowchart TD
    A["SoDEX Spot REST API v1"] --> B["markets/symbols"]
    A --> C["markets/tickers"]
    A --> D["markets/bookTickers"]
    A --> E["markets/{symbol}/orderbook"]
    A --> F["markets/{symbol}/klines"]
    A --> G["markets/{symbol}/trades"]
    A --> H["markets/coins"]
    A --> I["markets/miniTickers"]

    C --> J["Live Price Ticker — 15s refresh"]
    E --> K["Orderbook Depth Visualization"]
    F --> L["Kline Charts — 1H / 4H / 1D"]
    G --> M["Recent Trades Feed"]
    D --> N["Best Bid/Ask Spread"]
Loading

Execution Flow

flowchart TD
    A["Opportunity Card"] --> B["Open on SoDEX"]
    B --> C["Build Execution Context"]
    C --> D["Execution Preview Card"]
    D --> E["Allocation + Slippage + Route"]
    E --> F{"User Wants to Execute?"}
    F -- "No" --> G["Save to Signal Archive"]
    F -- "Yes" --> H["EIP-712 Order Builder"]
    H --> I["JSON Body Preview"]
    H --> J["Typed Data Preview"]
    H --> K["cURL Command Preview"]
    I --> L["Order Audit Trail"]
Loading

SoDEX Usage Levels

flowchart TD
    A["SoDEX Integration"] --> B["Level 1: Shipped"]
    A --> C["Level 2: Scaffold"]
    A --> D["Level 3: Future"]

    B --> E["Public Market Data"]
    B --> F["Ticker + Orderbook + Klines + Trades"]
    B --> G["Execution Preview Card"]
    B --> H["Dual Kline Charts"]

    C --> I["EIP-712 Order Builder"]
    C --> J["JSON + Typed Data + cURL"]
    C --> K["Order Audit Trail"]

    D --> L["Live Signed POST"]
    D --> M["SoDEX SDK Integration"]
    D --> N["Portfolio Execution"]
Loading

Signal Classification Engine

CryptoDesk uses a hybrid classification approach:

  1. Lexicon scoring — local keyword-based sentiment analysis runs on every article immediately
  2. Grok classification — AI-powered deep classification runs on the top 5 articles
flowchart LR
    A["News Article"] --> B["Lexicon Scorer — Local"]
    A --> C["Grok Classifier — AI"]

    B --> D[Base Sentiment + Strength]
    C --> E[Full Classification Object]

    D --> F[Merged Signal]
    E --> F

    F --> G[Signal List]
    F --> H[Opportunity Builder]
    F --> I[Watchlist Cross-Reference]
    F --> J[Signal Archive]
Loading

Quantitative Validation (Track Record)

Every other intelligence panel in CryptoDesk asks Grok a question and shows the answer. Track Record is deliberately the opposite: it makes no AI call at all — it grades the AI's past Buy/Sell/Hold calls against real, live SoSoValue prices, so the terminal's own accuracy is measurable instead of self-reported.

flowchart TD
    A["Signal enters Signal Archive"] --> B["Live entry price captured immediately"]
    B --> C{"Age ≥ 1 hour?"}
    C -- "No" --> D["Status: Pending"]
    C -- "Yes" --> E["Fetch current price — SoSoValue market-snapshot"]
    E --> F{"Price resolved?"}
    F -- "No" --> G["Status: No data"]
    F -- "Yes" --> H["Compute forward return %"]
    H --> I{"Recommendation vs. move"}
    I -- "Buy & return > +1%" --> J["Hit"]
    I -- "Sell & return < -1%" --> J
    I -- "Hold & |return| ≤ 1%" --> J
    I -- "Otherwise" --> K["Miss"]
    J --> L["Hit rate + avg return, by confidence bucket"]
    K --> L
Loading

Rules this panel follows, stricter than the rest of the app:

  • No backfilled or reconstructed history — an entry only gets graded once it has a price captured live at archive time.
  • No grading before maturity — signals younger than 1 hour show as "Pending," never scored early.
  • No fabricated prices — if SoSoValue can't resolve a current price for an asset, that entry stays "No data" rather than being guessed.
  • Small-sample honesty — the panel calls out when the graded sample is under 20 entries so a good-looking hit rate isn't mistaken for statistical significance.

Panels

CryptoDesk has a three-column terminal layout.

flowchart TD
    A["CryptoDesk Terminal"] --> B["Left — Navigation"]
    A --> C["Center — Main Workspace"]
    A --> D["Right — Intelligence Panel"]

    B --> E["Category Filters"]
    B --> F["SoSoValue Data Sections"]
    B --> G["Panel Shortcuts"]
    B --> H["Judge Demo Button"]

    C --> I["News Feed Tab"]
    C --> J["SoSoValue Hub Tab"]
    C --> K["SoDEX Terminal Tab"]

    D --> L["Signals Panel"]
    D --> M["Opportunities Panel"]
    D --> N["Article Analysis Panel"]
    D --> O["Briefing Panel"]
    D --> P["Research Copilot Panel"]
    D --> Q["Narratives Panel"]
    D --> R["Portfolio Panel"]
    D --> S["SSI Index Panel"]
    D --> T["Strategy Panel"]
    D --> U["Watchlist Panel"]
    D --> V["Signal Archive Panel"]
    D --> W["Order Audit Panel"]
    D --> X["Track Record Panel"]
Loading

Navigation Panels

Panel Shortcut Purpose
News Feed Default Browse SoSoValue articles
SoSoValue Hub [HUB] 8 parallel data dashboards
SoDEX Terminal [SDX] Live market data + order builder
Signals [SIG] AI-classified signal list
Opportunities [OPP] Ranked opportunity cards
AI Briefing [BRF] Grok-generated market briefing
Research Copilot [CP] Free-form research Q&A
Narratives [NAR] Narrative rotation scanner
Portfolio [PF] Portfolio intelligence agent
SSI Index [SSI] Custom index builder
Strategy [STR] Trade playbook generator
Watchlist [WCH] Token watchlist with alerts
Signal Archive [ARC] Session signal history
Track Record [TRK] Live price grading of archived signals — no AI involved
Order Audit [AUD] Prepared order trail
Judge Demo [DEM] Guided 8-step demo wizard

Storage

CryptoDesk stores only real user-generated data. All client-side storage uses sessionStorage — nothing persists to disk, and everything clears when the browser tab closes.

Key Data
cd_soso Optional SoSoValue API key override (BYOK)
cd_grok Optional Grok API key override (BYOK)
cd_sodex SoDEX API key
cd_topic Focus topic preference
cd_dark Dark mode preference
cd_watchlist User-added watchlist tokens
cd_signal_archive Signal/opportunity history, each entry stamped with entryPrice + entryPriceAt once a live price baseline is captured — the input to Track Record grading
cd_order_audit Prepared SoDEX order audit trail

SoSoValue and Grok requests work with no key entered at all — they're served by the app's server-side keys (GROK_API_KEY / SOSO_API_KEY, see Environment Variables). The cd_soso/cd_grok fields in Settings are only needed if a user wants to swap in their own key for a request.

Rules

  • No fake reports
  • No seeded watchlist data
  • No mock dashboard metrics
  • No hardcoded market data
  • All data comes from live API responses or real user actions

Button Behavior

Every visible button must work.

flowchart TD
    A["Button Click"] --> B{"Does Feature Exist?"}
    B -- "Yes" --> C["Run Real Action"]
    B -- "No" --> D["Disable Button or Remove It"]
    C --> E{"Success?"}
    E -- "Yes" --> F["Show Toast Notification"]
    E -- "No" --> G["Show Error Toast"]
Loading

Key Buttons

Button Behavior
Settings Optionally save a BYOK key override
AI Briefing Generate Grok market briefing
Risk Assess Run AI risk assessment on opportunity
Committee Run 4-agent investment committee
Strategy Generate trade strategy playbook
Execute on SoDEX Open SoDEX terminal with execution context
Add to Watchlist Save token to watchlist
Research Copilot Ask free-form question
Narrative Scan Run narrative rotation detection
Build Portfolio Generate AI portfolio allocation
Build SSI Index Design custom thematic index
Prepare Order Build EIP-712 signed order preview
Export JSON Download signal archive or order audit
Judge Demo Start guided 8-step demo wizard

Environment Variables

CryptoDesk's frontend is a client-side SPA, but SoSoValue and Grok calls now route through a serverless proxy (netlify/functions/) so their API keys live in the server environment, never in the browser.

Server-side (required for live data — set these, not a browser key)

Variable Source Purpose
GROK_API_KEY xAI API AI classification, agents, research — used by netlify/functions/grok.js
SOSO_API_KEY SoSoValue OpenAPI Market data, news, indices, ETFs — used by netlify/functions/soso.js

Copy .env.example to .env for local development with netlify dev, and set the same two variables under Site settings → Environment variables on Netlify for the deployed site. Without them, the proxy functions return a clear "not configured" error rather than failing silently.

Optional client-side overrides (BYOK)

A user can still paste their own SoSoValue/Grok key into the Settings modal — it's forwarded per-request to the proxy and takes precedence over the server key for that call. Not required for normal use.

Key Source Purpose
SoDEX API Key SoDEX Authenticated execution actions (future) — used directly client-side, since public SoDEX market data needs no auth

Environment URLs

Testnet Spot:  https://testnet-gw.sodex.dev/api/v1/spot
Testnet Perps: https://testnet-gw.sodex.dev/api/v1/perps

Mainnet Spot:  https://mainnet-gw.sodex.dev/api/v1/spot
Mainnet Perps: https://mainnet-gw.sodex.dev/api/v1/perps

Installation

git clone https://github.com/Nanle-code/CryptoDesk.git
cd CryptoDesk
npm install

Running Locally

npm run dev

Serves the frontend only, at http://localhost:5173. Calls to /.netlify/functions/* will 404 in this mode — fine for UI work, but Grok/SoSoValue data needs the full stack below.

For the full stack (frontend + serverless proxy functions), copy .env.example to .env, fill in GROK_API_KEY/SOSO_API_KEY, then run:

npm run dev:full

Open:

http://localhost:8888

Build

npm run build

Build output is written to dist/.

Preview Production Build

npm run preview

Project Structure

cryptodesk/
├── index.html
├── vite.config.js
├── package.json
├── netlify.toml
├── manifest.json
├── .env.example
│
├── netlify/
│   └── functions/
│       ├── grok.js               # Server-side Grok proxy — holds GROK_API_KEY
│       └── soso.js               # Server-side SoSoValue proxy — holds SOSO_API_KEY
│
├── src/
│   ├── main.jsx
│   ├── App.jsx
│   │
│   ├── api/
│   │   ├── sosovalue.js          # SoSoValue OpenAPI v1 client
│   │   ├── sodex.js              # SoDEX Spot REST API v1 client
│   │   ├── grok.js               # Grok AI agent layer (grok-4.3 default)
│   │   └── claude.js             # Claude API client (optional)
│   │
│   ├── components/
│   │   ├── Masthead.jsx          # Top bar — logo, tickers, AI briefing
│   │   ├── TrustBar.jsx          # Stats bar — articles, signals, sentiment
│   │   ├── Nav.jsx               # Left navigation — categories, panels
│   │   ├── MainWorkspace.jsx     # Center — news feed, SoSo hub, SoDEX
│   │   ├── IntelligencePanel.jsx # Right — all intelligence panels
│   │   ├── NewsFeed.jsx          # News article list
│   │   ├── SignalList.jsx        # AI-classified signal cards
│   │   ├── OpportunityList.jsx   # Ranked opportunity cards
│   │   ├── SoDEXTerminal.jsx     # SoDEX market data terminal
│   │   ├── SoSoDashboard.jsx     # SoSoValue Hub — 8 data panels
│   │   ├── KlineChartPanel.jsx   # Kline chart container
│   │   ├── MiniKlineChart.jsx    # Compact kline chart renderer
│   │   ├── OrderExecutionScaffold.jsx # EIP-712 order builder
│   │   ├── ExecutionPreviewCard.jsx   # Bound execution preview
│   │   ├── WatchlistPanel.jsx    # Token watchlist with alerts
│   │   ├── NarrativePanel.jsx    # Narrative rotation display
│   │   ├── PortfolioPanel.jsx    # Portfolio allocation display
│   │   ├── SSIIndexPanel.jsx     # SSI index builder + live data
│   │   ├── StrategyPanel.jsx     # Strategy playbook display
│   │   ├── ResearchCopilot.jsx   # Free-form research Q&A
│   │   ├── SignalArchivePanel.jsx # Signal history + export
│   │   ├── TrackRecordPanel.jsx  # Live price grading of archived signals
│   │   ├── OrderAuditPanel.jsx   # Order audit trail + export
│   │   ├── SettingsModal.jsx     # API key configuration
│   │   ├── DemoWizard.jsx        # Judge demo — 8-step wizard
│   │   ├── Background.jsx        # Animated background
│   │   ├── Toast.jsx             # Toast notification
│   │   └── VirtualList.js        # Virtualized list renderer
│   │
│   ├── context/
│   │   └── ConfigContext.jsx     # Global config, API keys, toast
│   │
│   ├── hooks/
│   │   ├── useNews.js            # News fetching + signal classification
│   │   └── useTickers.js         # Masthead ticker data
│   │
│   ├── lib/
│   │   ├── signals.js            # Opportunity builder + merge logic
│   │   ├── aiSignals.js          # Grok signal classification
│   │   ├── explainability.js     # Opportunity explainability engine
│   │   ├── executionPreview.js   # Execution context builder
│   │   ├── watchlist.js          # Watchlist logic + alerts + intel
│   │   ├── ssiIndex.js           # SSI reference fetcher + merge
│   │   ├── signalArchive.js      # Signal archive persistence + entry-price capture
│   │   ├── backtest.js           # Track Record grading — live price vs entry price
│   │   ├── sodexExecution.js     # SoDEX order builder + audit
│   │   ├── sodexSymbol.js        # Asset → SoDEX symbol mapper
│   │   ├── klineChart.js         # Kline chart rendering logic
│   │   ├── klineData.js          # Kline data normalization
│   │   ├── currencyLookup.js     # Currency ID resolution
│   │   ├── demoWizard.js         # Demo step definitions
│   │   ├── mockNews.js           # Demo mode fallback data
│   │   ├── parseGrokJson.js      # Safe JSON parser for Grok
│   │   ├── format.js             # Number formatting utilities
│   │   └── api.js                # SoSoValue fetch wrapper
│   │
│   ├── utils/
│   │   ├── format.js             # Display formatting helpers
│   │   └── intelligence.js       # Intelligence computation
│   │
│   ├── core/
│   │   ├── app.js                # Core application logic
│   │   ├── state.js              # State management
│   │   └── motion.js             # Animation engine
│   │
│   └── styles/
│       ├── design-system.css     # Design tokens + CSS variables
│       ├── app.css               # Application layout styles
│       ├── components.css        # Component-level styles
│       └── animations.css        # Micro-animation definitions
│
├── public/
│   └── manifest.json
│
├── docs/
│   ├── ROADMAP.md
│   ├── WAVE2_SUBMISSION.md
│   └── WAVE3_SUBMISSION.md
│
├── dist/                         # Production build output
└── legacy/                       # Previous version files

Component Architecture

flowchart TD
    A[App] --> B[ConfigProvider]
    B --> C[Terminal]

    C --> D[Background]
    C --> E[Masthead]
    C --> F[TrustBar]
    C --> G[Nav]
    C --> H[MainWorkspace]
    C --> I[IntelligencePanel]
    C --> J[SettingsModal]
    C --> K[DemoWizard]
    C --> L[Toast]

    H --> M[NewsFeed]
    H --> N[SoSoDashboard]
    H --> O[SoDEXTerminal]

    O --> P[KlineChartPanel]
    O --> Q[OrderExecutionScaffold]
    O --> R[ExecutionPreviewCard]

    I --> S[SignalList]
    I --> T[OpportunityList]
    I --> U[ResearchCopilot]
    I --> V[NarrativePanel]
    I --> W[PortfolioPanel]
    I --> X[SSIIndexPanel]
    I --> Y[StrategyPanel]
    I --> Z[WatchlistPanel]
    I --> AA[SignalArchivePanel]
    I --> AB[OrderAuditPanel]
    I --> AC[TrackRecordPanel]
Loading

Safety Rules

CryptoDesk follows these rules:

  1. No mock market data in production mode.
  2. No fake dashboard metrics.
  3. No seeded signals or opportunities.
  4. No silent API fallback — errors are always surfaced.
  5. No wallet required before analysis.
  6. No mainnet execution by default — SoDEX testnet only.
  7. No auto-execution — all orders require manual preparation.
  8. SoSoValue and Grok API keys live server-side (Netlify Functions env vars) and are never sent to the browser; any optional BYOK override a user enters stays in sessionStorage only, never persisted to disk.
  9. All AI outputs labeled as AI-generated.
  10. All user inputs validated before API calls.
  11. All errors shown via toast notifications.

Error Handling

flowchart TD
    A["UI calls Netlify Function proxy"] --> B{"Success?"}
    B -- "Yes" --> C["Process + Display Data"]
    B -- "No" --> D{"Error Type"}

    D --> E["Server key not configured"]
    D --> F["API Timeout"]
    D --> G["Rate Limited"]
    D --> H["Invalid Response"]
    D --> I["Network Error"]

    E --> J["Toast: proxy error surfaced verbatim"]
    F --> K["Toast: Try again later"]
    G --> L["Toast: Rate limited"]
    H --> M["Toast: Parse error"]
    I --> N["Toast: Network error"]
    D --> Q{"Was this the news feed?"}
    Q -- "Yes" --> R["Fall back to demo news — error toast still shown, never silent"]
Loading

Empty States

State Behavior
Server keys not yet configured Proxy returns a clear "not configured" error; UI surfaces it via toast and falls back to demo news
No signals yet Loading indicator during Grok classification
No watchlist Empty state with "Add tokens" prompt
No archive Empty state with explanation
No signals archived (Track Record) "No signals archived yet this session"
Archive not yet price-baselined (Track Record) "Capturing entry-price baselines…" — no hit rate shown until a live price is stamped
Signals younger than 1h (Track Record) Listed as "Pending" / "Maturing," excluded from hit-rate math
API failure Error toast with specific message

Tech Stack

Layer Technology
Framework React 19
Build Tool Vite 6
AI Model Grok (xAI, grok-4.3 default)
Market Data SoSoValue OpenAPI v1
Exchange Data SoDEX Spot REST API v1
Styling Vanilla CSS + CSS Variables
Typography Inter + JetBrains Mono (Google Fonts)
Backend Netlify Functions (serverless API key proxy)
Hosting Netlify
Storage sessionStorage (client)
State Management React hooks + Context API

Business Model

flowchart TD
    A["CryptoDesk Business Model"] --> B["Free Terminal"]
    A --> C["Pro Researcher"]
    A --> D["Fund Manager"]
    A --> E["Community Plan"]
    A --> F["API Access"]

    B --> G["Basic news + lexicon signals"]
    C --> H["Full AI agent suite + SoDEX execution"]
    D --> I["Portfolio management + committee reviews"]
    E --> J["Signal group integrations"]
    F --> K["Programmatic intelligence API"]
Loading

Pricing Plan Ideas

Plan Target User Example Price
Free Beginners Free
Pro Researcher Active traders $29/month
Fund Manager Serious portfolio managers $99/month
Community Signal groups $399/month
API Bots, wallets, DeFi apps Usage-based

Roadmap

gantt
    title CryptoDesk Roadmap
    dateFormat  YYYY-MM-DD
    axisFormat %m-%d
    
    section Shipped
    News Feed :done, 2026-06-01, 1d
    AI Signals :done, 2026-06-02, 1d
    Opportunities :done, 2026-06-03, 1d
    Committee :done, 2026-06-03, 1d
    SoDEX Terminal :done, 2026-06-04, 1d
    Portfolio + SSI :done, 2026-06-05, 1d
    Demo Wizard :done, 2026-06-05, 1d
    Server-Side Key Proxy :done, 2026-07-19, 1d
    Track Record :done, 2026-07-19, 1d

    section Next
    Live Execution :2026-07-20, 7d
    Push Alerts :2026-07-20, 7d
    PDF Reports :2026-07-20, 7d
    Multi-Model :2026-07-20, 7d
Loading

Judge Demo

CryptoDesk includes a built-in 8-step judge demo wizard accessible from the left navigation bar.

flowchart TD
    A["Start Judge Demo"] --> B["Step 1: Live by Default — server keys, nothing to paste in"]
    B --> C["Step 2: News Feed"]
    C --> D["Step 3: AI Classification"]
    D --> E["Step 4: Opportunity Engine"]
    E --> F["Step 5: Investment Committee"]
    F --> G["Step 6: Portfolio Agent"]
    G --> H["Step 7: Execution Preview"]
    H --> I["Step 8: Explainability"]
Loading

Each step navigates the terminal to the relevant panel and triggers the appropriate action. Toasts confirm progress. Step 1 no longer asks a judge to paste in API keys — Settings only exposes an optional personal key override.

Links

Quality Checklist

  • All panels load correctly
  • Navigation links work
  • SoSoValue integration connected — news, tickers, sectors, ETFs, indices, treasuries, fundraising, macro
  • SoDEX integration connected — tickers, orderbook, klines, trades, bookTickers
  • Grok AI classification works on feed load
  • Opportunity explainability (Why? / Risks) renders automatically
  • Investment committee returns structured multi-agent verdict
  • Portfolio agent generates allocations from live feed
  • SSI index builder aligns with live SoSoValue indices
  • Narrative rotation scanner detects current vs emerging themes
  • Strategy generator creates playbooks from opportunities
  • Research copilot answers free-form questions
  • SoDEX terminal shows execution preview card
  • Dual kline charts load on SoDEX tab
  • EIP-712 order builder generates JSON + typed data + cURL
  • Watchlist alerts fire on high-severity signals
  • Signal archive persists across tab lifecycle
  • Order audit trail tracks prepared orders
  • Export JSON works for archive and audit
  • Judge demo wizard navigates all 8 steps
  • App is responsive on mobile
  • npm run build passes
  • No mock data in production mode
  • SoSoValue + Grok API keys live server-side (Netlify Functions) — never sent to or stored in the browser
  • App works with zero user-entered keys; Settings only offers an optional BYOK override
  • Track Record grades archived signals against live SoSoValue prices, not simulated data
  • Track Record entries maturing < 1h are labeled Pending, never scored early

Disclaimer

CryptoDesk is a market intelligence and research tool.

It does not provide financial advice.

AI-generated signals, opportunities, committee reviews, and portfolio allocations are designed to help users understand market conditions and potential trade ideas. Users remain fully responsible for their own trading decisions.

All SoDEX execution features operate in testnet/preview mode by default. No real trades are executed.

One-Line Summary

CryptoDesk is an AI-powered on-chain intelligence terminal that connects SoSoValue market data, Grok AI classification, multi-agent investment committee reviews, and SoDEX execution previews into a single data-to-decision workflow — a client-side terminal backed by a minimal serverless proxy that keeps API keys off the browser, with a Track Record panel that grades the AI's own calls against live prices instead of asking you to take its word for it.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages