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:
{
"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ộtchuỗi truy vấn.
. - Đối với các endpoint
POST
,PUT
vàDELETE
, 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ật | Mô tả |
---|---|
NONE | Endpoint có thể được truy cập tự do |
TRADE | Endpoint yêu cầu gửi một Khóa API và chữ ký hợp lệ |
USER_DATA | Endpoint yêu cầu gửi một API-Key và chữ ký hợp lệ |
USER_STREAM | Endpoint yêu cầu gửi một Khóa API hợp lệ |
MARKET_DATA | Endpoint yêu cầu gửi một Khóa API hợp lệ |
- Endpoint
TRADE
vàUSER_DATA
là EndpointSIGNED
.
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 trongchuỗ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ànhHMAC SHA256
có khóa. Sử dụngsecretKey (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ầnthâ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 saudấu thời gian
mà yêu cầu có hiệu lực. NếurecvWindow §
§ 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óa | Giá trị |
---|---|
apiKey | vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A |
secretKey | NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j |
Tham số | Giá trị |
---|---|
symbol | LTC/BTC |
side | BUY |
type | LIMIT |
timeInforce | GTC |
quantity | 1 |
price | 0,1 |
recvWindow | 5000 |
timestamp | 1499827319559 |
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×tamp=1499827319559
HMAC SHA256 signature
[linux]$ echo -n
"symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=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×tamp=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×tamp=1499827319559
HMAC SHA256 signature:
[linux]$ echo -n
"symbol=LTC%2FBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000×tamp=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×tamp=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óa | Giá trị |
---|---|
apiKey | vmPUZE6mv9SD5VNHk4HlWFsOr6aKE2zvsw0MuIgwCIPy6utIco14y7Ju91duEh8A |
secretKey | NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j |
Tham số | Giá trị |
---|---|
symbol | BTC/USD_LEVERAGE |
side | BUY |
type | MARKET |
timeInforce | GTC |
quantity | 0.01 |
quantity | 2 |
accountId | 2376109060084932 |
takeProfit | 8000 |
stopLoss | 6000 |
recvWindow | 60000 |
timestamp | 1586942164000 |
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×tamp=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×tamp=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×tamp=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×tamp=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×tamp=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×tamp=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