콘텐츠로 이동

API 참조

일반 개념

거래량, 가격, 주문 유형 및 유효 기간

거래량

거래량은 센트(0.0000001 로트 단위)로 지정됩니다.

로트 거래량(센트)
0.01 100,000
0.1 1,000,000
1.0 10,000,000

가격

가격 값은 피펫으로 표시됩니다. 변환하려면: display_price = pipette_value / 10^pipDigits

EURUSD(5자리)의 경우, 피펫 값 112345 = 1.12345.

주문 유형

유형 설명 필수 필드
MARKET 현재 가격으로 즉시 실행 symbolId, tradeSide, volume
LIMIT 지정가 또는 더 나은 가격으로 실행 + limitPrice
STOP 시장이 스톱 가격에 도달하면 트리거 + stopPrice
MARKET_RANGE 가격 범위 내에서 실행 + baseSlippagePrice
STOP_LIMIT 스톱 가격에서 트리거되는 지정가 주문 + stopPrice, limitPrice

유효 기간

정책 설명
GOOD_TILL_CANCEL 주문이 체결되거나 취소될 때까지 활성 상태 유지
GOOD_TILL_DATE 지정된 expirationTimestamp에 주문 만료
IMMEDIATE_OR_CANCEL 즉시 사용 가능한 만큼 체결하고 나머지는 취소

계정 정보

GET /v1/balance Get account balance

계정 잔고, 평가금 및 사용 가능 증거금을 반환합니다.

매개 변수

매개변수 없음.

응답

200 성공적인 응답

Response body
{
  "balance": 10000.00,
  "equity": 10250.75,
  "freeMargin": 9800.50,
  "balanceVersion": 42,
  "moneyDigits": 2,
  "depositAssetId": 1
}
필드 종류 설명
balance double 입금 통화로 표시된 계정 잔고
equity double 잔고 + 미실현 손익
freeMargin double 새 거래에 사용 가능한 증거금
balanceVersion int64 잔고 버전 카운터
moneyDigits int32 금액 값의 소수 자릿수
depositAssetId int64 입금 통화 자산 ID
GET /v1/symbols 사용 가능한 심볼 가져오기

계정에서 거래 가능한 모든 심볼을 반환합니다.

매개 변수

매개변수 없음.

응답

200 심볼 객체 배열

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

심볼

필드 종류 설명
symbolId int64 심볼 ID(다른 API 호출에 사용됨)
symbolName string 심볼 이름(예: "EURUSD")
enabled boolean 심볼의 거래 가능 여부
baseAssetId int64 기본 자산 ID
quoteAssetId int64 호가 자산 ID
description string 사람이 읽을 수 있는 설명
GET /v1/assets 사용 가능한 자산 가져오기

사용 가능한 자산(통화)을 반환합니다.

매개 변수

매개변수 없음.

응답

200 자산 객체 배열

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

자산

필드 종류 설명
assetId int64 자산 ID
name string 자산 코드(예: "USD")
displayName string 표시 이름

시장 데이터

GET /v1/prices 현물 가격 가져오기

지정된 심볼의 현재 매도/매수 가격을 반환합니다. 이것은 스냅샷입니다. API는 스트리밍을 지원하지 않습니다.

매개 변수
이름 위치 종류 필수 설명
symbolId query int64[] 쉼표로 구분된 심볼 ID
응답

200 현물 가격 객체 배열

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

현물 가격

필드 종류 설명
symbolId int64 심볼 ID
bid int64 최고 매도 가격(피펫)
ask int64 최고 매수 가격(피펫)
high int64 세션 최고가(피펫)
low int64 세션 최저가(피펫)
sessionClose int64 이전 세션 종가(피펫)
timestamp int64 호가 타임스탬프(에포크 ms)
GET /v1/trendbars 과거 OHLCV 데이터 가져오기

심볼의 과거 캔들스틱(OHLCV) 데이터를 반환합니다.

매개 변수
이름 위치 종류 필수 기본 설명
symbolId query int64 – 심볼 ID
period query string – 바 기간
fromTimestamp query string – 시작 시간 (ISO-8601)
toTimestamp query string – 종료 시간 (ISO-8601)
count query int32 100 반환할 최대 바 수
사용 가능한 기간

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

응답

200 Trendbar 객체 배열

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

Trendbar

필드 종류 설명
timestamp int64 바 시작 시간 (epoch ms)
open double 시가 (피펫)
high double 고가 (피펫)
low double 저가 (피펫)
close double 종가 (피펫)
volume int64 틱 거래량

주문

POST /v1/orders 새 주문 실행

새로운 거래 주문을 실행합니다. ExecutionResponse를 반환합니다.

매개 변수

경로 또는 쿼리 매개변수 없음.

요청 본문 application/json
필드 종류 필수 설명
symbolId int64 거래할 심벌
orderType string MARKET, LIMIT, STOP, MARKET_RANGE, STOP_LIMIT
tradeSide string BUY 또는 SELL
volume int64 센트 단위의 거래량
limitPrice double 지정가 – LIMIT, STOP_LIMIT에 필수
stopPrice double 역지정 트리거 가격 – STOP, STOP_LIMIT에 필수
stopLoss double 손절매 가격
takeProfit double 이익실현 가격
comment string 자유 텍스트 코멘트 (최대 256자)
label string 봇 레이블 (최대 100자)
timeInForce string GOOD_TILL_CANCEL, GOOD_TILL_DATE, IMMEDIATE_OR_CANCEL
baseSlippagePrice double 슬리피지 기준 가격 – MARKET_RANGE에 필수
slippageInPoints int32 포인트 단위 최대 슬리피지
expirationTimestamp int64 만료 타임스탬프 (epoch ms) – GOOD_TILL_DATE용
Example request body
{
  "symbolId": 1,
  "orderType": "MARKET",
  "tradeSide": "BUY",
  "volume": 10000000,
  "stopLoss": 112000,
  "takeProfit": 113000
}
응답

200 ExecutionResponse – 주문 접수 또는 체결됨

400 INVALID_REQUEST 또는 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 예약 주문 조회

모든 예약(미체결) 주문을 반환합니다.

매개 변수

매개변수 없음.

응답

200 예약 주문 객체 배열

PUT /v1/orders/{orderId} 예약 주문 수정

기존 예약 주문을 수정합니다. ExecutionResponse를 반환합니다.

매개 변수
이름 위치 종류 필수 설명
orderId path int64 수정할 주문
요청 본문 application/json

다음 필드의 하위 집합.

필드 종류 설명
volume int64 센트 단위 새 거래량
limitPrice double 새 지정가
stopPrice double 새 역지정가
stopLoss double 새 손절매 가격
takeProfit double 새 이익실현 가격
expirationTimestamp int64 새 만료 타임스탬프 (epoch ms)
응답

200 ORDER_REPLACED가 포함된 ExecutionResponse

404 주문을 찾을 수 없음

DELETE /v1/orders/{orderId} 예약 주문 취소

예약 주문을 취소합니다. ExecutionResponse를 반환합니다.

매개 변수
이름 위치 종류 필수 설명
orderId path int64 취소할 주문
응답

200 ORDER_CANCELLED이 포함된 ExecutionResponse

404 주문을 찾을 수 없음

GET /v1/orders/history 주문 내역 조회

시간 범위 내의 과거 주문을 반환합니다.

매개 변수
이름 위치 종류 필수 설명
fromTimestamp query string 시작 시간 (ISO-8601)
toTimestamp query string 종료 시간 (ISO-8601)
응답

200 OrderListResponse

필드 종류 설명
orders Order[] 과거 주문 배열
hasMore boolean 추가 페이지 사용 가능 여부

포지션

GET /v1/positions 미결 포지션 조회

모든 미결 포지션 및 예약 주문을 반환합니다.

매개 변수

매개변수 없음.

응답

200 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
  }
]

포지션

필드 종류 설명
positionId int64 포지션 ID
symbolId int64 심볼 ID
tradeSide string BUY 또는 SELL
volume int64 센트 단위의 거래량
entryPrice double VWAP 진입 가격
stopLoss double 손절매 가격
takeProfit double 이익실현 가격
unrealizedPnl double 평가 손익
commission double 부과된 수수료
swap double 스왑 금액
GET /v1/positions/{positionId} 포지션 세부정보 조회

포지션과 관련 주문 및 거래를 반환합니다.

매개 변수
이름 위치 종류 필수 설명
positionId path int64 포지션 ID
응답

200 PositionDetailResponse

필드 종류 설명
position Position Position 객체
orders Order[] 관련 주문
deals Deal[] 관련 거래
PUT /v1/positions/{positionId} 포지션 손절매/이익실현 수정

미결 포지션의 손절매 및/또는 이익실현을 업데이트합니다. ExecutionResponse를 반환합니다.

매개 변수
이름 위치 종류 필수 설명
positionId path int64 포지션 ID
요청 본문 application/json
필드 종류 설명
stopLoss double 새 손절매 가격 (제거하려면 null)
takeProfit double 새 이익실현 가격 (제거하려면 null)
trailingStopLoss boolean 추적 손절매 활성화
Example request body
{
  "stopLoss": 111500,
  "takeProfit": 113500,
  "trailingStopLoss": false
}
응답

200 ExecutionResponse

POST /v1/positions/{positionId}/close 포지션 청산

미결 포지션을 전체 또는 부분적으로 청산합니다. 부분 청산의 경우 포지션의 전체 거래량보다 작은 값을 사용하십시오. ExecutionResponse를 반환합니다.

매개 변수
이름 위치 종류 필수 설명
positionId path int64 포지션 ID
요청 본문 application/json
필드 종류 필수 설명
volume int64 청산할 거래량(센트 단위)
Example – full close (1 lot)
{
  "volume": 10000000
}
응답

200 ExecutionResponse

422 NOT_ENOUGH_MONEY – 부분 청산을 위한 증거금 부족

Deals

GET /v1/deals 거래 내역 조회

시간 범위 내에서 실행된 거래를 반환합니다.

매개 변수
이름 위치 종류 필수 기본 설명
fromTimestamp query string – 시작 시간 (ISO-8601)
toTimestamp query string – 종료 시간 (ISO-8601)
maxRows query int32 50 반환할 최대 거래 수
응답

200 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
  }
]

거래

필드 종류 설명
dealId int64 거래 ID
orderId int64 이 거래를 발생시킨 주문
positionId int64 포지션 ID
symbolId int64 심볼 ID
tradeSide string BUY 또는 SELL
volume int64 요청된 거래량(센트 단위)
filledVolume int64 체결된 거래량(센트 단위)
executionPrice double 체결 가격
executionTimestamp int64 체결 시간 (에포크 ms)
dealStatus string 상태 – 아래 값 참조
commission double 부과된 수수료

dealStatus 값

값 의미
FILLED 주문 완전 체결
PARTIALLY_FILLED 주문이 부분 체결됨
REJECTED 거래 서버에서 거부됨
INTERNALLY_REJECTED 서버 도달 전 내부적으로 거부됨
ERROR 실행 중 오류 발생
MISSED 주문 누락 (예: 시장 갭)

스키마 { #execution-response-schema }

ExecutionResponse

모든 주문 발주, 수정 및 취소 작업은 이 객체를 반환합니다.

필드 종류 설명
orderId int64 영향을 받은 주문 ID
positionId int64 영향을 받은 포지션 ID
executionType string 결과 유형 – 아래 값 참조
order Order 주문 세부정보 (해당하는 경우)
position Position 포지션 세부정보 (해당하는 경우)
deal Deal 거래 세부 정보(해당되는 경우)

executionType 값

값 의미
ORDER_ACCEPTED 예약 주문 수락됨
ORDER_FILLED 주문 전체 체결됨
ORDER_REPLACED 주문 수정됨
ORDER_CANCELLED 주문이 취소됨
ORDER_EXPIRED 주문이 만료됨
ORDER_REJECTED 주문이 거부됨
ORDER_CANCEL_REJECTED 취소 요청 거부됨
ORDER_PARTIAL_FILL 주문이 부분 체결됨
SWAP 포지션 스왑 적용됨
DEPOSIT 계정 입금
WITHDRAW 계정 출금
BONUS_DEPOSIT_WITHDRAW 보너스 입금 또는 출금

속도 제한

게이트웨이는 여러 수준에서 속도 제한을 적용합니다.

레벨 설명
IP당 단일 IP 주소에서의 총 요청 수를 제한합니다
사용자당 단일 토큰에 대한 모든 계정의 총 요청 수를 제한합니다
계정당 단일 거래 계정을 대상으로 하는 요청 수를 제한합니다

속도 제한 초과

속도 제한을 초과하면 API는 Retry-After 헤더와 함께 429 Too Many Requests를 반환합니다.

오류 처리

요청이 실패하면 API는 JSON 오류 응답을 반환합니다.

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

오류 코드

코드 HTTP 설명
INVALID_REQUEST 400 잘못되었거나 누락된 요청 매개 변수
UNAUTHORIZED 401 잘못되었거나, 만료되었거나, 누락된 토큰
TRADING_BAD_VOLUME 400 거래량이 유효하지 않음(최소값 미만이거나 포지션 초과)
NOT_ENOUGH_MONEY 422 사용 가능 증거금 부족
SYMBOL_NOT_FOUND 404 심벌 ID가 존재하지 않음
MARKET_CLOSED 409 심벌에 대한 시장이 현재 마감됨
MAINTENANCE 503 거래 서버가 유지 관리 모드임
TIMEOUT 504 거래 서버가 제시간에 응답하지 않음
GATEWAY_RATE_LIMIT 429 속도 제한 초과 – Retry-After 헤더 참조

속도 제한 처리

429 응답을 받으면 Retry-After 헤더와 retryAfter 필드가 다음 요청을 보내기 전에 대기해야 하는 시간(초)을 나타냅니다.