OpenAPI 스펙으로 AI 에이전트 도구를 만들고 마켓플레이스에 배포하세요
외부 스킬이란?
외부 스킬은 여러분의 API를 RainbowStock AI 에이전트의 도구로 연결하는 시스템입니다. OpenAPI 스펙만 등록하면, 파서가 자동으로 에이전트 도구를 생성합니다. 사용자가 채팅으로 질문하면 AI가 적절한 시점에 여러분의 API를 호출합니다.
강화학습 모델, 퀀트 전략, 뉴스 분석, 차트 패턴 인식 등 — HTTP API로 제공할 수 있는 모든 것이 스킬이 될 수 있습니다.
API 개발
여러분의 서버
OpenAPI 스펙
스펙 등록
파서 변환
도구 자동 생성
AI 호출
채팅에서 사용
OpenAPI 스펙 작성법
스펙은 JSON 형식으로 작성하며, 직접 입력하거나 URL로 불러올 수 있습니다. 각 operation이 하나의 에이전트 도구가 됩니다.
| 필드 | 필수 | 설명 |
|---|---|---|
| openapi | "3.0.3" 또는 "3.1.0" | |
| info.title | 스킬 이름으로 사용됨 | |
| info.description | 권장 | 마켓플레이스 설명에 표시 |
| servers[0].url | API 베이스 URL (HTTPS 필수) | |
| paths | API 엔드포인트 (최대 20개 operation) | |
| operationId | 권장 | 도구 이름이 됨 (권장) |
| summary | 권장 | AI에게 보여지는 도구 설명 (권장) |
| parameters / requestBody | 권장 | 도구 입력 파라미터로 변환 |
예시 스펙
아래 예시는 RainbowStock에서 실제 운영 중인 공식 스킬입니다. 스펙을 복사하여 등록 페이지에서 바로 테스트해볼 수 있습니다.
GET배당 분석 API실제 작동
종목별 배당수익률, 연속배당 연수, 3년 CAGR, 고배당 TOP 종목을 제공합니다. pykrx 라이브러리로 KRX 배당 데이터를 조회합니다.
{
"openapi": "3.0.3",
"info": {
"title": "배당 분석 API",
"description": "한국 주식 배당 분석 및 캘린더 서비스. 배당수익률, 배당성장률, 배당성향, 연속배당 연수 등 제공.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://rainbowstock.net/api/skill-api"
}
],
"paths": {
"/dividend/{ticker}": {
"get": {
"operationId": "getDividendAnalysis",
"summary": "종목 배당 상세 분석 조회",
"parameters": [
{
"name": "ticker",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "종목 코드 (예: 005930)"
}
],
"responses": {
"200": {
"description": "배당 분석 결과",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string"
},
"name": {
"type": "string"
},
"dividend_per_share": {
"type": "number",
"description": "주당배당금 (원)"
},
"dividend_yield": {
"type": "number",
"description": "배당수익률 (%)"
},
"consecutive_years": {
"type": "integer",
"description": "연속배당 연수"
},
"dividend_growth_3y": {
"type": "number",
"description": "3년 배당성장률 CAGR (%)"
},
"history": {
"type": "array",
"description": "연도별 배당 이력",
"items": {
"type": "object",
"properties": {
"year": {
"type": "integer"
},
"dps": {
"type": "number"
},
"yield": {
"type": "number"
}
}
}
}
}
}
}
}
}
}
}
},
"/dividend/top": {
"get": {
"operationId": "getTopDividendStocks",
"summary": "고배당 종목 TOP N 조회",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"default": 10
},
"description": "조회할 종목 수"
}
],
"responses": {
"200": {
"description": "고배당 종목 목록",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ticker": {
"type": "string"
},
"name": {
"type": "string"
},
"dividend_yield": {
"type": "number"
},
"dividend_per_share": {
"type": "number"
}
}
}
}
}
}
}
}
}
}
}
}GET소셜 센티먼트 API실제 작동
네이버 종목토론방 게시글을 크롤링하여 감성 분석을 수행합니다. 긍정/부정 비율, 감성 점수(-1~1), 빈출 키워드를 제공합니다.
{
"openapi": "3.0.3",
"info": {
"title": "소셜 센티먼트 API",
"description": "네이버 종목토론방 기반 개인투자자 심리 분석. 감성 점수, 언급량, 키워드 분석 제공.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://rainbowstock.net/api/skill-api"
}
],
"paths": {
"/social/{ticker}": {
"get": {
"operationId": "getSocialSentiment",
"summary": "종목 소셜 감성 분석 (네이버 종목토론방)",
"parameters": [
{
"name": "ticker",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "종목 코드 (예: 005930)"
},
{
"name": "pages",
"in": "query",
"schema": {
"type": "integer",
"default": 3,
"minimum": 1,
"maximum": 10
},
"description": "분석할 페이지 수"
}
],
"responses": {
"200": {
"description": "감성 분석 결과",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ticker": {
"type": "string"
},
"name": {
"type": "string"
},
"sentiment_score": {
"type": "number",
"description": "-1.0(매우 부정) ~ 1.0(매우 긍정)"
},
"sentiment_label": {
"type": "string"
},
"post_count": {
"type": "integer",
"description": "분석한 게시글 수"
},
"bullish_ratio": {
"type": "number",
"description": "긍정 비율 (0~1)"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "빈출 키워드 TOP 10"
},
"summary": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}GET경제 이벤트 캘린더 API실제 작동
FOMC, 한은 금통위, CPI, 고용지표 등 글로벌 경제 이벤트 일정을 제공합니다. 종목별 영향 분석으로 어떤 이벤트가 특정 종목에 영향을 주는지 확인할 수 있습니다.
{
"openapi": "3.0.3",
"info": {
"title": "경제 이벤트 캘린더 API",
"description": "주요 경제 이벤트 일정 및 시장 영향 분석. FOMC, 금통위, CPI, 고용지표 등 주요 이벤트 추적.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://rainbowstock.net/api/skill-api"
}
],
"paths": {
"/events": {
"get": {
"operationId": "getEconomicEvents",
"summary": "향후 주요 경제 이벤트 캘린더 조회",
"parameters": [
{
"name": "days",
"in": "query",
"schema": {
"type": "integer",
"default": 14
},
"description": "조회 기간 (일)"
},
{
"name": "country",
"in": "query",
"schema": {
"type": "string",
"enum": [
"KR",
"US",
"JP",
"EU",
"CN"
]
},
"description": "국가 필터"
},
{
"name": "importance",
"in": "query",
"schema": {
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"description": "중요도 필터"
}
],
"responses": {
"200": {
"description": "경제 이벤트 목록",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"country": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"importance": {
"type": "string"
},
"impact_sectors": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
},
"/events/impact/{ticker}": {
"get": {
"operationId": "getEventImpact",
"summary": "종목별 영향 이벤트 분석",
"parameters": [
{
"name": "ticker",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "종목 코드 (예: 005930)"
},
{
"name": "days",
"in": "query",
"schema": {
"type": "integer",
"default": 30
},
"description": "조회 기간 (일)"
}
],
"responses": {
"200": {
"description": "종목 영향 분석",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"event_name": {
"type": "string"
},
"ticker": {
"type": "string"
},
"correlation": {
"type": "string"
},
"description": {
"type": "string"
},
"historical_impact": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
}인증 방식
RainbowStock 프록시가 인증 헤더를 자동 주입합니다. 사용자에게 크레덴셜이 노출되지 않습니다.
none
인증 불필요. 공개 API에 적합합니다.
api_key
헤더 또는 쿼리로 API 키 전달
{"name": "X-API-Key", "in": "header"}bearer
Authorization: Bearer 토큰 방식
{"token": "your-token"}basic
HTTP Basic 인증 (username:password)
{"username": "...", "password": "..."}개발자가 기본 크레덴셜을 설정하며, 사용자가 개별 크레덴셜을 등록할 수도 있습니다. 모든 크레덴셜은 AES-256-GCM으로 암호화되어 저장됩니다.
등록 프로세스
API 개발 & OpenAPI 스펙 준비
HTTPS로 접근 가능한 API 서버를 준비하고, OpenAPI 3.x JSON 스펙을 작성합니다.
스킬 등록 신청
스킬 등록 페이지에서 스펙을 입력하고, 카테고리·인증·과금 설정을 완료합니다.
자동 검증
OpenAPI 파서가 스펙을 분석하여 도구를 자동 생성합니다. 스펙 오류가 있으면 즉시 안내됩니다.
관리자 심사
보안 검토, API 헬스체크, 콘텐츠 적절성을 확인합니다. 보통 1~3 영업일 소요됩니다.
마켓플레이스 공개
승인되면 마켓에 공개됩니다. 사용자가 구독하면 AI 채팅에서 바로 사용할 수 있습니다.
크레딧 & 과금
무료 스킬
호출당 크레딧 비용 없음. 커뮤니티 도구, 오픈소스 프로젝트에 적합합니다.
유료 스킬
호출당 1~1,000 크레딧. 고급 분석, ML 모델 등 운영 비용이 있는 서비스에 적합합니다.
개발자 수익 분배
유료 스킬이 호출될 때마다 크레딧의 70%가 개발자에게, 30%는 플랫폼 수수료로 배분됩니다. 수익은 크레딧으로 즉시 적립되며 "내 스킬" 탭에서 확인할 수 있습니다.
베스트 프랙티스
- HTTPS 필수 — HTTP는 지원되지 않습니다. 모든 API는 TLS로 보호되어야 합니다.
- 응답은 JSON으로 — AI 에이전트가 응답을 직접 읽으므로, 명확한 필드명의 JSON을 반환하세요.
- 응답 크기 4KB 이하 권장 — 에이전트 컨텍스트 제한이 있으므로 핵심 데이터만 포함하세요.
- description을 충실히 — 모든 파라미터와 응답 필드에 description을 작성하면 AI가 더 정확하게 사용합니다.
- operationId는 짧고 명확하게 — AI에게 보이는 도구 이름이 됩니다. getStockSignal처럼 동작을 나타내세요.
- summary는 행동 지향적으로 — "종목 매매 시그널 조회"처럼 AI가 언제 호출할지 판단할 수 있게 작성하세요.
- 에러 처리 — 4xx/5xx 상태 코드와 함께 JSON 에러 바디를 반환하세요.
- 서버 측 레이트리밋 — RainbowStock 레이트리밋 외에, 자체 서버에서도 보호 장치를 두세요.
MCP 서버 등록
OpenAPI 스펙 외에 MCP(Model Context Protocol) 서버도 외부 스킬로 등록할 수 있습니다. MCP URL을 입력하면 서버에서 tools/list를 자동 호출하여 도구를 추출합니다.
등록 방법
- 스킬 등록 페이지에서 MCP 서버 탭 선택
- MCP 엔드포인트 URL 입력 (예:
https://your-server.vercel.app/api/mcp) - 이름, 카테고리, 과금 설정 후 등록
- 서버에서
tools/list호출 → 도구 자동 생성 - AI 에이전트가
tools/call로 자동 호출
MCP 서버 요구사항
- HTTPS 엔드포인트 (HTTP 미지원)
- JSON-RPC 2.0 프로토콜 (
tools/list,tools/call) - 최대 20개 도구
- 응답 시간 60초 이내
- Vercel, Cloudflare Workers, AWS Lambda 등 서버리스 호환
MCP 프로토콜 상세: modelcontextprotocol.io
자주 묻는 질문
Swagger 2.0 스펙도 지원하나요?
아니요. OpenAPI 3.0.x 또는 3.1.x만 지원합니다. Swagger 2.0 스펙은 swagger-converter 등의 도구로 변환 후 등록해 주세요.
YAML 형식을 지원하나요?
현재는 JSON만 지원합니다. YAML 스펙은 JSON으로 변환하여 등록해 주세요.
스펙 URL 방식은 어떻게 작동하나요?
등록 시점에 URL에서 스펙을 가져와 캐싱합니다. API가 변경되면 "스펙 새로고침" 버튼으로 업데이트할 수 있습니다.
API 호출 실패 시 크레딧이 차감되나요?
아니요. 2xx 성공 응답만 크레딧이 차감됩니다. 서버 오류나 타임아웃에는 차감되지 않습니다.
심사에 얼마나 걸리나요?
보통 1~3 영업일 내에 결과를 알려드립니다. 보안 검토, API 헬스체크, 콘텐츠 적절성을 확인합니다.
한 스킬에 여러 엔드포인트를 넣을 수 있나요?
네, 최대 20개의 operation(엔드포인트)까지 하나의 스킬로 등록할 수 있습니다.
MCP 서버도 등록할 수 있나요?
네. 스킬 등록 시 "MCP 서버" 탭을 선택하고 MCP 엔드포인트 URL을 입력하면 tools/list에서 도구를 자동 추출합니다.