QUICKSTART

4 步接入

Quickstart

从零到第一次成功调用，通常不到五分钟。下面分别给出原始 curl、Claude tool use、OpenAI function calling 与错误处理范式。

拉取 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

喂给你的 Agent 框架

把 openapi.json 转成 Claude 的 tool 定义或 OpenAI 的 function 定义；多数框架可直接从 OpenAPI 自动派生 tool schema。

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?" }],
});

发起只读查询

让 agent 回答“QDFI 当前净值是多少”，它应自动发出 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 server

想让 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 tools。官方原生 MCP server 在路线图中（Phase 3）。

需要事件推送或写操作（代用户申购）？这些在路线图的 Phase 2（SSE + 签名响应）与 Phase 4（meta-transaction relayer）。当前 v1 专注稳定的只读读取。