Thông tin chung về REST API

  • URL cơ sở: https://api-adapter.backend.currency.com
  • URL cơ sở, tài khoản demo:  https://demo-api-adapter.backend.currency.com
  • Tất cả các endpoint trả về một đối tượng hoặc mảng JSON.
  • Dữ liệu được trả về theo thứ tự tăng dần. Dữ liệu cũ nhất ở đầu, mới nhất ở sau cùng.
  • Tất cả các phần liên quan đến thời gian và dấu thời gian đều tính bằng mili giây.
  • Tất cả các tài sản token hóa ngoại trừ chữ ký điện tử công ty, trái phiếu token hóa, token “KARMA.cx” “KARMA.cx” và tài sản token hóa từ thị trường Hồng Kông đều có sẵn trong phiên bản đầu tiên (v1) của API của chúng tôi. Trong phiên bản API thứ hai (v2), thị trường Hồng Kông cũng có sẵn.
  • Bạn có thể tìm thấy danh sách các tài sản có sẵn để giao dịch đòn bẩy trong API tại đây.
  • Khi thiết lập thị trường, giới hạn hoặc dừng lệnh và đề cập đến một lượng lớn hơn yêu cầu về các số chính xác đối với một token cụ thể, logic làm tròn xuống là đúng. Bạn có thể tìm thấy độ chính xác cho phép trong phản hồi yêu cầu exchangeInfo (Thông tin giao dịch), quotePrecision (Tham số giá tham khảo).
  • Khi đề cập đến một lượng lớn các số chính xác cho tham số giá, logic làm tròn lên được sử dụng. Bạn có thể tìm thấy độ chính xác cho phép trong phản hồi yêu cầu exchangeInfo (Thông tin giao dịch), quotePrecision (Tham số giá tham khảo).

Vui lòng tham khảo phần REST API trong Swagger để nhận thông tin cần thiết. 

Troubleshooting

Mã HTTP Return

  • Mã HTTP Return 4XX được sử dụng cho các yêu cầu không đúng định dạng; vấn đề nằm ở phía người gửi.
  • Mã HTTP Return 403 được sử dụng khi Giới hạn WAF (Tường lửa Ứng dụng Web) bị vi phạm.
  • Mã HTTP Return 429 được sử dụng khi phá vỡ giới hạn tỷ lệ yêu cầu.
  • Mã HTTP Return 418 được sử dụng khi một IP đã bị tự động cấm tiếp tục gửi yêu cầu sau khi nhận được mã 429.
  • Mã HTTP Return 5XX được sử dụng cho các lỗi nội bộ; vấn đề nằm ở phía Currency.com. Điều quan trọng là KHÔNG coi đây là sự vận hành thất bại; trạng thái thực thi này được coi là CHƯA ĐƯỢC BIẾT TỚI và có thể là thành công.

Mã Error

  • Bất kỳ endpoint nào cũng có thể trả về ERROR (LỖI).

Payload mẫu bên dưới:

Phản hồi:
{ "code": -1121, "msg": "Invalid symbol." }
  • Mã lỗi và thông báo cụ thể được xác định trong mã Error

Thông tin chung về endpoint

  • Đối với endpoint GET, các tham số phải được gửi dưới dạng một chuỗi truy vấn..
  • Đối với các endpoint POST, PUTDELETE, các tham số có thể được gửi dưới dạng chuỗi truy vấn hoặc trong phần thân yêu cầu với loại nội dung application/x-www-form-urlencoded. Bạn có thể kết hợp các tham số giữa cả chuỗi truy vấn và phần thân yêu cầu nếu muốn. Các tham số có thể được gửi theo bất kỳ thứ tự nào.
  • Các tham số có thể được gửi theo bất kỳ thứ tự nào.
  • Nếu một tham số được gửi trong cả chuỗi truy vấn và nội dung yêu cầu, thì tham số chuỗi truy vấn sẽ được sử dụng.

Loại bảo mật endpoint

  • Mỗi endpoint có một kiểu bảo mật xác định cách bạn sẽ tương tác với nó. Điều này được nêu bên cạnh TÊN của endpoint.
  • Nếu không có kiểu bảo mật nào được nêu, ngầm hiểu kiểu bảo mật là NONE (KHÔNG).
  • Khóa API được chuyển vào REST API thông qua tiêu đề X-MBX-APIKEY.
  • Khóa API và khóa bí mật có phân biệt chữ hoa chữ thường.
  • Khóa API có thể được định cấu hình để chỉ truy cập một số loại endpoint an toàn nhất định. Ví dụ: một khóa API chỉ có thể được sử dụng cho TRADE, trong khi một khóa API khác có thể truy cập mọi thứ ngoại trừ các tuyến TRADE.
  • Theo mặc định, khóa API có thể truy cập tất cả các tuyến an toàn.
Loại bảo mậtMô tả
NONEEndpoint có thể được truy cập tự do
TRADEEndpoint yêu cầu gửi một Khóa API và chữ ký hợp lệ
USER_DATAEndpoint yêu cầu gửi một API-Key và chữ ký hợp lệ
USER_STREAMEndpoint yêu cầu gửi một Khóa API hợp lệ
MARKET_DATAEndpoint yêu cầu gửi một Khóa API hợp lệ
  • Endpoint TRADEUSER_DATA là Endpoint SIGNED.

SIGNED (TRADE, USER_DATA, AND MARGIN) Bảo mật endpoint

  • Endpoint SIGNED yêu cầu một tham số bổ sung và chữ ký được gửi trong chuỗi truy vấn hoặc phần thân yêu cầu.
  • Các endpoint sử dụng chữ ký HMAC SHA256. Chữ ký HMAC SHA256 là một quá trình vận hành HMAC SHA256 có khóa. Sử dụng secretKey (khóa bí mật) của bạn làm khóa và totalParams làm giá trị cho hoạt động HMAC.
  • Chữ ký không phân biệt chữ hoa và chữ thường.
  • totalParams được định nghĩa là chuỗi truy vấn được nối với phần thân yêu cầu.

Bảo mật thời gian

  • Endpoint SIGNED cũng yêu cầu một tham số và dấu thời gian được gửi đi. Đây phải là dấu thời gian (timestamp) tính theo mili giây về thời điểm yêu cầu được tạo và gửi.
  • Một tham số bổ sung, recvWindow, có thể được gửi để chỉ định số mili giây sau dấu thời gian mà yêu cầu có hiệu lực. Nếu recvWindow § § không được gửi thì con số mặc định là 5000.

Logic như sau:

if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) { // process request } else { // reject request }

Giao dịch nghiêm túc chú trọng thời gian. Network có thể không ổn định và không đáng tin cậy, điều này có thể dẫn đến các yêu cầu mất nhiều thời gian khác nhau để đến được máy chủ. Với recvWindow, bạn có thể chỉ định rằng yêu cầu phải được xử lý trong một số mili giây nhất định hoặc bị máy chủ từ chối.

Bạn nên sử dụng recvWindow nhỏ từ 5000 trở xuống! Mức tối đa không thể vượt quá 60.000!

Ví dụ về endpoint SIGNED cho POST /api/v1/order

Dưới đây là ví dụ từng bước về cách gửi payload đã ký hợp lệ từ dòng lệnh Linux bằng cách sử dụng echo, openssl và curl.

Chìa khóaGiá trị
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Tham sốGiá trị
symbolLTC/BTC
sideBUY
typeLIMIT
timeInforceGTC
quantity1
price0,1
recvWindow5000
timestamp1499827319559

Xin lưu ý rằng một số ký hiệu như '/' phải được mã hóa url và chuyển đổi thành tổ hợp '%2F'.

Ví dụ 1: Dưới dạng phần thân yêu cầu

requestBody:

symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

HMAC SHA256 signature

[linux]$ echo -n
"symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order' -d
'symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50'

Ví dụ 2: Dưới dạng một chuỗi truy vấn

queryString:

symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559

HMAC SHA256 signature:

[linux]$ echo -n
"symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order?symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1499827319559&signature=ebec6528b2beb508b2417fa33453a4ad28c1aae8097bb243caa60d0524036f50'

Ví dụ endpoint SIGNED cho POST /api/v1/order
(chế độ giao dịch đòn bẩy)

Dưới đây là ví dụ từng bước về cách gửi payload đã ký hợp lệ từ dòng lệnh Linux bằng cách sử dụng echo, openssl và curl.

Chìa khóaGiá trị
apiKeyvmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A
secretKeyNhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j
Tham sốGiá trị
symbolBTC/USD_LEVERAGE
sideBUY
typeMARKET
timeInforceGTC
quantity0.01
quantity2
accountId2376109060084932
takeProfit8000
stopLoss6000
recvWindow60000
timestamp1586942164000

Xin lưu ý rằng một số ký hiệu như '/' phải được mã hóa url và chuyển đổi thành tổ hợp '%2F'.

Ví dụ 1: Dưới dạng phần thân yêu cầu

requestBody:

symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000

HMAC SHA256 signature

[linux]$ echo -n
"symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order' -d
'symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000&signature=05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b'

Ví dụ 2: Dưới dạng một chuỗi truy vấn

queryString:

symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000

HMAC SHA256 signature:

[linux]$ echo -n
"symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000" | openssl dgst -sha256 -hmac
"NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j"
(stdin)= 05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY:
vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A" -X POST 'https://api-adapter.backend.currency.com/api/v1/order?symbol=BTC%2FUSD_LEVERAGE&side=BUY&type=MARKET&timeInForce=GTC&quantity=0.01&leverage=2&accountId=2376109060084932&takeProfit=8000&stopLoss=6000&recvWindow=60000&timestamp=1586942164000&signature=05fc9fd19c2b1a11215025c5dfa56da2204b04181add67670d4f92049b439f7b

Thuật ngữ

  • tài sản cơ sở đề cập đến tài sản là số lượng của một symbol.
  • tài sản báo giá đề cập đến tài sản là giá của một symbol.

Định nghĩa ENUM

Trạng thái đơn đặt hàng (status):

  • NEW (MỚI)
  • FILLED (ĐÃ DIỀN)
  • CANCELED (HỦY)
  • REJECTED (TỪ CHỐI)

Các loại đơn đặt hàng (orderTypes, type):

  • LIMIT (GIỚI HẠN)
  • MARKET (THỊ TRƯỜNG)
  • STOP (DỪNG) 

Bên đặt hàng (side)

  • BUY (MUA)
  • SELL (BÁN)

Thời gian có hiệu lực (timeInForce):

  • GTC
  • IOC
  • FOK

Khoảng thời gian của biểu đồ Kline/Candlestick:
p -> phút; h -> giờ; ng -> ngày; t -> tuần

  • 1p
  • 5p
  • 15p
  • 30p
  • 1h
  • 4h
  • 1ng
  • 1t

tham số loại /klines:

  • heiken-ashi