기본 정보#
| 항목 | 내용 |
|---|
| 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": [ { ... } ],
"totalPages": 5,
"totalElements": 42,
"isFirst": true,
"isLast": false
}
}
에러 응답#
{
"code": "OA_004",
"message": "Invalid signature",
"detail": "X-Signature 검증에 실패했습니다.",
"timestamp": "2026-03-03T12:00:00.000Z"
}
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는 공통 페이징 파라미터를 지원합니다.| 파라미터 | 타입 | 기본값 | 설명 |
|---|
page | int | 0 | 페이지 번호 (0-based) |
size | int | 20 | 페이지당 항목 수 (최대 100) |
sort | string | — | 정렬 기준 (예: createdAt,desc) |
요청 예시#
시세 조회 — JWT 인증 필요#
조회 권한 API Key의 JWT 인증이 필요합니다.Python#
cURL#
응답 예시
{
"status": "success",
"code": 200,
"data": {
"stockCd": "USDKRW",
"lastPrice": 1352.50,
"change": 2.50,
"changeRate": 0.19,
"volume": 15000000,
"high": 1355.00,
"low": 1348.00,
"timestamp": "2026-03-05T14:30:00.000Z"
}
}
주문 생성 — JWT + 서명 필요 (주문 API)#
JWT + 서명이 모두 필요합니다. 주문 권한 API Key가 필요합니다.Python#
cURL#
응답 예시
{
"status": "success",
"code": 201,
"data": {
"orderId": "ORD-2026-0001234",
"stockCd": "USDKRW",
"side": "BUY",
"type": "LIMIT",
"qty": 1000,
"price": 1350.50,
"status": "PENDING",
"createdAt": "2026-03-05T14:30:00.000Z"
}
}
Best Practice#
인증 모듈 분리#
JWT 생성과 서명 로직을 별도 모듈로 분리하여 모든 API 호출에서 재사용하세요.Python — API 클라이언트 예시
시간 동기화#
중요
X-Timestamp 검증은 ±60초입니다. 시스템 시간이 부정확하면 주문 API 서명 인증이 실패합니다.
주문 멱등성 확인#
주의
주문 요청 후 타임아웃이 발생하면 주문이 이미 접수되었을 수 있습니다. 재주문 전에 반드시 주문 내역을 조회하여 중복 주문을 방지하세요.
Secret Key 관리#
환경변수 또는 .env 파일로 관리 (반드시 .gitignore에 추가)
프론트엔드 코드, 공개 저장소에 절대 포함 금지
로그에 Secret Key, JWT 토큰 노출 금지
