Dành cho nhà phát triển

API & SDK realtime MarketWatch

REST snapshot

1 lần gọi, lấy toàn bộ giá hiện tại theo scope.

SSE realtime

Stream push tự động mỗi 5–60 giây, không cần polling.

SDK TypeScript

@marketwatch/sdk — ESM/CJS/IIFE, hỗ trợ Vite & Webpack.

1. Xin API key

Mỗi key được cấp với danh sách scope (gold, crypto, fuel, stocks) và không giới hạn thời gian. Liên hệ để nhận key dùng thử miễn phí cho dự án của bạn.

Yêu cầu API key →contact@marketwatch.vn

2. Endpoints

REST — Snapshot

Lấy dữ liệu hiện tại một lần. Lọc nhóm bằng ?scopes=gold,crypto.

curl -H "x-api-key: YOUR_KEY" \
  "https://marketwatch.vn/api/public/v1/snapshot?scopes=gold,crypto,fuel,stocks"

Realtime stream (SSE)

MarketWatch dùng Server-Sent Events (HTTP/1.1 streaming) thay cho WebSocket — nhẹ hơn, đi qua mọi proxy/CDN và dùng được trực tiếp với EventSource trên trình duyệt mà không cần thư viện. Server tự reconnect, tự đóng sau ~30 phút để client mở lại.

Endpoint

GET https://marketwatch.vn/api/public/v1/stream

Content-Type

text/event-stream; charset=utf-8

Query parameters (request)

Tham số	Bắt buộc	Mặc định	Mô tả
api_key	có	—	Khoá API. EventSource không cho custom header → truyền qua query. Server đồng thời chấp nhận header `x-api-key` hoặc `Authorization: Bearer`.
scopes	không	tất cả	CSV của `gold,crypto,fuel,stocks`. Bị giới hạn theo quyền của key.
interval	không	10	Chu kỳ push (giây), khoảng `5–60`.

Event map (server → client)

Event	Khi nào	Payload
hello	Ngay khi kết nối	`{ ok, interval, scopes, key: { id, name } }`
snapshot	Mỗi `interval` giây	`{ generatedAt, scopes, data: { gold?, crypto?, fuel?, stocks? } }`
error	Lỗi upstream khi lấy 1 scope	`{ message: string }`
close	Trước khi server đóng (sau ~30 phút)	`{ reason: "max_duration" }`

Format raw trên dây (SSE wire)

event: hello
data: {"ok":true,"interval":10,"scopes":["gold","crypto"],"key":{"id":"…","name":"site abc.vn"}}

event: snapshot
data: {"generatedAt":1733400000000,"scopes":["gold","crypto"],"data":{"gold":{…},"crypto":[…]}}

event: close
data: {"reason":"max_duration"}

Ví dụ kết nối từ trình duyệt

const url = new URL("https://marketwatch.vn/api/public/v1/stream");
url.searchParams.set("api_key", "YOUR_KEY");
url.searchParams.set("scopes", "gold,crypto");
url.searchParams.set("interval", "10");

const ev = new EventSource(url.toString());

ev.addEventListener("hello", (e) => {
  console.log("connected", JSON.parse(e.data));
});

ev.addEventListener("snapshot", (e) => {
  const { generatedAt, data } = JSON.parse(e.data);
  console.log(new Date(generatedAt), data.gold, data.crypto);
});

ev.addEventListener("error", (e) => {
  // Lỗi nghiệp vụ từ server (1 scope upstream fail)
  try { console.warn("scope error:", JSON.parse((e as MessageEvent).data)); } catch {}
});

ev.addEventListener("close", (e) => {
  console.log("server closing:", JSON.parse(e.data));
  ev.close(); // trình duyệt sẽ KHÔNG tự reconnect khi bạn close() chủ động
});

// Khi rời trang
window.addEventListener("beforeunload", () => ev.close());

Lưu ý: kết nối auto-close sau ~30 phút (event close với reason: "max_duration") —EventSource mặc định sẽ tự reconnect sau vài giây nếu bạn không gọi ev.close(). Với Node.js dùng package eventsource hoặc gói @marketwatch/sdk bên dưới.

3. SDK chính thức

@marketwatch/sdk đóng gói sẵn auth, parsing và stream — hỗ trợ Node, Vite, Webpack và bản IIFE chạy thẳng trên browser.

npm install @marketwatch/sdk

import { createClient } from "@marketwatch/sdk";

const mw = createClient({ apiKey: "YOUR_KEY" });

// Một lần
const snap = await mw.snapshot({ scopes: ["gold", "crypto"] });

// Realtime
const stop = mw.stream({ scopes: ["gold"], interval: 10 }, (e) => {
  console.log(e.data.gold);
});

<!-- Hoặc dùng trực tiếp trên trình duyệt (IIFE bundle) -->
<script src="https://unpkg.com/@marketwatch/sdk"></script>
<script>
  const mw = MarketWatch.createClient({ apiKey: "YOUR_KEY" });
  mw.stream({ scopes: ["gold"] }, (e) => console.log(e.data));
</script>

Xem trên npm Thử endpoint

Phạm vi dữ liệu (scopes)

gold — SJC, PNJ, DOJI, XAU/USD
crypto — BTC, ETH & top 100 theo vốn hoá
fuel — Xăng RON95, E5, dầu DO/KO Việt Nam
stocks — VN-Index, HOSE, HNX, UPCOM