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

API & SDK realtime MarketWatch

Đưa dữ liệu giá vàng (SJC, PNJ, XAU/USD…), tiền điện tử, xăng dầu Việt Nam và chứng khoán VN vào website của bạn chỉ với vài dòng code — qua REST, Server-Sent Events realtime hoặc SDK TypeScript chính thức.

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ộcMặc địnhMô tả
api_keycó—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.
scopeskhôngtất cảCSV của gold,crypto,fuel,stocks. Bị giới hạn theo quyền của key.
intervalkhông10Chu kỳ push (giây), khoảng 5–60.
Event map (server → client)
EventKhi nàoPayload
helloNgay khi kết nối{ ok, interval, scopes, key: { id, name } }
snapshotMỗi interval giây{ generatedAt, scopes, data: { gold?, crypto?, fuel?, stocks? } }
errorLỗi upstream khi lấy 1 scope{ message: string }
closeTrướ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)