INICIO RÁPIDO

Conéctate en 4 pasos

Quickstart

De cero a tu primera llamada exitosa en menos de cinco minutos. A continuación: curl en crudo, uso de herramientas de Claude, function calling de OpenAI y el patrón de manejo de errores.

Obtén la descripción de OpenAPI

Un GET devuelve una descripción legible por máquina de cada endpoint. Cualquier LLM puede autodescribirse y construir llamadas correctas a partir de ella.

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

Entrégala a tu framework de agentes

Convierte openapi.json en una definición de herramienta de Claude o en una definición de función de OpenAI; la mayoría de los frameworks pueden derivar los esquemas de herramienta directamente de 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?" }],
});

Emite una consulta de solo lectura

Pídele al agente «cuál es el NAV actual de QDFI»: debería emitir GET /v1/funds/qdfi/nav y explicar el JSON devuelto.

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()

Maneja errores y límites de tasa

Todos los errores son application/problem+json; ante un 429, lee Retry-After y aplica backoff; envía If-None-Match para usar los ETags y obtener 304 baratos.

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

Móntala como un servidor MCP

¿Quieres que Claude Desktop / Cursor y otros clientes MCP llamen directamente a la API de F-Star? Envuelve el OpenAPI con un puente genérico OpenAPI→MCP (p. ej. openapi-mcp-server), sin código de pegamento. Configuración mínima de mcpServers:

JSON

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

El puente lee /openapi.json y expone cada endpoint de solo lectura como una herramienta MCP. Un servidor MCP nativo de F-Star está en la hoja de ruta (Fase 3).

¿Necesitas push de eventos u operaciones de escritura (suscribirte en nombre de un usuario)? Están en la hoja de ruta: Fase 2 (SSE + respuestas firmadas) y Fase 4 (relayer de metatransacciones). La v1 se centra en un acceso estable de solo lectura.