QUICKSTART

Connect in 4 steps

Quickstart

From zero to your first successful call in under five minutes. Below: raw curl, Claude tool use, OpenAI function calling, and the error-handling pattern.

Fetch the OpenAPI description

One GET returns a machine-readable description of every endpoint. Any LLM can self-describe and build correct calls from it.

# 拉取完整 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

Hand it to your agent framework

Convert openapi.json into a Claude tool definition or an OpenAI function definition; most frameworks can derive tool schemas straight from 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?" }],
});

Issue a read-only query

Ask the agent "what is QDFI's current NAV" — it should emit GET /v1/funds/qdfi/nav and explain the returned 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()

Handle errors and rate limits

All errors are application/problem+json; on 429 read Retry-After and back off; send If-None-Match to use ETags for cheap 304s.

# 错误是 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

Mount as an MCP server

Want Claude Desktop / Cursor and other MCP clients to call the F-Star API directly? Wrap the OpenAPI with a generic OpenAPI→MCP bridge (e.g. openapi-mcp-server) — no glue code needed. Minimal mcpServers config:

JSON

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

The bridge reads /openapi.json and exposes every read-only endpoint as an MCP tool. A native F-Star MCP server is on the roadmap (Phase 3).

Need event push or write operations (subscribe on a user's behalf)? Those are on the roadmap — Phase 2 (SSE + signed responses) and Phase 4 (meta-transaction relayer). v1 focuses on stable read-only access.