# 대화 만들기
Source: https://morrowly.mintlify.app/api-reference/advisor/대화-만들기
/openapi.json post /v1/plans/{id}/advisor/threads
필요한 권한: `moro:write`
# 대화 목록
Source: https://morrowly.mintlify.app/api-reference/advisor/대화-목록
/openapi.json get /v1/plans/{id}/advisor/threads
필요한 권한: `moro:read`
# 대화 보기
Source: https://morrowly.mintlify.app/api-reference/advisor/대화-보기
/openapi.json get /v1/plans/{id}/advisor/threads/{threadId}
필요한 권한: `moro:read`
# 대화 지우기
Source: https://morrowly.mintlify.app/api-reference/advisor/대화-지우기
/openapi.json delete /v1/plans/{id}/advisor/threads/{threadId}
필요한 권한: `moro:write`
# 모로 모델·사용량
Source: https://morrowly.mintlify.app/api-reference/advisor/모로-모델·사용량
/openapi.json get /v1/advisor
필요한 권한: `moro:read`
# 모로 알림
Source: https://morrowly.mintlify.app/api-reference/advisor/모로-알림
/openapi.json get /v1/plans/{id}/advisor/alerts
필요한 권한: `moro:read`
# 적용 되돌리기
Source: https://morrowly.mintlify.app/api-reference/advisor/적용-되돌리기
/openapi.json post /v1/plans/{id}/advisor/threads/{threadId}/messages/{messageId}/undo
필요한 권한: `moro:write` + `plans:write` + `finances:write`
# 제안 모두 적용
Source: https://morrowly.mintlify.app/api-reference/advisor/제안-모두-적용
/openapi.json post /v1/plans/{id}/advisor/threads/{threadId}/messages/{messageId}/apply-all
필요한 권한: `moro:write` + `plans:write` + `finances:write`
# 제안 적용
Source: https://morrowly.mintlify.app/api-reference/advisor/제안-적용
/openapi.json post /v1/plans/{id}/advisor/threads/{threadId}/messages/{messageId}/proposals/{index}/apply
필요한 권한: `moro:write` + `plans:write` + `finances:write`
# 질문하기(스트림)
Source: https://morrowly.mintlify.app/api-reference/advisor/질문하기스트림
/openapi.json post /v1/plans/{id}/advisor/threads/{threadId}/messages
필요한 권한: `moro:write`
# 수입이 끊기면 버티는 기간
Source: https://morrowly.mintlify.app/api-reference/finances/수입이-끊기면-버티는-기간
/openapi.json post /v1/finances/safety-net
필요한 권한: `finances:read`
# 순자산 기록 넣기
Source: https://morrowly.mintlify.app/api-reference/finances/순자산-기록-넣기
/openapi.json put /v1/finances/history/{date}
필요한 권한: `finances:write`
# 순자산 기록 보기
Source: https://morrowly.mintlify.app/api-reference/finances/순자산-기록-보기
/openapi.json get /v1/finances/history
필요한 권한: `finances:read`
# 순자산 기록 지우기
Source: https://morrowly.mintlify.app/api-reference/finances/순자산-기록-지우기
/openapi.json delete /v1/finances/history/{date}
필요한 권한: `finances:write`
# 이번 달 수입·지출 계산
Source: https://morrowly.mintlify.app/api-reference/finances/이번-달-수입·지출-계산
/openapi.json post /v1/finances/this-month
필요한 권한: `finances:read`
# 현재 재무 보기
Source: https://morrowly.mintlify.app/api-reference/finances/현재-재무-보기
/openapi.json get /v1/finances
필요한 권한: `finances:read`
# 현재 재무 저장
Source: https://morrowly.mintlify.app/api-reference/finances/현재-재무-저장
/openapi.json put /v1/finances
필요한 권한: `finances:write`
# 상태 확인
Source: https://morrowly.mintlify.app/api-reference/health/상태-확인
/openapi.json get /v1/health
권한 없이 어느 토큰으로나 부릅니다.
# API 개요
Source: https://morrowly.mintlify.app/api-reference/introduction
기본 주소, 인증, 응답 모양, 오류
`https://api.morrowly.app/v1`
`Authorization: Bearer` 헤더에 **API 토큰**
## 인증
모든 요청에 토큰이 필요합니다. 토큰이 없거나 틀리거나 만료되면 401, 권한이 모자라면 403 입니다.
```bash theme={null}
curl https://api.morrowly.app/v1/finances \
-H "Authorization: Bearer $MORROWLY_TOKEN"
```
## 응답 모양
성공하면 `result` 가 `SUCCESS` 이고 값은 `data` 에 있습니다.
```json theme={null}
{ "result": "SUCCESS", "data": { "…": "…" }, "error": null }
```
실패하면 `result` 가 `ERROR` 이고 `error` 에 코드와 문구가 있습니다.
```json theme={null}
{ "result": "ERROR", "data": null, "error": { "code": "E404", "message": "Not found.", "data": null } }
```
## 오류
| 상태 | 코드 | 뜻 |
| - | - | - |
| 400 | `E400` | 요청이 잘못됨. `error.data` 에 이유 |
| 401 | | 토큰이 없거나 틀리거나 만료됨(본문 없음) |
| 402 | `E402` | 요금제가 필요한 기능 |
| 403 | | 권한이 모자라거나 토큰으로 쓸 수 없는 경로(본문 없음) |
| 404 | `E404` | 없거나 이 가구의 것이 아님 |
| 412 | `E412` | 읽은 뒤 다른 곳에서 바뀜. 다시 읽고 고칩니다 |
| 429 | `E429` | 모로의 이번 달 사용 한도를 다 씀 |
| 503 | `E503` | 실거래가 서버 등 바깥 서비스에 닿지 못함. `error.data` 에 이유 |
| 500 | `E500` | 서버 오류 |
# 고친 플랜의 전망(저장 안 함)
Source: https://morrowly.mintlify.app/api-reference/plans/고친-플랜의-전망저장-안-함
/openapi.json post /v1/plans/{id}/projection
필요한 권한: `plans:read`
# 몬테카를로
Source: https://morrowly.mintlify.app/api-reference/plans/몬테카를로
/openapi.json get /v1/plans/{id}/monte-carlo
필요한 권한: `plans:read`
# 몬테카를로 시행 하나
Source: https://morrowly.mintlify.app/api-reference/plans/몬테카를로-시행-하나
/openapi.json get /v1/plans/{id}/monte-carlo/trials/{n}
필요한 권한: `plans:read`
# 백테스트
Source: https://morrowly.mintlify.app/api-reference/plans/백테스트
/openapi.json get /v1/plans/{id}/backtest
필요한 권한: `plans:read`
# 백테스트 시작 연도 하나
Source: https://morrowly.mintlify.app/api-reference/plans/백테스트-시작-연도-하나
/openapi.json get /v1/plans/{id}/backtest/{startYear}
필요한 권한: `plans:read`
# 상속 전망
Source: https://morrowly.mintlify.app/api-reference/plans/상속-전망
/openapi.json get /v1/plans/{id}/estate
필요한 권한: `plans:read`
# 성공 확률 맞추기
Source: https://morrowly.mintlify.app/api-reference/plans/성공-확률-맞추기
/openapi.json get /v1/plans/{id}/monte-carlo/levers
필요한 권한: `plans:read`
# 연금계좌 전략
Source: https://morrowly.mintlify.app/api-reference/plans/연금계좌-전략
/openapi.json get /v1/plans/{id}/pension-strategy
필요한 권한: `plans:read`
# 전망
Source: https://morrowly.mintlify.app/api-reference/plans/전망
/openapi.json get /v1/plans/{id}/projection
필요한 권한: `plans:read`
# 전세 vs 월세 vs 매수
Source: https://morrowly.mintlify.app/api-reference/plans/전세-vs-월세-vs-매수
/openapi.json get /v1/plans/{id}/rent-vs-buy
필요한 권한: `plans:read`
# 집 살 시기·가격
Source: https://morrowly.mintlify.app/api-reference/plans/집-살-시기·가격
/openapi.json get /v1/plans/{id}/affordability
필요한 권한: `plans:read`
# 집 살 시기·가격의 성공 확률(스트림)
Source: https://morrowly.mintlify.app/api-reference/plans/집-살-시기·가격의-성공-확률스트림
/openapi.json get /v1/plans/{id}/affordability/stream
필요한 권한: `plans:read`
# 최적화
Source: https://morrowly.mintlify.app/api-reference/plans/최적화
/openapi.json get /v1/plans/{id}/optimize
필요한 권한: `plans:read`
# 최적화 적용
Source: https://morrowly.mintlify.app/api-reference/plans/최적화-적용
/openapi.json post /v1/plans/{id}/optimize/apply
필요한 권한: `plans:write` + `finances:write`
# 플랜 고치기
Source: https://morrowly.mintlify.app/api-reference/plans/플랜-고치기
/openapi.json put /v1/plans/{id}
필요한 권한: `plans:write`
# 플랜 만들기
Source: https://morrowly.mintlify.app/api-reference/plans/플랜-만들기
/openapi.json post /v1/plans
필요한 권한: `plans:write`
# 플랜 목록
Source: https://morrowly.mintlify.app/api-reference/plans/플랜-목록
/openapi.json get /v1/plans
필요한 권한: `plans:read`
# 플랜 보기
Source: https://morrowly.mintlify.app/api-reference/plans/플랜-보기
/openapi.json get /v1/plans/{id}
필요한 권한: `plans:read`
# 플랜 복제
Source: https://morrowly.mintlify.app/api-reference/plans/플랜-복제
/openapi.json post /v1/plans/{id}/clone
필요한 권한: `plans:write`
# 플랜 지우기
Source: https://morrowly.mintlify.app/api-reference/plans/플랜-지우기
/openapi.json delete /v1/plans/{id}
필요한 권한: `plans:write`
# 시군구 목록
Source: https://morrowly.mintlify.app/api-reference/real-estate/시군구-목록
/openapi.json get /v1/real-estate/regions
권한 없이 어느 토큰으로나 부릅니다.
# 아파트 실거래가 찾기
Source: https://morrowly.mintlify.app/api-reference/real-estate/아파트-실거래가-찾기
/openapi.json get /v1/real-estate/apartments
권한 없이 어느 토큰으로나 부릅니다.
# 계산(저장 안 함)
Source: https://morrowly.mintlify.app/api-reference/simulate/계산저장-안-함
/openapi.json post /v1/simulate
권한 없이 어느 토큰으로나 부릅니다.
# 전세 vs 월세 vs 매수(저장 안 함)
Source: https://morrowly.mintlify.app/api-reference/simulate/전세-vs-월세-vs-매수저장-안-함
/openapi.json post /v1/simulate/rent-vs-buy
권한 없이 어느 토큰으로나 부릅니다.
# API 토큰
Source: https://morrowly.mintlify.app/authentication
토큰은 비밀번호처럼 다루세요. 남에게 보여 주거나 브라우저에서 도는 코드, 공개 저장소, 로그에 넣지 마세요.
API 토큰은 **한** 가구에 묶입니다. 토큰으로 보낸 요청은 지금 화면에서 보는 가구가 아니라 토큰을 만든 가구를 읽고 고칩니다.
[Morrowly](https://my.morrowly.app) 설정 창의 **API 토큰**에서 **토큰 만들기**를 누릅니다. 가구 소유자만 보입니다.
* **이름**: 어디에 쓰는 토큰인지 알아볼 이름
* **만료**: 1일\~1년 또는 만료 없음
* **권한**: 자원마다 없음·읽기·쓰기
![]()
토큰(`morrowly_oat_…`)은 만든 직후 **한 번만** 보입니다. 바로 복사해 쓸 곳에 넣습니다.
```http theme={null}
Authorization: Bearer morrowly_oat_xxxxxxxxxxxxxxxxx
```
## 권한
권한은 자원마다 읽기(`:read`)와 쓰기(`:write`)이고, 쓰기는 읽기를 포함합니다. 경로마다 필요한 권한은 레퍼런스의 각 경로에 적혀 있습니다.
| 권한 | 읽기(`:read`) | 쓰기(`:write`) |
| - | - | - |
| `finances` | 현재 재무·순자산 기록 보기, 이번 달·안전망 계산 | 현재 재무 저장, 순자산 기록 고치기 |
| `plans` | 플랜 보기, 전망·분석 | 플랜 만들기·고치기·지우기(최적화 적용은 `finances:write` 도 필요) |
| `moro` | 알림·대화 보기 | 대화하기, 제안 적용·되돌리기(`plans:write`·`finances:write` 도 필요) |
* 계산·부동산·상태 확인처럼 가구 데이터가 아닌 경로는 권한 없이 어느 토큰으로나 부릅니다.
* 계산 결과에는 다른 자원이 비칩니다. `plans:read` 로도 전망의 순자산·현금이, `moro:read` 로도 모로가 보는 재무가 보입니다.
* 계정·가구·결제·토큰 관리는 토큰으로 할 수 없습니다(403).
## 관리
* 토큰 목록에서 마지막 사용 시각을 보고, 이름과 권한을 고치거나 폐기합니다.
* 다른 가구로 옮겨 가도 토큰은 만든 가구만 봅니다. 가구를 지우면 토큰도 지워집니다.
* 토큰이 새어 나갔다면 바로 폐기하고 새로 만드세요. 비밀 관리 방법은 [OWASP Secrets Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)를 참고합니다.
# API 변경 내역
Source: https://morrowly.mintlify.app/changelog/api
Morrowly API 에 생기고 바뀐 것을 날짜별로 남깁니다.
## 공개 API
* 가구의 [API 토큰](/authentication)으로 `https://api.morrowly.app/v1` 을 부릅니다. 권한은 `finances`·`plans`·`moro` 마다 읽기·쓰기입니다.
* 재무·플랜·플랜 분석·모로·계산·부동산 경로를 엽니다. 경로마다 필요한 권한은 [API 레퍼런스](/api-reference/introduction)에 있습니다.
# 제품 업데이트
Source: https://morrowly.mintlify.app/changelog/product
# 예제
Source: https://morrowly.mintlify.app/examples
curl·jq 로 바로 돌려 보는 작은 스크립트
모두 토큰을 환경 변수 `MORROWLY_TOKEN` 에 넣고 돌립니다. 필요한 권한만 고른 토큰을 쓰세요.
```bash theme={null}
export MORROWLY_TOKEN=morrowly_oat_...
```
## 월말 순자산 기록
권한: `finances:write`. 현재 재무를 자세히 고치지 않고 오늘의 합계만 순자산 기록에 남깁니다. 매달 말 cron 등으로 돌립니다.
```bash record.sh theme={null}
#!/usr/bin/env bash
# 사용: ./record.sh 현금 투자 부동산·보증금 부채 (원)
set -euo pipefail
curl -sf -X PUT "https://api.morrowly.app/v1/finances/history/$(date +%F)" \
-H "Authorization: Bearer $MORROWLY_TOKEN" -H "Content-Type: application/json" \
-d "{\"cash\":$1,\"investments\":$2,\"realAssets\":$3,\"liabilities\":$4}" | jq .data
```
## 플랜 나란히 보기
권한: `plans:read`. 가구의 플랜마다 끝 순자산·은퇴 때 순자산·경제적 자유 나이를 표로 봅니다.
```bash compare.sh theme={null}
#!/usr/bin/env bash
set -euo pipefail
API=https://api.morrowly.app/v1
auth=(-H "Authorization: Bearer $MORROWLY_TOKEN")
curl -sf "${auth[@]}" "$API/plans" | jq -r '.data[] | [.id, .name] | @tsv' |
while IFS=$'\t' read -r id name; do
curl -sf "${auth[@]}" "$API/plans/$id/projection" |
jq -r --arg name "$name" '.data.summary | [$name, .finalNetWorth, (.retirementNetWorth // "-"), (.fiAge // "-")] | @tsv'
done
```
## 저장하지 않고 바꿔 보기
권한: `plans:read`. 은퇴를 62세로 미루면 어떻게 되는지 저장 없이 계산합니다. 바꿀 것만 보냅니다([플랜 본문](/plans)).
```bash theme={null}
curl -sf -X POST "https://api.morrowly.app/v1/plans/$PLAN/projection" \
-H "Authorization: Bearer $MORROWLY_TOKEN" -H "Content-Type: application/json" \
-d '{"milestones":[{"id":"retirement","name":"은퇴","time":{"age":62}}]}' |
jq '.data.summary | {finalNetWorth, retirementNetWorth, fiAge}'
```
## 에이전트에게 맡기기
Claude Code·Codex 같은 에이전트는 이 문서와 토큰만 있으면 API 를 직접 부릅니다.
점검만 시킬 거면 `finances:read`·`plans:read` 만 고릅니다. 고치게 하려면 `:write` 를 더합니다.
에이전트를 띄우는 셸에서 `export MORROWLY_TOKEN=...` 합니다. 대화에 토큰을 붙여 넣지 마세요.
```text theme={null}
Morrowly API(https://api.morrowly.app/v1, 문서 https://docs.morrowly.app/llms-full.txt)를
$MORROWLY_TOKEN 으로 불러 우리 가구의 현재 재무와 플랜들을 읽고,
현금이 모자라는 달이 있는 플랜과 그 까닭을 알려 줘. 아무것도 저장하지 마.
```
# 현재 재무
Source: https://morrowly.mintlify.app/finances
지금 가진 현금·자산·부채·수입·지출. 모든 플랜의 시작 조건입니다.
현재 재무는 가구에 하나이고 모든 플랜이 여기서 시작합니다(시작 고정 플랜은 만든 날의 재무를 따로 둡니다).
금액은 원(정수), 비율은 연율 소수(`0.05` = 5%), 달은 `"YYYY-MM"` 입니다.
```json theme={null}
{
"birthMonth": "1991-05",
"cash": 50000000,
"assets": [{ "id": "etf", "name": "ETF", "type": "INVESTMENT", "value": 200000000, "annualRate": null }],
"liabilities": [{ "id": "loan1", "name": "전세대출", "principal": 100000000, "annualRate": 0.04, "remainingMonths": 24, "repayment": "BULLET" }],
"cashFlows": [
{ "id": "salary", "name": "월급", "type": "INCOME", "incomeKind": "SALARY", "monthlyAmount": 7000000, "start": "2026-10", "end": null },
{ "id": "living", "name": "생활비", "type": "EXPENSE", "monthlyAmount": 3500000, "start": "2026-10", "end": null }
],
"dependents": [{ "id": "spouse", "name": "배우자", "kind": "SPOUSE", "birthMonth": "1992-03" }]
}
```
* `birthMonth`: 본인 생년월. 비어 있으면 계산할 수 없어 전망이 400 입니다.
* `cash`: 운용 계좌. 모든 수입·지출·상환이 여기로 들어오고 나갑니다.
* `id` 는 직접 정합니다. 플랜 항목(`change`·`holding`·`transfer`)이 이 id 를 가리킵니다.
## 자산 `assets`
| `type` | 뜻 | `annualRate` 가 null 이면 |
| - | - | - |
| `INVESTMENT` | 주식·펀드·예금 등 투자 | 가정의 투자 수익률 |
| `PENSION_ACCOUNT` | 연금저축·IRP | 가정의 투자 수익률 |
| `RETIREMENT_PENSION` | 퇴직연금 DC | 가정의 투자 수익률 |
| `REAL_ESTATE` | 부동산 | 가정의 부동산 상승률 |
| `VEHICLE` | 자동차 | 연 −15% |
| `DEPOSIT` | 전세·월세 보증금 | 0 |
## 부채 `liabilities`
`repayment` 는 `ANNUITY`(원리금균등)·`EQUAL_PRINCIPAL`(원금균등)·`BULLET`(만기일시)·`DEPOSIT`(받은 보증금: 이자·상환 없이 집을 팔 때 돌려줌)입니다.
## 수입·지출 `cashFlows`
* `type` 은 `INCOME`·`EXPENSE` 입니다. `start`\~`end` 달(포함) 동안 매달이고, `end` 가 null 이면 끝까지입니다.
* 수입 `incomeKind`: `SALARY`(세전 급여, 엔진이 세금·보험료를 뗌)·`NET`(세후)·`BUSINESS`(사업소득)·`PUBLIC_PENSION`(국민연금).
* 지출 `expenseKind`(선택): `RENT`(월세)·`DONATION`(기부금). 연말정산 세액공제에 씁니다.
* `annualGrowth` 가 null 이면 수입은 가정의 소득 상승률, 지출은 물가 상승률로 매년 1월에 오릅니다.
## 명의 `owner`
자산·부채·수입에 `SELF`(기본)·`SPOUSE`·`JOINT` 를 줍니다. 투자·연금계좌와 수입은 `JOINT` 를 쓸 수 없고, `SPOUSE` 는 `dependents` 에 배우자(`kind: "SPOUSE"`)가 있어야 합니다.
## 부양가족 `dependents`
소득 없는 가족입니다. `kind` 는 `SPOUSE`(생년월 선택)·`CHILD`·`PARENT`(생년월 필수). 인적공제·자녀세액공제와 정책대출 심사에 씁니다.
## 저장과 순자산 기록
* `PUT /v1/finances` 는 전체를 바꿉니다. `GET` 응답의 `ETag` 를 `If-Match` 에 넣으면 그사이 바뀌었을 때 덮어쓰지 않고 412 입니다.
* 저장할 때마다 그날의 합계가 **순자산 기록**(`GET /v1/finances/history`)에 남습니다(같은 날은 마지막 값).
* 지난 기록은 `PUT /v1/finances/history/{YYYY-MM-DD}` 로 넣거나 고칩니다. 미래 날짜·음수는 400 입니다.
# Morrowly API
Source: https://morrowly.mintlify.app/introduction
가구의 재무·플랜을 화면 없이 읽고 고치고, 미래 자산을 계산합니다.
Morrowly 는 지금 자산·수입·지출과 앞으로의 계획(집 구매, 결혼, 출산, 이직, 은퇴)을 넣으면 미래 자산을 월 단위로 계산하는 서비스입니다.
API 를 쓰면 직접 만든 스크립트나 Claude Code·Codex 같은 에이전트가 화면에서 하는 일을 똑같이 합니다.
현재 재무를 읽고 저장하고, 순자산 기록을 고칩니다.
플랜을 만들고 고치고, 전망·몬테카를로·백테스트·최적화 결과를 받습니다.
AI 계산 도우미 모로와 대화하고 제안을 적용하거나 되돌립니다.
저장 없이 계산하고, 시군구·아파트 실거래가를 조회합니다.
## 빠른 시작
[Morrowly](https://my.morrowly.app) 설정 창의 **API 토큰**에서 토큰을 만듭니다. 토큰은 가구의 것이고 가구 소유자만 만들 수 있습니다.
자세한 내용은 [API 토큰](/authentication)을 봅니다.
`Authorization: Bearer` 헤더에 토큰을 실어 보냅니다.
```bash theme={null}
curl https://api.morrowly.app/v1/plans \
-H "Authorization: Bearer $MORROWLY_TOKEN"
```
[예제](/examples)를 돌려 보고, [API 레퍼런스](/api-reference/introduction)에서 경로마다 필요한 권한과 요청·응답 모양을 봅니다.
# 모로와 대화하기
Source: https://morrowly.mintlify.app/moro
AI 계산 도우미 모로에게 묻고, 받은 제안을 적용하거나 되돌립니다.
모로는 이 가구의 현재 재무와 플랜을 읽고, 계산 엔진으로 직접 계산해 답합니다. 플랜을 바꾸자고 할 때는 **제안**을 내고, 적용해야 저장됩니다.
대화·질문·제안 적용은 **맥스** 요금제가 필요합니다(없으면 402). 사용량 보기(`GET /v1/advisor`)와 알림(`advisor/alerts`)은 요금제 없이 됩니다.
## 순서
`GET /v1/advisor` 의 `models[].provider` 하나로 대화를 만듭니다. 대화는 플랜마다 여럿입니다.
```bash theme={null}
curl -X POST https://api.morrowly.app/v1/plans/$PLAN/advisor/threads \
-H "Authorization: Bearer $MORROWLY_TOKEN" -H "Content-Type: application/json" \
-d '{"provider":"OPENAI"}'
```
`question` 은 1\~2000자입니다. 답은 스트림으로 옵니다(아래).
```bash theme={null}
curl -N -X POST https://api.morrowly.app/v1/plans/$PLAN/advisor/threads/$THREAD/messages \
-H "Authorization: Bearer $MORROWLY_TOKEN" -H "Content-Type: application/json" \
-d '{"question":"은퇴를 2년 늦추면 순자산이 얼마나 달라져?"}'
```
답의 `proposals[index]` 를 `.../messages/{messageId}/proposals/{index}/apply` 로 적용합니다. 한 번에 다 적용하려면 `apply-all`, 마지막 적용을 되돌리려면 `undo` 입니다.
## 답 스트림
질문 응답은 [Vercel AI SDK UI 메시지 스트림](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol) v1 입니다(헤더 `x-vercel-ai-ui-message-stream: v1`). 줄마다 `data: {조각}` 이고 끝은 `data: [DONE]` 입니다.
| 조각 `type` | 뜻 |
| - | - |
| `start` · `finish` | 시작과 끝 |
| `reasoning-start/delta/end` | 생각 요약 |
| `tool-input-available` · `tool-output-available` | 엔진으로 계산한 것(도구 이름·입력·결과) |
| `text-start/delta/end` | 답 글 |
| `data-exchange` | 저장된 질문·답과 제안(`data` 가 대화 한 번) |
| `error` | 답하다 실패함(`errorText`) |
* 없는 대화(404)·빈 질문(400)·이번 달 한도(429)는 스트림이 시작되기 전에 상태 코드로 옵니다.
* 연결을 끊어도 모로는 끝까지 답해 저장합니다. 나중에 `GET .../threads/{threadId}` 로 읽습니다.
* 브라우저나 Node 에서는 AI SDK 의 `useChat`·`readUIMessageStream` 으로 읽을 수 있습니다.
## 제안
`data-exchange` 와 대화 보기의 `proposals[]` 하나는 플랜을 어떻게 바꿀지와 그 결과입니다.
* `remove`·`upsert`·`milestones`: 뺄 항목 id, 넣거나 바꿀 항목, 바꿀 이정표([플랜 본문](/plans)과 같은 모양). `finances`: 현재 재무 고치기(없으면 null).
* `before`·`after`: 바꾸기 전과 후의 `finalNetWorth`·`fiAge`·`minCash`·`firstShortfallMonth`·`retirementNetWorth`.
* 적용하면 플랜(과 재무)이 저장됩니다. 제안을 받은 뒤 플랜이나 재무가 다른 곳에서 바뀌었으면 412 입니다.
## 사용량
`GET /v1/advisor` 의 `usedUsd`·`limitUsd` 가 가구의 이번 달 사용량과 한도입니다. 한도를 다 쓰면 다음 달까지 질문이 429 입니다.
# 플랜 본문
Source: https://morrowly.mintlify.app/plans
이정표와 항목으로 플랜을 쓰고, 덮어쓰지 않게 고칩니다.
플랜은 **이정표**(언제)와 **항목**(무엇이 얼마나, 언제부터 언제까지) 두 가지로 씁니다.
지금 가진 자산·부채·수입·지출은 플랜이 아니라 가구의 **현재 재무**(`GET /v1/finances`)에 있고 모든 플랜이 같이 씁니다.
플랜 항목은 앞으로 생기는 것과, 현재 재무에 대한 계획(팔기·재계약·금액 바꾸기)입니다.
## 고치는 순서
`GET /v1/plans/{id}` 로 플랜 전체를 받습니다. `revision` 은 지금 판의 지문입니다.
`POST /v1/plans/{id}/projection` 에 바꿀 것만(`remove`·`upsert`·`milestones`) 보내면 저장하지 않고 전망을 계산합니다.
받은 본문을 고쳐 `revision` 과 함께 `PUT /v1/plans/{id}` 로 보냅니다. 그사이 다른 곳(화면·다른 사람·다른 토큰)에서 저장했으면 덮어쓰지 않고 **412** 입니다. 다시 읽고 고칩니다. PUT 은 전체를 바꿉니다. 빠뜨린 `milestones`·`items` 는 빈 목록, `monteCarlo` 는 기본값으로 저장됩니다.
현재 재무도 같습니다. `GET /v1/finances` 응답의 `ETag` 를 `PUT /v1/finances` 의 `If-Match` 에 넣으면 그사이 바뀌었을 때 412 입니다(넣지 않으면 그냥 덮어씁니다).
## 시기 `Time`
항목의 시점(`at`)·시작(`start`)·끝(`end`)은 모두 셋 중 하나로 씁니다.
```json theme={null}
{ "month": "2029-12" }
{ "age": 60, "who": "SPOUSE" }
{ "milestone": "retirement", "offset": -12 }
```
* `month`: 그 달. `age`: 그 나이가 되는 생일 달(`who` 가 `SPOUSE` 면 배우자 나이). `milestone`: 이정표 달 ± `offset` 개월.
* 시작·시점은 그 달부터입니다. **끝**은 달이면 그 달까지, 나이·이정표면 **그 전 달까지**입니다(은퇴하면 그달부터 월급이 끊기는 것과 같습니다). 비우면 플랜 끝까지입니다.
* 이정표에 묶은 항목은 이정표를 옮기면 따라 움직입니다.
## 이정표
이정표는 계산이 달라지는 정해진 시점뿐이고, id 가 정해져 있습니다. 다른 id 는 400 입니다.
| id | 뜻 |
| - | - |
| `retirement` | 본인 은퇴 |
| `retirement-spouse` | 배우자 은퇴 |
| `national-pension` | 본인 국민연금 받기 시작 |
| `national-pension-spouse` | 배우자 국민연금 받기 시작 |
이정표의 시기는 달 또는 나이입니다(`{ "id": "retirement", "name": "은퇴", "time": { "age": 60 } }`).
## 항목
모든 항목은 `id`(플랜 안에서 겹치지 않게 직접 정함)·`kind`·`name` 과 종류별 필드를 가집니다. 금액은 원이고 월 금액은 `monthlyAmount` 입니다. 필드는 레퍼런스의 스키마에 있습니다.
| `kind` | 뜻 |
| - | - |
| `income` | 이 플랜의 수입(부업·새 직장·연금) |
| `expense` | 이 플랜의 지출(부모님 생활비·기부) |
| `change` | 현재 재무의 수입·지출을 어느 달부터 바꾸기(이직·퇴사, 0 이면 끝) |
| `lumpSum` | 한 번 들어오거나(+) 나가는(−) 목돈 |
| `housing` | 주거: 자가(`OWN`)·전세(`JEONSE`)·월세(`RENT`)·갭(`GAP`) |
| `asset` | 그 밖의 자산 사기(자동차 등) |
| `holding` | 지금 가진 자산의 계획(팔기·재계약·주택연금·배당 받기) |
| `child` | 자녀(출생, 월 양육비) |
| `severance` | 퇴직금 |
| `gift` | 증여 |
| `transfer` | 자산 옮기기(예금으로, ISA → 연금계좌) |
* `change`·`holding`·`transfer` 는 현재 재무의 수입·지출·자산 `id` 를 가리킵니다.
* 항목을 지우지 않고 계산에서만 빼려면 그 `id` 를 플랜의 `off` 에 넣습니다. 끈 수입·자산을 가리키는 `change`·`transfer` 도 함께 빠집니다.
* 저장할 때 400: id 가 겹칠 때, 없는 이정표·수입·지출·자산을 가리킬 때, 한 달도 없는 항목(끝이 시작보다 앞)일 때.
## 결과에서 항목 찾기
전망 응답의 이벤트 이름표는 항목 id 입니다. 한 항목에서 여러 일이 생기면 `"항목 id:부분"` 으로 가립니다(예: `home` 을 사면 `home`, 팔면 `home:sale`, 재계약하면 `home:renew`). 그래서 응답의 숫자를 항목으로 거슬러 찾을 수 있습니다.
# 전망 읽기
Source: https://morrowly.mintlify.app/projection
플랜을 달마다 계산한 결과의 모양과 뜻
`GET /v1/plans/{id}/projection` 은 현재 재무에서 시작해 플랜 끝까지 **달마다** 계산한 결과를 줍니다. 저장 없이 고친 플랜을 계산하는 `POST /v1/plans/{id}/projection`, 플랜 없이 엔진 입력으로 계산하는 `POST /v1/simulate` 도 같은 모양입니다.
같은 입력은 늘 같은 결과입니다. 금액은 원(반올림)입니다.
```json theme={null}
{
"months": [
{
"month": "2026-10", "age": 35,
"income": 7000000, "expense": 3500000, "debtPayment": 1432246,
"cash": 12000000, "assets": { "etf": 203000000 }, "liabilities": { "loan1": 299567754 },
"totalAssets": 215000000, "totalLiabilities": 299567754, "netWorth": -84567754, "shortfall": false,
"flows": { "income": { "salary": 7000000 }, "expense": { "living": 3500000 }, "debt": { "loan1": 1432246 },
"saved": { "etf": 2067754 }, "withdrawn": {}, "sold": {}, "events": {} }
}
],
"summary": {
"netWorthByAge": { "40": 500000000, "50": 1300000000, "60": 2700000000 },
"finalNetWorth": 3000000000, "minCash": 12000000, "firstShortfallMonth": null, "fiAge": 51
}
}
```
## 달마다 `months`
* `age`: 그 달의 만 나이. `netWorth` = `totalAssets` − `totalLiabilities`. `tax`: 그 달 세금·보험료(`taxes` 는 종류별).
* `assets`·`liabilities`: 자산·부채 id 마다 그 달 말 잔액.
* `shortfall`: 투자 자산을 다 꺼내도 현금이 모자란 달. 오류가 아니라 표시입니다.
* `flows`: 그 달 현금이 오간 곳(0 은 빠짐).
* `income`·`expense`: 수입·지출 id 마다. 양육비·월세는 `{항목 id}-child`·`{항목 id}-rent`, 출산·양육 지원금은 `child-benefits`.
* `debt`: 대출 id 마다 상환액. `saved`: 자산에 넣은 돈(적립·남는 돈 옮기기).
* `withdrawn`: 투자 자산에서 꺼낸 돈. 그중 현금이 모자라 판 돈은 `sold` 에도 있습니다.
* `events`: 항목이 그 달 만든 현금(+ 목돈·퇴직금·매도 대금, − 매수·증여). 키는 [항목 이름표](/plans#결과에서-항목-찾기)입니다.
## 요약 `summary`
| 필드 | 뜻 |
| - | - |
| `netWorthByAge` | 생일 달의 순자산(나이 → 금액) |
| `finalNetWorth` | 플랜 끝 순자산 |
| `retirementNetWorth` | 은퇴 달 순자산 |
| `minCash` | 가장 적었던 현금 |
| `firstShortfallMonth` | 처음 현금이 모자란 달. 없으면 null |
| `fiAge` | (현금 + 투자) × 안전 인출률 ÷ 12 가 그 달 지출 + 상환 이상이 되는 첫 나이. 없으면 null |
## 그 밖의 결과
* `taxYears`: 해마다 연말정산(급여 받는 사람별 공제·세액·한계세율).
* `loanChecks`: 지역을 아는 집 구매 대출의 규제 한도(LTV·DSR 등)와 실제로 빌린 원금.
* `warnings`: 계산하며 걸린 주의할 점(`event` 는 항목 이름표).
필드 전체는 레퍼런스의 스키마에 있습니다.
용어(순자산, 경제적 자유 나이, 스트레스 DSR 등)의 뜻은 [용어 사전](https://morrowly.app/glossary)에 있습니다.
## 요금제가 필요한 분석
전망·몬테카를로·백테스트는 요금제 없이 됩니다. 아래는 **프로페셔널** 이상이 필요하고, 없으면 402 입니다.
* 집 살 시기·가격(`affordability`), 전세 vs 월세 vs 매수(`rent-vs-buy`), 상속 전망(`estate`), 연금계좌 전략(`pension-strategy`), 최적화(`optimize`·`optimize/apply`), 성공 확률 맞추기(`monte-carlo/levers`)
# 보안과 취약점 신고
Source: https://morrowly.mintlify.app/security
## 토큰이 새어 나갔다면
1. [Morrowly](https://my.morrowly.app) 설정 창의 **API 토큰**에서 그 토큰을 바로 **폐기**합니다. 폐기한 토큰은 그 즉시 401 입니다.
2. 목록의 **최근 사용** 시각으로 쓰인 적이 있는지 봅니다.
3. 필요한 권한만 고른 새 토큰을 만들어 바꿔 넣습니다.
토큰은 가구 소유자만 폐기할 수 있습니다. 토큰은 Morrowly 서버에 해시로만 남아 Morrowly 도 원문을 볼 수 없습니다.
## 취약점 신고
취약점을 찾았다면 [info@morrowly.app](mailto:info@morrowly.app) 으로 알려 주세요. 다음을 적어 주면 빨리 확인할 수 있습니다.
* 문제와 그 영향
* 다시 해 볼 수 있는 단계
* 환경(브라우저·OS·도구 버전)
* 있다면 확인용 코드
받으면 확인했다고 답장하고, 고치는 동안 진행을 알려 드립니다.
## 특히 보고 싶은 것
* 인증 우회, 권한 상승(토큰 권한 밖의 경로나 다른 가구의 데이터에 닿기)
* 개인정보·재무 데이터 노출
## 대상
* [https://my.morrowly.app](https://my.morrowly.app)
* [https://api.morrowly.app](https://api.morrowly.app)
* [https://morrowly.app](https://morrowly.app)
## 대상이 아닌 것
* 자동 스캔, 서비스 거부(DoS), 과도한 요청
* 사회공학, 기기에 직접 손대야 하는 공격
* 실제로 써먹을 수 없는 이론상의 공격
## 조사할 때 지켜 주세요
* 내 계정과 내 가구로만 시험합니다.
* 내 것이 아닌 데이터는 보거나 고치거나 지우거나 저장하지 않습니다.
* 고치기 전까지 내용을 공개하지 않습니다.
# 지원
Source: https://morrowly.mintlify.app/support
## 문서
먼저 이 문서와 [사용 가이드](https://morrowly.app/guide)를 찾아보세요. 재무·플랜·모로는 화면에서 하는 일과 API 가 같으니, 화면 설명이 API 를 쓸 때도 도움이 됩니다.
## 앱에서 의견 보내기
[Morrowly](https://my.morrowly.app) 넓은 화면의 사이드바 아래 **의견 보내기**로 불편한 점이나 바라는 기능을 보냅니다. 보던 화면 주소가 함께 가고, 답은 로그인한 이메일로 받습니다.
## 이메일
[info@morrowly.app](mailto:info@morrowly.app) 로 보냅니다. API 문의라면 부른 경로·메서드, 받은 상태 코드와 `error` 본문, 보낸 시각을 함께 적어 주세요. **토큰은 적지 마세요.**