fintel-data

Fintel Data Skill

ホストが以下のシェルプローブをまだ実行していない場合（たとえば Codex の場合）は、セットアップ方法を選ぶ前に、シェルツールを使って ! ラッパー内のコマンドを実行してください。実際の出力を使用してください。シェルにアクセスできない場合は、その制約を報告してください。

Fintel（fintel.io）は、機関投資家向けのマーケットインテリジェンスプラットフォームです。 特に優れたデータセットは、他の多くのプロバイダーが提供していないものです。空売り残高、株券借入金利、空売り出来高、受渡不履行、13F 機関投資家保有状況、インサイダー取引が含まれます。

Fintel は、同じデータ契約に基づく 2 つのインターフェースを提供しています。

インターフェース	エンドポイント	認証	最適な用途
REST	https://api.fintel.io/v1/*	X-API-KEY ヘッダー	デフォルト — 任意の CLI エージェントから curl を実行
MCP	https://mcp.fintel.io/mcp	X-API-KEY ヘッダー	MCP ネイティブクライアント、ツールの自動検出

どちらも Fintel API キーが必要です。このスキルは読み取り専用です — GET エンドポイントのみ呼び出してください。API は書き込みエンドポイント（株式リストの作成・削除、アラート登録、チーム）も提供していますが、呼び出さないでください。

---

Step 1: FINTEL_API_KEY の解決

このスキルは、次の順序で FINTEL_API_KEY を解決します。

1. FINTEL_API_KEY 環境変数
2. 現在のディレクトリにある .env の FINTEL_API_KEY
3. Git リポジトリのルートにある .env の FINTEL_API_KEY（これにより、ワークツリーはメインのチェックアウトからキーを引き継ぎます）

!`if [ -n "$FINTEL_API_KEY" ]; then echo "KEY_FROM_ENV_VAR"; elif [ -f .env ] && grep -qE "^FINTEL_API_KEY=" .env; then echo "KEY_FROM_LOCAL_DOTENV:$(pwd)/.env"; else GIT_COMMON=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null); if [ -n "$GIT_COMMON" ]; then ROOT=$(dirname "$GIT_COMMON"); if [ -f "$ROOT/.env" ] && grep -qE "^FINTEL_API_KEY=" "$ROOT/.env"; then echo "KEY_FROM_ROOT_DOTENV:$ROOT/.env"; else echo "KEY_NOT_SET"; fi; else echo "KEY_NOT_SET"; fi; fi`

結果に応じて、次のように対応してください。

• KEY_FROM_ENV_VAR — curl 呼び出しでは $FINTEL_API_KEY を直接使用します。
• KEY_FROM_LOCAL_DOTENV:<path> / KEY_FROM_ROOT_DOTENV:<path> — 呼び出しの前に一度読み込みます。

  export FINTEL_API_KEY=$(grep -E "^FINTEL_API_KEY=" <path> | head -1 | cut -d= -f2- | sed 's/^["'\'']//;s/["'\'']$//')
  

• KEY_NOT_SET — ユーザーにキーを尋ねます。キーは Fintel API プランに付属します（fintel.io、ドキュメントは api.fintel.io/docs）。export FINTEL_API_KEY="..." を実行するか、リポジトリルートの .env に FINTEL_API_KEY=... を追加できます（ワークツリーでは後者を推奨します）。

---

Step 2: 証券の特定

ほとんどのエンドポイントは {country}/{symbol} 形式で指定します。ISO 国コードとティッカーの組み合わせで、例は us/AAPL です。ユーザーがティッカーだけを指定した場合は、us をデフォルトにします。

ティッカーが曖昧な場合、またはユーザーが企業名、CUSIP、ISIN、FIGI を指定した場合は、先に解決してください。

# name / ticker / CUSIP / ISIN / FIGI search
curl -s -H "X-API-KEY: $FINTEL_API_KEY" "https://api.fintel.io/v1/securities?query=apple&country=us"
# exact identifier lookup (type: cusip, isin, ticker, id)
curl -s -H "X-API-KEY: $FINTEL_API_KEY" "https://api.fintel.io/v1/identifiers/isin/US0378331005"

---

ステップ 3：リクエストに対応するエンドポイントを特定する

ユーザーの要望	エンドポイント	備考
空売り残高、カバー日数	/v1/securities/{country}/{symbol}/short-interest	過去1年分、NYSE/NASDAQ報告データ。利用可能範囲に制限があります。アカウントごとに有効化する必要があり、403 は利用権限がないことを意味します
貸株料、借株コスト、貸出可能株数	/v1/securities/{country}/{symbol}/borrow-rate	最新の証券貸借料率、リベート率、貸出可能株数
日次空売り出来高	/v1/securities/{country}/{symbol}/short-volume	過去1年分：空売り、空売り免除、総出来高
フェイルズ・トゥ・デリバー／FTD	/v1/securities/{country}/{symbol}/fails-to-deliver	過去1年分の SEC FTD 記録（米国のみ）
機関投資家の保有者／13F 保有者	/v1/securities/{country}/{symbol}/owners	SEC 13F データに基づく現在の保有者
インサイダー取引／Form 4	/v1/securities/{country}/{symbol}/insiders	SEC Form 3/4/5 データに基づく。count パラメーター
アナリストの目標株価	/v1/securities/{country}/{symbol}/price-targets	高値、安値、平均値、中央値
アナリストの買い／保有／売り評価	/v1/securities/{country}/{symbol}/analyst-ratings	推奨評価を集計
売上高／EPS 予測	/v1/securities/{country}/{symbol}/forecast	アナリスト予測を集計
日次終値の履歴	/v1/securities/{country}/{symbol}/eod	period：1m、3m、6m、1y（デフォルト）、2y、3y、5y、all
最新株価と算出指標	/v1/securities/{country}/{symbol}/last-price	52週高値／安値、週初来／月初来／年初来の変動率。EOD 終値にフォールバックする場合は meta.warnings=["quote_stale"] が返されます
配当履歴	/v1/securities/{country}/{symbol}/dividends
決算履歴と予想との差	/v1/securities/{country}/{symbol}/earnings
今後の決算（1銘柄／市場全体）	/v1/securities/{country}/{symbol}/calendar/earnings または /v1/calendar/earnings	from／to は ISO 日付。デフォルトは今日から7日後まで、最大期間は90日
今後の配当（1銘柄／市場全体）	/v1/securities/{country}/{symbol}/calendar/dividends または /v1/calendar/dividends	期間のルールは同じです
特定のファンダメンタル指標	/v1/securities/{country}/{symbol}/data-points/{key}	/v1/data-definitions?query=... でキーを確認
ランキング上位／下位の銘柄	/v1/leaderboards の後に /v1/leaderboards/{key}/entries	503 not_available は後で再試行してください。meta.status="beta" はスタブデータを意味します
証券プロフィール、上場情報、識別子の履歴	/v1/securities/{country}/{symbol}
ユーザーのウォッチリスト	/v1/stock-lists、/v1/stock-lists/{id}/items	リストごとに /insiders、/owners、/filings も利用できます
ユーザーのアラート	/v1/alerts、/v1/alert-messages
アカウント／利用権限	/v1/account

すべてのパラメーターの詳細、国／取引所の確認用エンドポイント、 その他の curl の例については、references/api-reference.md を参照してください。

---

ステップ 4：API を呼び出す

curl -s -H "X-API-KEY: $FINTEL_API_KEY" \
  "https://api.fintel.io/v1/securities/us/AAPL/short-volume" | python3 -m json.tool

• 成功時のレスポンスは JSON です。一部には meta オブジェクト（警告、 データの鮮度、ステータス）が含まれます。meta.warnings がある場合は ユーザーに伝えてください。
• エラーは {"error": {"code": "...", "message": "..."}} の形式で返されます。例： unauthorized（キーが無効、または未指定）、403（アカウントでデータセットが 有効になっていない。空売り残高でよく発生します）、503 not_available（ランキング サービスが停止中。後で再試行し、データが空だとは扱わないでください）。
• 利用量はアカウントごとに計測されます。バッチ処理は慎重に行い、ポーリングは避けてください。

---

ステップ 5：MCP の代替手段（任意）

MCP ネイティブのセットアップでは、公式サーバーから同じツールを検出できます （fintel.get_short_interest、fintel.get_security_owners などのツール名。REST と同等の機能で、利用権限も同じです）。

claude mcp add --transport http fintel https://mcp.fintel.io/mcp --header "X-API-KEY: your_key_here"

シェルにアクセスできる場合は、キー以外のセットアップが不要な curl 経由の REST を 優先してください。ユーザーが明示的に希望した場合、またはシェルへのアクセスが 制限されている場合は MCP を使用してください（注：どちらも Claude.ai の サンドボックスでは動作しません）。

ステップ 6：ユーザーに回答する

• 数値は見やすく整えます。価格は小数点以下 2 桁、パーセンテージは小数点以下 1～2 桁、株数はカンマ区切りまたは略記（2.3M、1.1B）にします。
• 空売りデータが少ない場合は、文脈を補足します。空売り残高は浮動株に対する割合、カバー日数、借株手数料の傾向を示します。借株手数料が高く、利用可能な株数が減少しているのは、典型的なスクイーズの状況です。予測はせず、データを提示してください。
• 保有状況やインサイダー取引には表（保有者、株数、変動、日付）を使います。Form 4 データでは、買い、売り、オプション行使を区別します。
• 該当する場合は、データセットの出所（SEC 13F、Form 3/4/5、NYSE/NASDAQ の空売り報告）とともに、データソースとして「Fintel」を記載します。
• データを売買の推奨、目標株価、スクイーズの予測に変換しないでください。事実を提示し、結論はユーザーに委ねます。

---

参考ファイル

• references/api-reference.md — REST エンドポイントの完全なリファレンス。すべての GET エンドポイント、パラメーター、デフォルト値、制限、エラーの意味、MCP ツール名との対応、curl の例を記載しています。