photonichat-api-www

Quote proxy for the photonichat ESP32 clock — Sina Finance (stocks/FX/futures/indices) + CoinGecko (crypto).

Live sample

Updates every 10s via /clock. Upstream cache: 30s quotes, 60s metals, 30s crypto.

Endpoints

Symbol formats

All Sina hq.sinajs.cn codes work natively. Yahoo-style aliases (AAPL, 0700.HK, 600519.SS, USDCNY=X, GC=F, ^GSPC) are auto-translated.

Full A-share universe

The complete Shanghai + Shenzhen + Beijing A-share listing, loaded from Sina at startup and cached to disk for 7 days. Reload manually with /symbols/reload.

loading universe…

browse SH · browse SZ · browse BJ · browse all

Curated catalog

Hand-picked highlights across markets (including HK, US, indices, FX, futures, crypto). Or grab the whole curated list via /symbols JSON.

ESP32 usage

// Single quote, JSON:
//   GET /q/sh600519
//   -> {"symbol":"SH600519","name":"贵州茅台","price":1450.5,
//        "change":6.1,"change_pct":0.42,"currency":"CNY","exchange":"SH",
//        "ts":1715200000,"ts_utc":"2024-05-08T22:13:20Z","source":"sina",
//        "input_symbol":"SH600519"}

// Full clock bundle in one fetch:
//   GET /clock?stocks=sh600519,hk00700,gb_aapl&coins=bitcoin,ethereum

Agent implementation guide

If you are an AI agent (or an LLM-driven client) reading this page to integrate with this server, follow these rules. Everything here is read-only HTTP GET, no auth, CORS-open, JSON.

1 · Decide which endpoint to call

2 · Build a symbol the server understands

Before calling, normalize the user's input to one of the supported forms. The server is tolerant of Yahoo-style aliases, but if you can produce a native Sina code you'll skip a lookup.

Apple                 -> gb_aapl    (or AAPL)
Tencent (HK 0700)     -> hk00700    (or 0700.HK)
Kweichow Moutai       -> sh600519   (or 600519.SS)
Ping An Bank          -> sz000001   (or 000001.SZ)
S&P 500               -> int_sp500  (or ^GSPC)
Hang Seng             -> int_hangseng (or ^HSI)
USD/CNY               -> fx_susdcny (or USDCNY=X)
NYMEX gold future     -> hf_GC      (or GC=F)
Spot gold (XAUUSD)    -> hf_XAU     (or XAUUSD)
Spot silver (XAGUSD)  -> hf_XAG     (or XAGUSD)
Bitcoin (crypto)      -> bitcoin    (CoinGecko id, /crypto endpoint)

Rule of thumb: stocks/FX/futures/indices → /quote or /q; crypto → /crypto. Crypto ids are not tickers — use the lowercase CoinGecko slug (bitcoin, not BTC).

3 · Response schema

Every quote object — whether from /q/{sym}, /quote/{sym}, or as an item inside /q?syms=… — has the same shape. Every envelope response also carries a top-level ts + ts_utc.

{
  "symbol": "SH600519",        // server-normalized
  "input_symbol": "SH600519",  // exactly what you sent (uppercased)
  "name": "贵州茅台",
  "price": 1450.5,
  "change": 6.1,
  "change_pct": 0.42,          // already a percent, not a fraction
  "currency": "CNY",
  "exchange": "SH",
  "ts": 1715200000,            // unix seconds, upstream timestamp when available
  "ts_utc": "2024-05-08T22:13:20Z",  // ISO 8601 UTC, derived from ts
  "source": "sina"
}

404 means "no quote available for that symbol" — either the symbol is unknown or upstream returned an empty body. Treat as a normal "not found", not an error to retry.

4 · Worked examples

curl https://<host>/quote/gb_nvda
curl 'https://<host>/q?syms=sh600519,hk00700,gb_aapl,int_sp500'
curl 'https://<host>/clock?stocks=gb_aapl,gb_tsla&coins=bitcoin,ethereum'
curl 'https://<host>/symbols/search?q=茅台'

# Python
import httpx
r = httpx.get("https://<host>/q", params={"syms": "gb_aapl,hk00700,sh600519"})
for q in r.json()["quotes"]:
    print(q["symbol"], q["price"], q["change_pct"], "%")

// JavaScript
const d = await (await fetch('/q?syms=gb_aapl,hk00700,sh600519')).json();
d.quotes.forEach(q => console.log(q.symbol, q.price, q.change_pct + '%'));

5 · Rules an AI client should follow

• Batch. If you need more than one symbol, call /q?syms=… or /clock — never loop single requests.
• Don't poll faster than 30s. Server caches at 30s for quotes / 60s for metals / 30s for crypto; faster polling wastes round trips and returns identical data.
• Send the user's symbol as-is if you're unsure of the format. The server normalizes Yahoo-style and bare tickers automatically.
• Treat 404 as a clean "no quote", not as a failure. Suggest checking the /symbols catalog or /symbols/search.
• For Chinese stock discovery use /symbols/search?q=… — it accepts Chinese characters in the query string.
• No auth, no API key. CORS allows any origin. GET only.
• Discovery: GET /symbols returns the curated catalog and the universe endpoints in machine-readable JSON.

Caching

In-memory TTL cache. One upstream fetch per (symbol, TTL window) serves every polling device. See /cache for live stats.

Sources: Sina Finance (hq.sinajs.cn) · CoinGecko