API 명세서 — 모의 주식 트레이딩 서비스

{
  "email": "user@example.com",
  "password": "********",
  "nickname": "홍길동"
}

{
  "userId": 1,
  "nickname": "홍길동",
  "accessToken": "eyJhbGciOi...",
  "account": {
    "accountId": 1,
    "roundNo": 1,
    "initialCash": "50000000",
    "cashBalance": "50000000"
  }
}

{ "email": "user@example.com", "password": "********" }

응답은 회원가입과 동일한 형태입니다.

{ "userId": 1, "email": "user@example.com", "nickname": "홍길동" }

{
  "markets": [
    {
      "marketCountry": "KR",
      "open": true,
      "opensAt": "2026-08-11T09:00:00+09:00",
      "closesAt": "2026-08-11T15:30:00+09:00",
      "nextOpensAt": null
    },
    {
      "marketCountry": "US",
      "open": false,
      "opensAt": null,
      "closesAt": null,
      "nextOpensAt": "2026-08-11T22:30:00+09:00"
    }
  ],
  "serverTime": "2026-08-11T12:36:59+09:00"
}

프론트는 이 응답으로 거래 버튼 활성화와 "실시간 / 종가" 문구를 판단합니다. 토스 /market-calendar 를 하루 1회 받아 캐싱한 값에서 계산합니다.

{
  "baseCurrency": "USD",
  "quoteCurrency": "KRW",
  "rate": "1398.50",
  "changeRate": "0.0016",
  "rateAt": "2026-08-11T15:00:00+09:00"
}

{
  "items": [
    { "rateAt": "2026-07-11T00:00:00+09:00", "rate": "1385.20" },
    { "rateAt": "2026-07-11T01:00:00+09:00", "rate": "1385.60" }
  ]
}

exchange_rate 테이블(매시 정각 적재)에서 집계합니다.

{
  "items": [
    {
      "rank": 1,
      "symbol": "005930",
      "name": "삼성전자",
      "market": "KOSPI",
      "category": "INDIVIDUAL",
      "isDividend": false,
      "leverageFactor": null,
      "currency": "KRW",
      "lastPrice": "241500",
      "prevClose": "236050",
      "changeAmount": "5450",
      "changeRate": "0.0231",
      "tradingAmount": "1240000000000",
      "quoteAt": "2026-08-11T12:36:59+09:00",
      "realtime": true
    }
  ],
  "nextCursor": "eyJ0YSI6IjEyNDAwMDAwMDAwMDAiLCJpZCI6MTAyNH0",
  "hasNext": true
}

화면 컬럼 매핑 — 종목명(name) · 티커(symbol) · 종류(category) · 현재가(lastPrice) · 전일대비(changeAmount, changeRate) · 거래대금(tradingAmount)

{
  "items": [
    {
      "symbol": "005930",
      "name": "삼성전자",
      "englishName": "SamsungElec",
      "market": "KOSPI",
      "marketCountry": "KR",
      "category": "INDIVIDUAL"
    }
  ]
}

{
  "symbol": "005930",
  "name": "삼성전자",
  "englishName": "SamsungElec",
  "market": "KOSPI",
  "marketCountry": "KR",
  "currency": "KRW",
  "isinCode": "KR7005930003",

  "category": "INDIVIDUAL",
  "leverageFactor": null,
  "isDividend": false,

  "price": {
    "lastPrice": "241500",
    "prevClose": "236050",
    "changeAmount": "5450",
    "changeRate": "0.0231",
    "upperLimit": "313500",
    "lowerLimit": "169500",
    "quoteAt": "2026-08-11T12:36:59+09:00",
    "realtime": true
  },

  "info": {
    "marketCap": "1441000000000000",
    "sharesOutstanding": "5969782550",
    "listDate": "1975-06-11"
  },

  "warnings": [
    { "type": "INVESTMENT_WARNING", "label": "투자경고" }
  ],

  "tradable": true,
  "tradableReason": null
}

{
  "symbol": "005930",
  "interval": "1d",
  "range": "6M",
  "currency": "KRW",
  "items": [
    {
      "at": "2026-08-11T00:00:00+09:00",
      "open": "237000",
      "high": "242500",
      "low": "236500",
      "close": "241500",
      "volume": "12345678"
    }
  ]
}

// 1주차 분봉 처리 흐름
GET /stocks/NVDA/candles?interval=1m&range=1D
   ↓
minute_candle 에 60초 이내 데이터가 있나?
   ├ 있다  → DB 에서 바로 반환                      토스 호출 없음
   └ 없다  → 토스 /candles?interval=1m&count=200 호출
             ↓  ON CONFLICT DO NOTHING 으로 UPSERT
             DB 에서 반환

?symbol=005930&side=BUY&quantity=10

{
  "symbol": "005930",
  "side": "BUY",
  "quantity": "10",
  "executedPrice": "241500",
  "exchangeRate": "1",
  "grossAmount": "2415000",
  "fee": "242",
  "tax": "0",
  "netAmount": "2415242",
  "availableCash": "48240000",
  "quoteAt": "2026-08-11T12:36:59+09:00",
  "executable": true,
  "reason": null
}

매수   netAmount = grossAmount + fee           (예수금에서 차감)
매도   netAmount = grossAmount − fee − tax     (예수금으로 입금)

grossAmount = executedPrice × quantity × exchangeRate
fee         = grossAmount × FEE_RATE       0.0001 · 매수/매도 · 국내/미국 공통

tax  매도 시에만. 시장에 따라 계산식이 다르다
  국내  k_tax = grossAmount × K_TAX_RATE                     0.002
  미국  a_tax = max(grossAmount × A_TAX_RATE, A_TAX_MIN_USD × exchangeRate)
                                          0.0000206, 최소 $0.01

매수는 훨씬 단순합니다 — 두 시장 모두 tax = 0 이라 삼성전자 10주는 2,415,000 + 242 = 2,415,242 차감입니다.

{
  "clientOrderId": "018f2c9e-4a1b-7c3d-9e5f-1a2b3c4d5e6f",
  "symbol": "005930",
  "side": "BUY",
  "quantity": "10"
}

{
  "orderId": 1024,
  "status": "FILLED",
  "symbol": "005930",
  "side": "BUY",
  "quantity": "10",
  "executedPrice": "241500",
  "exchangeRate": "1",
  "grossAmount": "2415000",
  "fee": "242",
  "tax": "0",
  "netAmount": "2415242",
  "quoteAt": "2026-08-11T12:36:59+09:00",
  "orderedAt": "2026-08-11T12:37:02+09:00",
  "account": {
    "cashBalance": "45824758",
    "totalAsset": "50412300"
  }
}

응답에 갱신된 계좌 요약을 포함하면 프론트가 재조회하지 않아도 됩니다.

① SELECT ... FROM account WHERE account_id = ? FOR UPDATE
② 검증 — 장 시간 · is_ranked · 거래정지 · 시세 유효시간 · 예수금/보유수량
③ INSERT trade_order       (clientOrderId 유니크 위반 → 중복 요청)
④ UPDATE account.cash_balance
⑤ INSERT ledger_entry       (append only)
⑥ UPSERT holding            (이동평균 단가 재계산)

{
  "accountId": 1,
  "roundNo": 1,
  "initialCash": "50000000",
  "cashBalance": "48240000",
  "stockValue": "2172300",
  "totalAsset": "50412300",
  "unrealizedPnl": "137300",
  "unrealizedPnlRate": "0.0675",
  "exchangeRate": "1398.50",
  "asOf": "2026-08-11T12:36:59+09:00"
}

1주차는 평가손익만 제공합니다. 실현손익은 체결 내역이 쌓인 뒤 2주차에 분리합니다. stockValue 는 holding × quote_snapshot.last_price 로 계산하며, 해외 종목은 exchangeRate 로 원화 환산합니다.

{
  "items": [
    {
      "symbol": "005930",
      "name": "삼성전자",
      "currency": "KRW",
      "quantity": "6",
      "avgBuyPrice": "228000",
      "avgExchangeRate": "1",
      "lastPrice": "241500",
      "evaluationAmount": "1449000",
      "unrealizedPnl": "81000",
      "unrealizedPnlRate": "0.0592",
      "realtime": true
    }
  ],
  "asOf": "2026-08-11T12:36:59+09:00"
}

{
  "items": [
    {
      "entryId": 3041,
      "entryType": "BUY",
      "amount": "-2415242",        // gross 2,415,000 + fee 242
      "balanceAfter": "47584758",
      "exchangeRate": "1",
      "memo": "삼성전자 10주 @ 241,500 (수수료 포함)",
      "orderId": 1024,
      "symbol": "005930",
      "name": "삼성전자",
      "occurredAt": "2026-08-11T12:37:02+09:00"
    },
    {
      "entryId": 3040,
      "entryType": "INITIAL_DEPOSIT",
      "amount": "50000000",
      "balanceAfter": "50000000",
      "exchangeRate": "1",
      "memo": "모의투자금 지급",
      "orderId": null,
      "symbol": null,
      "name": null,
      "occurredAt": "2026-08-10T09:00:00+09:00"
    }
  ],
  "nextCursor": "eyJlbnRyeUlkIjozMDQwfQ",
  "hasNext": false
}

체결 시점 환율입니다. 원화 종목은 1, 미국 종목은 그때의 USD/KRW. amount 는 이미 원화 환산값이라 계산에 쓰이지는 않습니다 — "이 거래를 얼마짜리 환율로 했는가"를 원장만 보고 알 수 있게 하는 감사 항목입니다. 1주차 화면에는 안 띄워도 되지만, 지금 안 남기면 과거 값은 복원할 수 없습니다.

{
  "accountId": 2,
  "roundNo": 2,
  "initialCash": "50000000",
  "cashBalance": "50000000"
}

UPDATE account SET status='CLOSED', closed_at=now() WHERE account_id = 현재;
INSERT INTO account (user_id, round_no, ...) VALUES (?, 이전+1, 50000000, 50000000);
INSERT INTO ledger_entry (entry_type='INITIAL_DEPOSIT', ...);