가상자산 거래 플랫폼 API 문서

👤 1. 유저 API (User)

1.1 회원가입

새로운 유저가 거래소에 가입합니다.

HTTP request

POST /api/users HTTP/1.1
Content-Type: application/json
Content-Length: 65
Host: localhost:8080

{"email":"apiTest@test.com","password":"1234","name":"apiTester"}

Request fields

Path Type Description

Path	Type	Description
`email`	`String`	사용자 이메일
`name`	`String`	사용자 이름
`password`	`String`	비밀번호 (4자리 이상)

email

String

사용자 이메일

name

String

사용자 이름

password

String

비밀번호 (4자리 이상)

HTTP response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: text/plain;charset=UTF-8
Content-Length: 20

회원가입 성공!

📈 2. 주식 API (Stock)

2.1 주식 목록 전체 조회

거래소에 상장된 전체 주식(코인) 목록을 조회합니다.

HTTP request

GET /api/stocks HTTP/1.1
Host: localhost:8080

HTTP response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
Content-Length: 56

[{"code":"KRW-BTC","name":"비트코인","price":1.0E8}]

Response fields

Path Type Description

Path	Type	Description
`[].code`	`String`	주식 종목 코드
`[].name`	`String`	주식 이름
`[].price`	`Number`	현재 가격

[].code

String

주식 종목 코드

[].name

String

주식 이름

[].price

Number

현재 가격

💰 3. 자산 API (My Asset)

3.1 원화(KRW) 충전

가상 자산 거래를 위한 원화(KRW) 예수금을 충전합니다.

HTTP request

PATCH /api/assets/charge HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjaGFyZ2VUZXN0QHRlc3QuY29tIiwiYXV0aCI6IlVTRVIiLCJpYXQiOjE3NzQ1OTIwMjQsImV4cCI6MTc3NDY3ODQyNH0.6qgSDdf2gkuGBjmy8MnFs6BR6inLKwpcc7J83_PgYJM
Content-Length: 15
Host: localhost:8080

{"money":10000}

Request headers

Name Description

Name	Description
`Authorization`	JWT 인증 토큰 (Bearer 타입 필수)

Authorization

JWT 인증 토큰 (Bearer 타입 필수)

Request fields

Path Type Description

Path	Type	Description
`money`	`Number`	충전할 금액 (최소 1원 이상)

money

Number

충전할 금액 (최소 1원 이상)

HTTP response

HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: text/plain;charset=UTF-8
Content-Length: 80
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

10000원이 정상적으로 충전되었습니다. (현재 총 잔고: 60000원)

3.2 내 포트폴리오 조회

로그인한 유저의 총 자산, 예수금, 수익률 및 보유 주식 목록을 상세 조회합니다.

HTTP request

GET /api/assets HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJzdG9ja0hvbGRpbmdBcGlUZXN0ZXJAdGVzdC5jb20iLCJhdXRoIjoiVVNFUiIsImlhdCI6MTc3NDU5MjAyNCwiZXhwIjoxNzc0Njc4NDI0fQ.EM-hiRJ9IixUn2Cd3SM_nWwInpg9mwLjdAodUGUys1E
Host: localhost:8080

Request headers

Name Description

Name	Description
`Authorization`	JWT 인증 토큰 (Bearer 타입 필수)

Authorization

JWT 인증 토큰 (Bearer 타입 필수)

HTTP response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 344

{"totalAssetAmount":150000000,"balance":50000000,"totalPurchaseAmount":80000000,"totalEvaluationAmount":100000000,"totalProfitLoss":20000000,"returnRate":25.0,"holdingList":[{"stockName":"비트코인","stockCode":"KRW-BTC","quantity":1,"avgPrice":10000.0,"currentPrice":5000.0,"profitRate":0.5,"purchaseAmount":10000,"evaluationAmount":5000}]}

Response fields

Path Type Description

Path	Type	Description
`totalAssetAmount`	`Number`	총 자산 금액
`balance`	`Number`	보유 예수금
`totalPurchaseAmount`	`Number`	총 매수 금액
`totalEvaluationAmount`	`Number`	총 평가 금액
`totalProfitLoss`	`Number`	총 평가 손익
`returnRate`	`Number`	총 수익률
`holdingList`	`Array`	보유 주식 목록
`holdingList[].stockName`	`String`	주식 이름
`holdingList[].stockCode`	`String`	주식 종목 코드
`holdingList[].quantity`	`Number`	보유 수량
`holdingList[].avgPrice`	`Number`	매수 평균 단가
`holdingList[].currentPrice`	`Number`	현재가
`holdingList[].profitRate`	`Number`	수익률
`holdingList[].purchaseAmount`	`Number`	총 매수 금액
`holdingList[].evaluationAmount`	`Number`	총 평가 금액

totalAssetAmount

Number

총 자산 금액

balance

Number

보유 예수금

totalPurchaseAmount

Number

총 매수 금액

totalEvaluationAmount

Number

총 평가 금액

totalProfitLoss

Number

총 평가 손익

returnRate

Number

총 수익률

holdingList

Array

보유 주식 목록

holdingList[].stockName

String

주식 이름

holdingList[].stockCode

String

주식 종목 코드

holdingList[].quantity

Number

보유 수량

holdingList[].avgPrice

Number

매수 평균 단가

holdingList[].currentPrice

Number

현재가

holdingList[].profitRate

Number

수익률

holdingList[].purchaseAmount

Number

총 매수 금액

holdingList[].evaluationAmount

Number

총 평가 금액

🛒 4. 주문 API (Order)

4.1 주문 접수 (매수/매도)

특정 주식에 대한 새로운 매수 또는 매도 주문을 서버(Kafka)로 전송합니다.

HTTP request

POST /api/orders HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJvcmRlckFwaVRlc3RAdGVzdC5jb21uIiwiYXV0aCI6IlVTRVIiLCJpYXQiOjE3NzQ1OTIwMjMsImV4cCI6MTc3NDY3ODQyM30.QKsKkC1zgh-HkQQrE3YssF_3FdWrn6Cy5WuGBQofFps
Content-Length: 46
Host: localhost:8080

{"code":"Code","quantity":1,"orderType":"BUY"}

Request headers

Name Description

Name	Description
`Authorization`	JWT 인증 토큰 (Bearer 타입 필수)

Authorization

JWT 인증 토큰 (Bearer 타입 필수)

Request fields

Path Type Description

Path	Type	Description
`code`	`String`	주식 종목 코드
`quantity`	`Number`	주문 수량 (최소 1주 이상)
`orderType`	`String`	주문 타입 (BUY 또는 SELL)

code

String

주식 종목 코드

quantity

Number

주문 수량 (최소 1주 이상)

orderType

String

주문 타입 (BUY 또는 SELL)

HTTP response

HTTP/1.1 202 Accepted
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: text/plain;charset=UTF-8
Content-Length: 20
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

주문 접수 완료

4.2 주문 내역 조회 (페이징)

로그인한 유저의 과거 주문 내역을 페이징 처리하여 최신순으로 조회합니다.

HTTP request

GET /api/orders HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJvcmRlckxpc3RBcGlUZXN0QHRlc3QuY29tbiIsImF1dGgiOiJVU0VSIiwiaWF0IjoxNzc0NTkyMDIyLCJleHAiOjE3NzQ2Nzg0MjJ9.-iWZ-ZVDDdkzp6BFGF42kvGkJEx9kM99ch-8dayiBFY
Host: localhost:8080

Request headers

Name Description

Name	Description
`Authorization`	JWT 인증 토큰 (Bearer 타입 필수)

Authorization

JWT 인증 토큰 (Bearer 타입 필수)

HTTP response

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 209

{"content":[{"orderId":1,"stockName":"Code","orderType":"매수","quantity":1,"price":1500.0,"totalAmount":1500.0,"orderDate":"2026-03-19 11:15"}],"page":{"size":1,"number":0,"totalElements":1,"totalPages":1}}

Response fields

Path Type Description

Path	Type	Description
`content[].orderId`	`Number`	주문 ID
`content[].stockName`	`String`	주식 이름
`content[].orderType`	`String`	주문 타입 (매수/매도)
`content[].quantity`	`Number`	주문 수량
`content[].price`	`Number`	1주당 가격
`content[].totalAmount`	`Number`	총 거래 금액
`content[].orderDate`	`String`	주문 일시 (yyyy-MM-dd HH:mm)
`page.totalElements`	`Number`	전체 데이터 개수
`page.totalPages`	`Number`	전체 페이지 수
`page.number`	`Number`	현재 페이지 번호 (0부터 시작)
`page.size`	`Number`	페이지당 데이터 개수

content[].orderId

Number

주문 ID

content[].stockName

String

주식 이름

content[].orderType

String

주문 타입 (매수/매도)

content[].quantity

Number

주문 수량

content[].price

Number

1주당 가격

content[].totalAmount

Number

총 거래 금액

content[].orderDate

String

주문 일시 (yyyy-MM-dd HH:mm)

page.totalElements

Number

전체 데이터 개수

page.totalPages

Number

전체 페이지 수

page.number

Number

현재 페이지 번호 (0부터 시작)

page.size

Number

페이지당 데이터 개수