퍼스톡 OpenAPI 시작하기

퍼스톡 OpenAPI로 퍼스톡 웹에서 하는 일을 프로그램에서 그대로 할 수 있어요. 시세 조회, 매수·매도, 잔고·보유종목 확인, 커뮤니티 글쓰기 모두 됩니다. 나만의 트레이더봇이나 커스텀 퍼스톡 클라이언트를 만들어 보세요.

퍼스톡은 모의투자 서비스예요. 모든 금액은 실제 가치가 없는 가상 화폐(“원”)이고, API로 하는 거래도 똑같이 가상 거래입니다.

한눈에 보기

항목	값
REST API	`https://api.furstock.trade`
인증	OAuth 2.0 Client Credentials → `Authorization: Bearer <access_token>`
토큰 발급	`POST https://api.furstock.trade/oauth2/token`
실시간 시세	`wss://ws.furstock.trade/socket` (Phoenix Channels, 인증 불필요)
OpenAPI 스펙	openapi.json · openapi.yaml
Swagger UI	api.furstock.trade/docs
데이터 형식	JSON(UTF-8), 필드명 camelCase
요청 한도	API 키당 초당 10회(순간 20회)

5분 퀵스타트

1. API 키 발급

프로필 → OpenAPI 탭에서 새 키 발급을 누르면 client_id와 client_secret이 나와요. client_secret은 그때 한 번만 보이니 바로 안전한 곳에 복사해 두세요.

2. access token 받기

curl -s https://api.furstock.trade/oauth2/token 
  -d grant_type=client_credentials 
  -d client_id=$FURSTOCK_CLIENT_ID 
  -d client_secret=$FURSTOCK_CLIENT_SECRET

{ "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 3600 }

토큰은 1시간 동안 쓸 수 있어요. 만료되면 같은 요청으로 새로 받으면 됩니다.

3. 내 잔고 조회

curl -s https://api.furstock.trade/v1/accounts/buying-power 
  -H "Authorization: Bearer $TOKEN"

{ "cashBalance": 300000 }

4. 첫 주문

curl -s https://api.furstock.trade/v1/orders 
  -H "Authorization: Bearer $TOKEN" 
  -H "content-type: application/json" 
  -d '{"symbol":"FOXX","side":"buy","type":"market","quantity":1,"clientToken":"'$(uuidgen)'"}'

응답의 status가 filled면 체결된 거예요. 자세한 내용은 주문을 보세요.

할 수 있는 것

분류	주요 기능	문서
종목·시세	종목 목록(최대 1000개)·검색·상세, 현재가, 호가, 캔들, 체결, 인기·거래량·급상승·급하락 순위	종목·시세
계좌	잔고(주문가능금액), 보유종목, 프로필	계좌
주문	시장가·지정가 매수/매도, 주문 이력, 매매 대기열, 지정가 취소	주문
커뮤니티·소셜	종목토론 조회·작성·수정, 관심종목, 최근 본 종목, 종목 그룹, 뉴스·갤러리, 상장 신청	커뮤니티·소셜
실시간	종목별 시세 push	실시간 시세

API 키로 할 수 없는 것도 있어요. API 키 발급·폐기와 회원 탈퇴는 보안상 퍼스톡 웹에 로그인해서만 할 수 있어요. 자세한 건 인증을 보세요.

AI 에이전트로 봇 만들기

Claude Code, Cursor 같은 AI 코딩 에이전트에게 이 페이지 주소(https://furstock.trade/developers)만 알려주세요. 에이전트가 읽을 수 있는 자료를 따로 준비해 뒀어요.

/llms.txt: 에이전트용 문서 색인
/llms-full.txt: 모든 문서를 합친 한 파일
/skills/furstock-openapi/SKILL.md: 에이전트 스킬. 봇 개발 절차, 주의사항, 참고 문서 링크가 들어 있어요.
openapi.json: 기계가 읽는 정식 스펙

에이전트에게 이렇게 말하면 됩니다: ”https://furstock.trade/developers 를 참고해서 거래량 상위 종목을 매매하는 퍼스톡 봇을 만들어줘. 키는 환경변수 FURSTOCK_CLIENT_ID / FURSTOCK_CLIENT_SECRET에 있어.”

이용 수칙

키는 비밀번호와 같아요. 코드 저장소에 올리지 말고 환경변수로 관리하세요. 유출됐다면 바로 폐기하세요.
요청 한도를 지키고, 429를 받으면 Retry-After만큼 기다렸다 다시 시도하세요.
봇도 운영정책을 따라요. 커뮤니티 도배, 시세 조작을 노린 반복 매매 같은 행위는 이용 제한 대상이에요.