기본 정보#
| 항목 | 내용 |
|---|
| Base URL | https://open-api.moda.co.kr |
| 프로토콜 | HTTPS (TLS 1.2 이상) |
| 데이터 형식 | JSON |
| 인증 | JWT (HS512) + HMAC-SHA512 서명 |
요청 형식#
HTTP Method#
| Method | 용도 | 예시 |
|---|
GET | 데이터 조회 | 시세, 잔고, 주문 내역 |
POST | 데이터 생성 | 주문 생성 |
PATCH | 데이터 수정 | 주문 정정 |
DELETE | 데이터 삭제 | — |
Query Parameter — GET 요청#
Request Body — POST / PATCH 요청#
응답 형식#
성공 응답#
{
"status": "success",
"code": 200,
"data": { ... }
}
목록 응답#
{
"status": "success",
"code": 200,
"data": {
"contents": [ { ... } ]
}
}
에러 응답#
{
"type": "about:blank",
"title": "Security Error",
"status": 401,
"detail": "요청 서명(X-Signature)이 유효하지 않습니다.",
"instance": "/open/v1/orders",
"code": "OA_004",
"timestamp": "2026-03-03T12:00:00.000Z"
}
validation 필드가 추가됩니다.{
"type": "about:blank",
"title": "Validation Failed",
"status": 400,
"detail": "입력값 검증에 실패했습니다.",
"instance": "/open/v1/orders",
"code": "V0001",
"timestamp": "2026-03-03T12:00:00.000Z",
"validation": [
{ "field": "stockCd", "message": "유효하지 않은 종목코드입니다." }
]
}
HTTP 상태 코드#
| 코드 | 설명 | 재시도 |
|---|
200 | 요청 성공 | — |
201 | 리소스 생성 성공 | — |
400 | 잘못된 요청 | X |
401 | 인증 실패 | X |
403 | 권한 없음 | X |
404 | 리소스 없음 | X |
429 | Rate Limit 초과 | O (Retry-After 후) |
500 | 서버 내부 오류 | O (지수 백오프) |
데이터 타입#
| 타입 | 설명 | 예시 |
|---|
| String | 문자열 | "USDKRW" |
| Number | 정수 또는 소수 | 1350.50 |
| Boolean | 참/거짓 | true |
| DateTime | ISO 8601 | "2026-03-05T14:30:00.000Z" |
| Enum | 정해진 값 | "BUY", "SELL" |
페이징#
차트 데이터 등 목록 API는 offset + limit 기반 페이징을 사용합니다.| 파라미터 | 타입 | 설명 |
|---|
offset | string | 초기 요청 시 빈 문자열, 이후 마지막 데이터의 타임스탬프 |
limit | int | 조회할 항목 수 |
요청 예시#
시세 조회 — JWT 인증 필요#
조회 권한 API Key의 JWT 인증이 필요합니다.Python#
cURL#
응답 예시
{
"status": "success",
"code": 200,
"data": {
"contents": [
{ "buy": "1.84823", "sell": "1.84816", "buySize": "100000", "sellSize": "100000" },
{ "buy": "1.84826", "sell": "1.84813", "buySize": "500000", "sellSize": "500000" },
{ "buy": "1.84829", "sell": "1.84810", "buySize": "1000000", "sellSize": "1000000" },
{ "buy": "1.84839", "sell": "1.84801", "buySize": "3000000", "sellSize": "3000000" },
{ "buy": "1.84854", "sell": "1.84786", "buySize": "5000000", "sellSize": "5000000" }
]
}
}
주문 생성 — JWT + 서명 필요 (주문 API)#
JWT + 서명이 모두 필요합니다. 주문 권한 API Key가 필요합니다.Python#
cURL#
응답 예시
{
"status": "success",
"code": 200,
"data": {
"orderDateTime": "2026-03-05T14:30:00.000Z",
"orderNo": "27"
}
}
Best Practice#
인증 모듈 분리#
JWT 생성과 서명 로직을 별도 모듈로 분리하여 모든 API 호출에서 재사용하세요.Python — API 클라이언트 예시
시간 동기화#
중요
X-Timestamp 검증은 ±60초입니다. 시스템 시간이 부정확하면 주문 API 서명 인증이 실패합니다.
주문 멱등성 확인#
주의
주문 요청 후 타임아웃이 발생하면 주문이 이미 접수되었을 수 있습니다. 재주문 전에 반드시 주문 내역을 조회하여 중복 주문을 방지하세요.
Secret Key 관리#
환경변수 또는 .env 파일로 관리 (반드시 .gitignore에 추가)
프론트엔드 코드, 공개 저장소에 절대 포함 금지
로그에 Secret Key, JWT 토큰 노출 금지
