Quy ước API
Các quy tắc áp dụng chung cho mọi endpoint: bố cục URL, lớp bọc phản hồi, ký hiệu, đơn vị, dấu thời gian, phân trang và cache.
URL gốc và phiên bản
Mọi endpoint nằm dưới một URL gốc và được gọi bằng HTTPS GET. Các đường dẫn hiện tại thuộc phiên bản v1. Trong v1, thay đổi chỉ mang tính bổ sung: có thể thêm trường và endpoint, còn các trường hiện có giữ nguyên tên, kiểu và ý nghĩa. Thay đổi phá vỡ tương thích sẽ được phát hành dưới một đường dẫn mới và được thông báo trước trong nhật ký thay đổi.
https://www.coinboss.com/apiLớp bọc phản hồi
Mọi phản hồi JSON đều có cờ success ở cấp cao nhất. Các endpoint của lớp dữ liệu tự thu thập (đường dẫn dưới /api/sd) có chung các khối bổ sung sau:
| Trường | Mô tả |
|---|---|
| success | true khi lệnh gọi thành công. Luôn kiểm tra trường này. |
| schema | Mã định danh và phiên bản chính của cấu trúc phản hồi. |
| now | Thời gian máy chủ lúc phản hồi được dựng, tính bằng mili giây. |
| coverage | Những sàn nào được tính, những sàn nào không khả dụng và vì sao, và những sàn nào bị loại do quá hạn. |
| method | Công thức hoặc quy tắc đứng sau từng số liệu tổng hợp trong phản hồi. |
| meta | Nguồn, dấu thời gian, khung thời gian, xếp loại chất lượng, cờ quá hạn, thời gian sống của cache và hành vi dự phòng. |
Các endpoint cũ hơn trả về success cùng một trường data và có thể không có coverage, method hay meta. Trang tham chiếu của chúng mô tả chính xác các trường.
Coin, hợp đồng và sàn
- Tham số coin nhận ký hiệu cơ sở viết hoa, ví dụ BTC hoặc PEPE.
- Các hợp đồng có hệ số nhân như 1000PEPE hay kPEPE được gộp vào coin cơ sở, số lượng được quy đổi tương ứng.
- Mã định danh sàn viết thường, ví dụ binance, okx, bybit, hyperliquid.
- Ký hiệu hợp đồng được trả về đúng như cách sàn đặt tên. Ở những endpoint trộn nhiều loại, hợp đồng ký quỹ USDT, USDC, ký quỹ bằng coin và hợp đồng giao sau có kỳ hạn được phân biệt bằng một trường loại hợp đồng.
- Hợp đồng vĩnh cửu của cổ phiếu token hóa và hàng hóa có ticker trùng với một tài sản crypto bị loại khỏi các số liệu tổng hợp crypto.
Đơn vị
- Trường kết thúc bằng _usd là giá trị danh nghĩa tính bằng đô la Mỹ.
- Tỷ lệ funding là số thập phân, không phải phần trăm: 0.0001 nghĩa là 0.01%. Trường kết thúc bằng _8h được chuẩn hóa về chu kỳ 8 giờ; chu kỳ gốc được trả về bên cạnh tỷ lệ thô.
- Trường kết thúc bằng _pct là phần trăm: 1.5 nghĩa là 1.5%.
- Vị thế mở là giá trị danh nghĩa một chiều tính bằng USD, trừ khi mô tả trường nêu khác. Những sàn công bố số liệu hai chiều được ghi chú trong khối method.
- Một số endpoint đời cũ trả về số thập phân dưới dạng chuỗi để giữ độ chính xác. Bảng trường ghi kiểu là string(decimal).
Dấu thời gian
- Dấu thời gian là Unix epoch tính bằng mili giây theo UTC, trừ khi mô tả trường nêu khác.
- observed_at là dấu thời gian của chính sàn cho bản ghi mới nhất được tính, hoặc null khi sàn không cung cấp.
- received_at là lúc trình thu thập của CoinBoss lưu bản ghi đó.
- fetched_at là lúc phản hồi được dựng. Với phản hồi lấy từ cache, giá trị này cũ hơn thời điểm bạn gọi tối đa bằng TTL cache.
- Chuỗi theo ngày dùng ranh giới ngày theo UTC.
Khung thời gian và chu kỳ
- Tham số khung thời gian dùng các token ngắn: 1h, 4h, 12h, 24h, và ở một số endpoint là 3d, 7d, 30d, 90d. Trang tham chiếu liệt kê các giá trị được chấp nhận cho từng endpoint.
- Giá trị khung thời gian không hợp lệ hoặc bị từ chối với INVALID_PARAM, hoặc được thay bằng giá trị mặc định trong tài liệu, tùy theo mô tả của từng tham số.
- Kích thước bucket của chuỗi thời gian phụ thuộc vào khung thời gian và được nêu trên trang tham chiếu.
Phân trang và sắp xếp
- Các endpoint dạng danh sách dùng limit và offset, hoặc page và size, như mô tả ở từng endpoint. Giới hạn có mức trần; giá trị lớn hơn sẽ bị hạ xuống mức trần.
- Khi phản hồi có total, đó là số dòng trước khi phân trang.
- Thứ tự sắp xếp là cố định, trừ khi endpoint có mô tả tham số sắp xếp.
Null, 0 và trường vắng mặt
- null nghĩa là giá trị chưa biết hoặc không khả dụng. 0 nghĩa là giá trị đo được bằng 0.
- Biểu đồ phải để khoảng trống cho null. Không nội suy.
- Trường được đánh dấu “có thể vắng mặt” trong bảng trường có thể hoàn toàn không xuất hiện trong object; hãy xử lý như null.
Cache
- Mỗi endpoint có một TTL cache máy chủ, ghi trên trang tham chiếu và trong meta.cache_ttl_s. Header X-Cache báo HIT, STALE hoặc MISS.
- Phía trước hầu hết các endpoint GET có một cache biên ngắn hạn khoảng mười giây.
- Polling nhanh hơn TTL chỉ nhận lại dữ liệu y hệt và làm tiêu hao hạn mức tần suất của bạn.
WebSocket
wss://www.coinboss.com/ws- Luồng chỉ đẩy JSON một chiều. Mỗi thông điệp có một trường type.
- Sau khi mất kết nối, hãy chờ một khoảng rồi kết nối lại và nạp bù từ endpoint HTTP tương ứng.
Tài liệu cho máy đọc
Danh mục, tham số và bảng trường của từng endpoint, trạng thái và ma trận chất lượng đều có dưới dạng JSON tại /api/meta, còn toàn bộ danh mục có dưới dạng một tài liệu OpenAPI 3.