Bỏ qua

Tài liệu tham khảo API

Các khái niệm chung

Khối lượng, giá, loại lệnh và thời gian hiệu lực

Khối lượng

Khối lượng được chỉ định bằng cent (đơn vị 0,0000001 lô).

Lô Khối lượng (cent)
0.01 100,000
0.1 1,000,000
1.0 10,000,000

Giá

Giá trị giá được tính bằng pipette. Để chuyển đổi: display_price = pipette_value / 10^pipDigits

Đối với EURUSD (5 chữ số), giá trị pipette là 112345 = 1.12345.

Loại lệnh

Loại Mô tả Trường bắt buộc
MARKET Thực hiện ngay lập tức ở giá hiện tại symbolId, tradeSide, volume
LIMIT Thực hiện ở giá giới hạn hoặc tốt hơn + limitPrice
STOP Kích hoạt khi thị trường đạt giá dừng + stopPrice
MARKET_RANGE Thực hiện trong phạm vi giá + baseSlippagePrice
STOP_LIMIT Lệnh giới hạn được kích hoạt ở giá dừng + stopPrice, limitPrice

Thời gian hiệu lực

Chính sách Mô tả
GOOD_TILL_CANCEL Lệnh vẫn hoạt động cho đến khi được khớp hoặc hủy
GOOD_TILL_DATE Lệnh hết hạn tại expirationTimestamp đã chỉ định
IMMEDIATE_OR_CANCEL Khớp những gì có sẵn ngay lập tức, hủy phần còn lại

Thông tin tài khoản

GET /v1/balance Get account balance

Trả về số dư tài khoản, vốn tức thời và dư ký quỹ.

Tham số

Không có tham số.

Phản hồi

200 Phản hồi thành công

Response body
{
  "balance": 10000.00,
  "equity": 10250.75,
  "freeMargin": 9800.50,
  "balanceVersion": 42,
  "moneyDigits": 2,
  "depositAssetId": 1
}
Trường Loại Mô tả
balance double Số dư tài khoản bằng đơn vị tiền tệ nạp
equity double Số dư + lãi/lỗ chưa thực hiện
freeMargin double Ký quỹ khả dụng cho giao dịch mới
balanceVersion int64 Bộ đếm phiên bản số dư
moneyDigits int32 Số chữ số thập phân cho giá trị tiền tệ
depositAssetId int64 ID tài sản tiền tệ nạp
GET /v1/symbols Lấy các mã giao dịch khả dụng

Trả về tất cả các mã giao dịch có sẵn để giao dịch trên tài khoản.

Tham số

Không có tham số.

Phản hồi

200 Mảng các đối tượng Symbol

Response body
[
  {
    "symbolId": 1,
    "symbolName": "EURUSD",
    "enabled": true,
    "baseAssetId": 2,
    "quoteAssetId": 1,
    "description": "Euro vs US Dollar"
  }
]

Symbol

Trường Loại Mô tả
symbolId int64 ID mã giao dịch (được sử dụng trong các lệnh gọi API khác)
symbolName string Tên mã giao dịch (ví dụ: "EURUSD")
enabled boolean Mã giao dịch có thể giao dịch hay không
baseAssetId int64 ID tài sản cơ sở
quoteAssetId int64 ID tài sản định giá
description string Mô tả dễ đọc
GET /v1/assets Lấy các tài sản khả dụng

Trả về các tài sản có sẵn (tiền tệ).

Tham số

Không có tham số.

Phản hồi

200 Mảng các đối tượng Asset

Response body
[
  {
    "assetId": 1,
    "name": "USD",
    "displayName": "US Dollar"
  }
]

Asset

Trường Loại Mô tả
assetId int64 ID tài sản
name string Mã tài sản (ví dụ: "USD")
displayName string Tên hiển thị

Dữ liệu thị trường

GET /v1/prices Lấy giá giao ngay

Trả về giá bid/ask hiện tại cho các mã giao dịch đã chỉ định. Đây là ảnh chụp nhanh – API không hỗ trợ truyền trực tuyến.

Tham số
Tên Nằm trong Loại Bắt buộc Mô tả
symbolId query int64[] ID mã giao dịch được phân tách bằng dấu phẩy
Phản hồi

200 Mảng các đối tượng SpotPrice

Response body
[
  {
    "symbolId": 1,
    "bid": 112340,
    "ask": 112355,
    "high": 112890,
    "low": 111950,
    "sessionClose": 112100,
    "timestamp": 1700000000000
  }
]

SpotPrice

Trường Loại Mô tả
symbolId int64 ID ký hiệu
bid int64 Giá bid tốt nhất (pipette)
ask int64 Giá ask tốt nhất (pipette)
high int64 Mức cao nhất trong phiên (pipette)
low int64 Mức thấp nhất trong phiên (pipette)
sessionClose int64 Giá đóng cửa phiên trước (pipette)
timestamp int64 Dấu thời gian báo giá (epoch ms)
GET /v1/trendbars Lấy dữ liệu OHLCV lịch sử

Trả về dữ liệu nến (OHLCV) lịch sử cho một mã giao dịch.

Tham số
Tên Nằm trong Loại Bắt buộc Mặc định Mô tả
symbolId query int64 – ID ký hiệu
period query string – Giai đoạn nến
fromTimestamp query string – Thời gian bắt đầu (ISO-8601)
toTimestamp query string – Thời gian kết thúc (ISO-8601)
count query int32 100 Số thanh tối đa để trả về
Các khoảng thời gian khả dụng

M_1 M_2 M_3 M_4 M_5 M_10 M_15 M_30 H_1 H_2 H_3 H_4 H_6 H_8 H_12 D_1 W_1 MN_1

Phản hồi

200 Mảng các đối tượng Trendbar

Response body
[
  {
    "timestamp": 1700000000000,
    "open": 112340.0,
    "high": 112890.0,
    "low": 111950.0,
    "close": 112500.0,
    "volume": 4521
  }
]

Trendbar

Trường Loại Mô tả
timestamp int64 Thời gian mở thanh (epoch ms)
open double Giá mở cửa (pipettes)
high double Giá cao nhất (pipettes)
low double Giá thấp nhất (pipettes)
close double Giá đóng cửa (pipettes)
volume int64 Khối iượng tick

Lệnh

POST /v1/orders Đặt lệnh mới

Đặt một lệnh giao dịch mới. Trả về một ExecutionResponse.

Tham số

Không có tham số đường dẫn hoặc truy vấn.

Nội dung yêu cầu application/json
Trường Loại Bắt buộc Mô tả
symbolId int64 Ký hiệu để giao dịch
orderType string MARKET, LIMIT, STOP, MARKET_RANGE, STOP_LIMIT
tradeSide string BUY hoặc SELL
volume int64 Khối lượng tính bằng xu
limitPrice double Giá giới hạn – bắt buộc đối với LIMIT, STOP_LIMIT
stopPrice double Giá kích hoạt dừng – bắt buộc đối với STOP, STOP_LIMIT
stopLoss double Giá cắt lỗ
takeProfit double Giá chốt lời
comment string Bình luận văn bản tự do (tối đa 256 ký tự)
label string Nhãn bot (tối đa 100 ký tự)
timeInForce string GOOD_TILL_CANCEL, GOOD_TILL_DATE, IMMEDIATE_OR_CANCEL
baseSlippagePrice double Giá cơ sở cho trượt giá – bắt buộc đối với MARKET_RANGE
slippageInPoints int32 Trượt giá tối đa tính theo điểm
expirationTimestamp int64 Dấu thời gian hết hạn (epoch ms) – đối với GOOD_TILL_DATE
Example request body
{
  "symbolId": 1,
  "orderType": "MARKET",
  "tradeSide": "BUY",
  "volume": 10000000,
  "stopLoss": 112000,
  "takeProfit": 113000
}
Phản hồi

200 ExecutionResponse – lệnh được chấp nhận hoặc đã khớp

400 INVALID_REQUEST hoặc TRADING_BAD_VOLUME

422 NOT_ENOUGH_MONEY

409 MARKET_CLOSED

Example success response
{
  "orderId": 12345,
  "positionId": 67890,
  "executionType": "ORDER_FILLED",
  "order": { "..." : "..." },
  "position": { "..." : "..." },
  "deal": { "..." : "..." }
}
GET /v1/orders Lấy các lệnh chờ

Trả về tất cả các lệnh chờ (chưa khớp).

Tham số

Không có tham số.

Phản hồi

200 Mảng các đối tượng lệnh chờ

PUT /v1/orders/{orderId} Sửa đổi lệnh chờ

Sửa đổi một lệnh chờ hiện có. Trả về một ExecutionResponse.

Tham số
Tên Nằm trong Loại Bắt buộc Mô tả
orderId path int64 Lệnh cần sửa đổi
Nội dung yêu cầu application/json

Bất kỳ tập hợp con nào của các trường sau.

Trường Loại Mô tả
volume int64 Khối lượng mới tính theo cent
limitPrice double Giá giới hạn mới
stopPrice double Giá dừng mới
stopLoss double Giá cắt lỗ mới
takeProfit double Giá chốt lời mới
expirationTimestamp int64 Dấu thời gian hết hạn mới (epoch ms)
Phản hồi

200 ExecutionResponse với ORDER_REPLACED

404 Không tìm thấy lệnh

DELETE /v1/orders/{orderId} Hủy lệnh chờ

Hủy một lệnh chờ. Trả về một ExecutionResponse.

Tham số
Tên Nằm trong Loại Bắt buộc Mô tả
orderId path int64 Lệnh cần hủy
Phản hồi

200 ExecutionResponse với ORDER_CANCELLED

404 Không tìm thấy lệnh

GET /v1/orders/history Lấy lịch sử lệnh

Trả về các lệnh lịch sử trong một khoảng thời gian.

Tham số
Tên Nằm trong Loại Bắt buộc Mô tả
fromTimestamp query string Thời gian bắt đầu (ISO-8601)
toTimestamp query string Thời gian kết thúc (ISO-8601)
Phản hồi

200 OrderListResponse

Trường Loại Mô tả
orders Order[] Mảng các lệnh lịch sử
hasMore boolean Có các trang bổ sung khả dụng hay không

Vị thế

GET /v1/positions Lấy các vị thế đang mở

Trả về tất cả các vị thế đang mở và lệnh chờ.

Tham số

Không có tham số.

Phản hồi

200 Mảng các đối tượng Position

Response body
[
  {
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "entryPrice": 112345.0,
    "stopLoss": 112000.0,
    "takeProfit": 113000.0,
    "unrealizedPnl": 155.25,
    "commission": -7.00,
    "swap": -1.20
  }
]

Vị thế

Trường Loại Mô tả
positionId int64 ID vị thế
symbolId int64 ID ký hiệu
tradeSide string BUY hoặc SELL
volume int64 Khối lượng tính bằng xu
entryPrice double Giá vào lệnh VWAP
stopLoss double Giá cắt lỗ
takeProfit double Giá chốt lời
unrealizedPnl double Lãi/lỗ thả nổi
commission double Hoa hồng đã tính
swap double Số tiền phí qua đêm
GET /v1/positions/{positionId} Lấy chi tiết vị thế

Trả về một vị thế cùng với các lệnh và giao dịch liên quan.

Tham số
Tên Nằm trong Loại Bắt buộc Mô tả
positionId path int64 ID vị thế
Phản hồi

200 PositionDetailResponse

Trường Loại Mô tả
position Position Đối tượng vị thế
orders Order[] Các lệnh liên quan
deals Deal[] Các giao dịch liên quan
PUT /v1/positions/{positionId} Sửa đổi cắt lỗ/chốt lời của vị thế

Cập nhật cắt lỗ và/hoặc chốt lời cho một vị thế đang mở. Trả về một ExecutionResponse.

Tham số
Tên Nằm trong Loại Bắt buộc Mô tả
positionId path int64 ID vị thế
Nội dung yêu cầu application/json
Trường Loại Mô tả
stopLoss double Giá cắt lỗ mới (null để xóa)
takeProfit double Giá chốt lời mới (null để xóa)
trailingStopLoss boolean Bật cắt lỗ di động
Example request body
{
  "stopLoss": 111500,
  "takeProfit": 113500,
  "trailingStopLoss": false
}
Phản hồi

200 ExecutionResponse

POST /v1/positions/{positionId}/close Đóng một vị thế

Đóng một vị thế đang mở hoàn toàn hoặc một phần. Sử dụng giá trị nhỏ hơn khối lượng đầy đủ của vị thế để đóng một phần. Trả về một ExecutionResponse.

Tham số
Tên Nằm trong Loại Bắt buộc Mô tả
positionId path int64 ID vị thế
Nội dung yêu cầu application/json
Trường Loại Bắt buộc Mô tả
volume int64 Khối lượng cần đóng tính bằng cent
Example – full close (1 lot)
{
  "volume": 10000000
}
Phản hồi

200 ExecutionResponse

422 NOT_ENOUGH_MONEY – ký quỹ không đủ để đóng một phần

Giao dịch

GET /v1/deals Lấy lịch sử giao dịch

Trả về các giao dịch đã thực hiện trong một khoảng thời gian.

Tham số
Tên Nằm trong Loại Bắt buộc Mặc định Mô tả
fromTimestamp query string – Thời gian bắt đầu (ISO-8601)
toTimestamp query string – Thời gian kết thúc (ISO-8601)
maxRows query int32 50 Số giao dịch tối đa cần trả về
Phản hồi

200 Mảng các đối tượng Deal

Response body
[
  {
    "dealId": 11111,
    "orderId": 12345,
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "filledVolume": 10000000,
    "executionPrice": 112345.0,
    "executionTimestamp": 1700000000000,
    "dealStatus": "FILLED",
    "commission": -7.00
  }
]

Deal

Trường Loại Mô tả
dealId int64 ID giao dịch
orderId int64 Lệnh đã kích hoạt giao dịch này
positionId int64 ID vị thế
symbolId int64 ID ký hiệu
tradeSide string BUY hoặc SELL
volume int64 Khối lượng yêu cầu tính bằng cent
filledVolume int64 Khối lượng đã khớp tính bằng cent
executionPrice double Giá thực hiện
executionTimestamp int64 Thời gian thực hiện (epoch ms)
dealStatus string Trạng thái – xem các giá trị bên dưới
commission double Hoa hồng đã tính

Giá trị dealStatus

Giá trị Ý nghĩa
FILLED Lệnh đã được khớp hoàn toàn
PARTIALLY_FILLED Lệnh khớp một phần
REJECTED Bị từ chối bởi máy chủ giao dịch
INTERNALLY_REJECTED Bị từ chối nội bộ trước khi đến máy chủ
ERROR Đã xảy ra lỗi trong quá trình thực hiện
MISSED Lệnh bị bỏ lỡ (ví dụ: khoảng trống trong thị trường)

Schemas { #execution-response-schema }

ExecutionResponse

Tất cả các thao tác đặt lệnh, sửa đổi và hủy lệnh đều trả về đối tượng này.

Trường Loại Mô tả
orderId int64 ID lệnh bị ảnh hưởng
positionId int64 ID vị thế bị ảnh hưởng
executionType string Loại kết quả – xem các giá trị bên dưới
order Order Chi tiết lệnh (nếu có)
position Position Chi tiết vị thế (nếu có)
deal Deal Chi tiết giao dịch (nếu có)

Giá trị executionType

Giá trị Ý nghĩa
ORDER_ACCEPTED Lệnh chờ đã được chấp nhận
ORDER_FILLED Lệnh đã được khớp hoàn toàn
ORDER_REPLACED Lệnh đã được sửa đổi
ORDER_CANCELLED Lệnh đã hủy
ORDER_EXPIRED Lệnh đã hết hạn
ORDER_REJECTED Lệnh bị từ chối
ORDER_CANCEL_REJECTED Yêu cầu hủy bị từ chối
ORDER_PARTIAL_FILL Lệnh khớp một phần
SWAP Hoán đổi vị thế đã được áp dụng
DEPOSIT Nạp tiền vào tài khoản
WITHDRAW Rút tiền khỏi tài khoản
BONUS_DEPOSIT_WITHDRAW Nạp hoặc rút tiền thưởng

Giới hạn tốc độ

Cổng thông tin thực thi giới hạn tốc độ ở nhiều cấp độ.

Mức Mô tả
Mỗi IP Giới hạn tổng số yêu cầu từ một địa chỉ IP duy nhất
Mỗi người dùng Giới hạn tổng số yêu cầu trên tất cả các tài khoản cho một token duy nhất
Mỗi tài khoản Giới hạn các yêu cầu nhắm đến một tài khoản giao dịch duy nhất

Vượt quá giới hạn tốc độ

Khi vượt quá giới hạn tốc độ, API trả về 429 Too Many Requests với tiêu đề Retry-After.

Xử lý lỗi

Khi một yêu cầu thất bại, API trả về phản hồi lỗi JSON.

Error response format
{
  "error": {
    "code": "NOT_ENOUGH_MONEY",
    "message": "Insufficient free margin for this order",
    "httpStatus": 422,
    "retryAfter": null
  }
}

Mã lỗi

Mã HTTP Mô tả
INVALID_REQUEST 400 Tham số yêu cầu không hợp lệ hoặc bị thiếu
UNAUTHORIZED 401 Token không hợp lệ, hết hạn hoặc bị thiếu
TRADING_BAD_VOLUME 400 Khối lượng không hợp lệ (dưới mức tối thiểu hoặc vượt quá vị thế)
NOT_ENOUGH_MONEY 422 Dư ký quỹ không đủ
SYMBOL_NOT_FOUND 404 ID mã giao dịch không tồn tại
MARKET_CLOSED 409 Thị trường cho mã giao dịch hiện đang đóng cửa
MAINTENANCE 503 Máy chủ giao dịch đang trong chế độ bảo trì
TIMEOUT 504 Máy chủ giao dịch không phản hồi kịp thời
GATEWAY_RATE_LIMIT 429 Vượt quá giới hạn tốc độ – xem tiêu đề Retry-After

Xử lý giới hạn tốc độ

Khi bạn nhận được phản hồi 429, tiêu đề Retry-After và trường retryAfter cho biết bạn phải đợi bao nhiêu giây trước khi gửi yêu cầu tiếp theo.