Market Profile API

API HTTP chỉ đọc, đưa ra bối cảnh phiên đấu giá trực tiếp từ worker cho toàn bộ danh sách futures được quét: các mức chính (POC / value area / IB / naked POC / poor high & low) và alert cấu trúc thị trường. JSON qua HTTPS. Đây là bối cảnh để học hỏi, không phải lời khuyên đầu tư.

Base URL

https://<your-deployment>/api

Xác thực

Mọi request đều cần một API key trong header x-api-key chứ đừng bao giờ để trong query string. Query string sẽ làm key lọt vào log và referrer. Bạn tự tạo và thu hồi key trên trang Tài khoản.

curl -H "x-api-key: aift_xxxxxxxxxxxx" \
  "https://<your-deployment>/api/levels?symbol=ES"

Rate limit & các gói

Giới hạn tính riêng cho từng key, theo từng phút. Mọi response đều kèm X-RateLimit-Limit và X-Api-Tier. Vượt giới hạn sẽ nhận về 429.

Nguồn dữ liệu và độ mới

Mọi response của /api/levels đều nói rõ nó mô tả phiên nào, vì một chương trình không đọc được lời chú thích dạng văn xuôi. Hãy rẽ nhánh theo ba trường này trước đã.

Khi live là false, mọi trường suy ra từ phiên đang mở đều bằng null thay vì cũ một cách âm thầm: lastPrice, bias, overnight, playbook và updatedAt. prior, nakedPocs, poorHighs và poorLows mang phiên đã hoàn tất. developing là null trong response delayed, vì không có phiên nào đang chạy để mô tả: nó chỉ có giá trị khi đã nối broker. Hãy viết client theo dạng delayed trước, và nhớ kiểm tra null cho developing: một Elite key bắt đầu ở trạng thái delayed và giữ nguyên cho tới khi bạn nối broker trên trang Account.

Endpoints

{
  "symbol": "ES",
  "dataSource": "delayed",
  "live": false,
  "asOf": "2026-07-16",
  "updatedAt": null,
  "lastPrice": null,
  "bias": null,
  "developing": null,
  "prior":    { "poc": 5601, "vah": 5610, "val": 5590 },
  "overnight": null,
  "nakedPocs":[ { "price": 5588, "date": "2026-07-15" } ],
  "poorHighs":[], "poorLows":[],
  "playbook": null
}

{
  "symbol": "ES",
  "dataSource": "personal",
  "live": true,
  "asOf": null,
  "updatedAt": "2026-07-17T14:03:11.402Z",
  "lastPrice": 5623.25,
  "bias": "trend_up",
  "developing": { "poc": 5620, "vah": 5628, "val": 5612,
                  "vpoc": 5621, "ibHigh": 5626, "ibLow": 5610,
                  "high": 5631, "low": 5608 },
  "prior":    { "poc": 5601, "vah": 5610, "val": 5590 },
  "overnight":{ "high": 5629, "low": 5605 },
  "nakedPocs":[ { "price": 5588, "date": "2026-07-15" } ],
  "poorHighs":[], "poorLows":[],
  "playbook": { "bias": "trend_up", "levels": [ ... ], "scenarios": [ ... ] }
}

{
  "updatedAt": "2026-07-17T14:03:11.402Z",
  "count": 2,
  "alerts": [
    { "symbol": "ES", "type": "va-reject-high", "severity": "critical",
      "price": 5628, "ref": "prior-VAH", "message": "ES rejected prior VAH 5628" },
    { "symbol": "NQ", "type": "naked-poc", "severity": "warn",
      "price": 20110, "ref": "2026-07-15", "message": "NQ testing naked POC 20110" }
  ]
}

Các loại alert & severity

Webhooks

Thay vì poll liên tục /api/alerts, bạn có thể đăng ký webhook Discord / Telegram / endpoint tuỳ ý, hoặc bản tổng hợp qua email, trên trang Tài khoản. Mỗi đăng ký có thể lọc theo symbol và mức severity tối thiểu; worker sẽ đẩy alert khớp điều kiện ngay khi chúng kích hoạt.

Payload cho endpoint tuỳ ý

Endpoint tuỳ ý nhận một HTTPS POST với body JSON: version, một trường text tóm tắt cho người đọc, và mảng alerts có cấu trúc để automation xử lý (type, severity, price, params). Endpoint phải là HTTPS công khai (dải địa chỉ private và loopback bị từ chối). Hãy dùng nút Send test trên trang Account để bắn đúng payload này vào endpoint của bạn trước khi phụ thuộc vào nó.

{
  "version": 2,
  "text": "• TEST alert from AI Futures Trader. This webhook is wired up correctly: real market-structure alerts will arrive here looking exactly like this card. Nothing to trade.",
  "alerts": [
    {
      "kind": "structure",
      "key": "ES:webhook-test:1767627000000",
      "symbol": "ES",
      "type": "webhook-test",
      "severity": "info",
      "session": "rth",
      "price": 1234.25,
      "ref": "delivery check, not a signal",
      "message": "TEST alert from AI Futures Trader. This webhook is wired up correctly: real market-structure alerts will arrive here looking exactly like this card. Nothing to trade.",
      "params": null,
      "url": "https://trade.aifutures.dev/alerts"
    }
  ]
}

Lỗi

401 thiếu key hoặc key không hợp lệ · 404 symbol không tồn tại · 409 chưa có phiên hoàn tất nào được cấp quyền cho key này (code no_licensed_source; body kèm object fix trỏ tới /account và /broker-guide) · 429 vượt rate limit · 502 store phía trên không phản hồi.

Hãy rẽ nhánh theo code, đừng theo chuỗi message: câu chữ từ chối được viết theo ngôn ngữ người đọc và sẽ đổi theo, còn code thì không.