QUICKSTART

4단계로 연결하기

Quickstart

5분 안에 처음부터 첫 성공 호출까지. 아래에는 원시 curl, Claude 도구 사용, OpenAI 함수 호출, 그리고 에러 처리 패턴이 있습니다.

OpenAPI 기술 가져오기

한 번의 GET이 모든 엔드포인트의 기계 판독 가능한 기술을 반환합니다. 어떤 LLM이든 이로부터 스스로를 기술하고 올바른 호출을 구성할 수 있습니다.

# 拉取完整 OpenAPI 3.1 描述
curl -s https://api.fstar.io/openapi.json | jq '.info.version'
# => "1.0.0"

# 或直接读 LLM 友好的精简地图
curl -s https://api.fstar.io/llms.txt

에이전트 프레임워크에 넘기기

openapi.json을 Claude 도구 정의나 OpenAI 함수 정의로 변환합니다. 대부분의 프레임워크는 OpenAPI에서 곧바로 도구 스키마를 도출할 수 있습니다.

TYPESCRIPT

// Claude tool use — 用 OpenAPI 当工具定义
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

const spec = await (await fetch("https://api.fstar.io/openapi.json")).json();

const msg = await client.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  tools: [{
    name: "fstar_get",
    description: "GET any F-Star API path, e.g. /v1/funds/qdfi/nav",
    input_schema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
    },
  }],
  messages: [{ role: "user", content: "What is QDFI's current NAV?" }],
});

읽기 전용 쿼리 발행하기

에이전트에게 "QDFI의 현재 NAV는?"이라고 물으면 — GET /v1/funds/qdfi/nav를 발행하고 반환된 JSON을 설명해야 합니다.

PYTHON

# OpenAI function calling
from openai import OpenAI
import requests, json

client = OpenAI()
tools = [{
  "type": "function",
  "function": {
    "name": "fstar_get",
    "description": "GET an F-Star API path, e.g. /v1/funds/qdfi/nav",
    "parameters": {
      "type": "object",
      "properties": {"path": {"type": "string"}},
      "required": ["path"],
    },
  },
}]

# When the model calls fstar_get(path="/v1/funds/qdfi/nav"):
def fstar_get(path):
    return requests.get("https://api.fstar.io" + path, timeout=10).json()

에러와 레이트 리밋 처리하기

모든 에러는 application/problem+json입니다. 429일 때는 Retry-After를 읽고 백오프하세요. If-None-Match를 보내 ETag로 저렴한 304를 활용하세요.

# 错误是 RFC 7807 application/problem+json
curl -s https://api.fstar.io/v1/funds/nope | jq
# {
#   "type": "https://fstar.io/problems/not-found",
#   "title": "Not Found",
#   "status": 404,
#   "detail": "fund \"nope\" not registered; see /v1/funds",
#   "instance": "/v1/funds/nope"
# }

# 限速 429 时读 Retry-After 退避；带 ETag 拿 304 省流量
curl -s -H 'If-None-Match: "abc123"' -D - https://api.fstar.io/v1/funds/qdfi/nav -o /dev/null

MCP

MCP 서버로 마운트하기

Claude Desktop / Cursor 및 기타 MCP 클라이언트가 F-Star API를 직접 호출하길 원하시나요? OpenAPI를 범용 OpenAPI→MCP 브리지(예: openapi-mcp-server)로 감싸면 — 접착 코드가 필요 없습니다. 최소 mcpServers 설정:

JSON

{
  "mcpServers": {
    "fstar": {
      "command": "npx",
      "args": ["-y", "openapi-mcp-server", "https://api.fstar.io/openapi.json"]
    }
  }
}

브리지는 /openapi.json을 읽어 모든 읽기 전용 엔드포인트를 MCP 도구로 노출합니다. 네이티브 F-Star MCP 서버는 로드맵에 있습니다(Phase 3).

이벤트 푸시나 쓰기 작업(사용자를 대신한 구독)이 필요하신가요? 그것들은 로드맵에 있습니다 — Phase 2(SSE + 서명된 응답)와 Phase 4(메타 트랜잭션 릴레이어). v1은 안정적인 읽기 전용 접근에 집중합니다.