# 퍼스톡 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](https://api.furstock.trade/openapi.json) · [openapi.yaml](https://api.furstock.trade/openapi.yaml) |
| Swagger UI   | [api.furstock.trade/docs](https://api.furstock.trade/docs)                                                        |
| 데이터 형식  | JSON(UTF-8), 필드명 camelCase                                                                                     |
| 요청 한도    | API 키당 초당 10회(순간 20회)                                                                                     |

## 5분 퀵스타트

### 1. API 키 발급

[프로필 → OpenAPI 탭](https://furstock.trade/profile?tab=api)에서 **새 키 발급**을 누르면 `client_id`와 `client_secret`이 나와요. `client_secret`은 **그때 한 번만** 보이니 바로 안전한 곳에 복사해 두세요.

### 2. access token 받기

```bash
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
```

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

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

### 3. 내 잔고 조회

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

```json
{ "cashBalance": 300000 }
```

### 4. 첫 주문

```bash
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`면 체결된 거예요. 자세한 내용은 [주문](/developers/orders)을 보세요.

## 할 수 있는 것

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

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

## AI 에이전트로 봇 만들기

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

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

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

## 이용 수칙

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