株主優待 MCP (Yutai MCP)

株主優待を検索する。複数条件を組み合わせて絞り込める。 【重要: vestingDates と karaDates の違い】 vestingDates（権利確定日）: 現物保有で優待を得るための権利確定月日。「○月に権利確定する銘柄」はこちら。 karaDates（空クロス日）: 権利確定日だけでなく別の日付にも株を一定数保有する必要がある銘柄の、その追加保有日。 端株保有だけでは条件を満たせず、その日付にクロス取引（空クロス）で株数を確保する必要がある。 「○月に空クロスが必要な銘柄」→ karaDate="MM" または karaDateFrom/karaDateTo で検索する。 vestingDate で検索しても空クロス対象の銘柄は正しく絞り込めない。 【信用取引区分 lendingType】 both=制度信用売り可。制度信用でクロスができる buying_only=制度信用買いのみ可、売りが使えないため制度信用ではクロスができない none=信用取引不可 【制度信用の規制 systemLendingStatus】各結果に付く。none=規制なし / warn=注意喚起(増担保・申込停止等) / prohibited=売禁(制度信用の新規売り停止)。lendingType(構造的な区分)とは別で、日々変動する。 ・売禁の銘柄だけ / 除外したい → sellProhibited=true / false ・注意喚起の銘柄だけ / 除外したい → sellCaution=true / false ・売禁または注意喚起(要注意銘柄)だけ / 除外したい → sellRestricted=true / false データ未取得の銘柄は「規制なし」として扱う。 【増担保 marginRateMultiplier】各結果に付く。増担保金徴収措置による最高料率倍率(例: 10=10倍)。 systemLendingStatusとは別の措置で、売禁・注意喚起と同時に付くことも単独で付くこともある。措置無しはundefined。 ・倍率で絞り込みたい → minMarginRateMultiplier / maxMarginRateMultiplier(措置無しの銘柄は対象外になる) 【長期条件】longType: none=なし / longAddition=長期優遇 / longOnly=長期必須 【難易度】rarity: 前回権利時の一般信用在庫の推移(証券会社別)から算出した「一般信用クロスでの 確保しやすさ」。canNormalSelling_* / minRemain_* とは別の、過去実績ベースの総合指標。 S(最難。在庫がほぼ出回らない)>A>B>C>D>E(最易。常時潤沢) ※minRarity='A' → AかSの銘柄のみ 【一般信用売り】canNormalSelling_*: enableSelling=売り可(空売含) / enableLongSelling=長期売りのみ可 / notEnableSelling=不可 【一般信用残】minRemain_sbi/gmo: few=△以上 / remaining=◎のみ。minRemain_rakuten/kabucom/smbc: 数量指定 【利回り】actualYield(%): 優待の申込単位ごとに (評価額 ÷ (株価×その単位の株数)) × 100 を計算し、 達成可能な最良の値を採用する(必要株数がminRequiredUnitsと異なる場合がある)。 長期保有条件(details[].longType='required'/'additional')付きの上位ランク・追加分はクロス (初回取得)では届かないため対象外(longTypeが無い基本額のみで計算)。 クロスの手数料・貸株料・逆日歩は一切含まない額面利回り。 ※minValue/maxValue(評価額の最小値/最大値)・minRequiredUnits(必要株数の最小値)は、それぞれ独立の別統計であり 同じ申込単位の値とは限らない(actualYieldの算出には使わない)。 【手取り利回り】netYield(%): (優待評価額 - 必要クロスコスト)/必要資金×100。必要クロスコストに逆日歩は 含まない(一般信用クロスのみが対象で、逆日歩が発生する制度信用は含まないため)。 ・各結果に crossCost(必要クロスコスト)/crossCostBroker/crossCostSellMethod/netValue/netYield が付く。 ・比較対象は「今この銘柄で実際にできる一般信用クロス」に限る: - その証券会社で一般信用売りの取り扱いがあり(enableShort/enableUnlimited)、かつ残数がある - 短期(general_short)は SBI/GMO/楽天のみ。約定日が売建可能日以降であること - 制度信用クロスは常に対象外(逆日歩リスクがあるため netYield には含めない) ・上記を満たす手段が1つも無い銘柄、株価・優待評価額・権利確定日が無い銘柄、 今からでは決済が間に合わない銘柄には netYield が付かない(= 今すぐ得できる優待の指標)。 ・「手数料を引いても得な優待」は minNetYield / sortBy:netYield で絞る。 ・返す数件には常に付くが、sortBy:netYield / minNetYield / maxNetYield を指定したときだけ 全候補に対して計算する(それ以外は最終ページの数件のみ計算)。 ・使ったプラン設定(ゼロ革命/コース/大口優遇/約定日)はヘッダー行に出る。ユーザーの実際の契約と 違う場合は sbiZeroRevolution / rakutenCourse / kabucomLargeLot / date 等で指定し直せることを案内すること。 【逆日歩】prevLendingInterest: 直近1回(前回の権利付き最終日)の逆日歩実績のみ(平均ではない)を、 1日あたり・株価に対する比率に換算した値(0.01=1日あたり1%)。制度信用クロスのコスト目安に使う。 過去複数回の履歴(ワースト10・直近10日)や一般信用在庫の推移は get_benefit に sections:["negativeInterests"] / ["remainingHistories"] を指定して取得する。 【並べ替え】sortBy / order で並べ替え、件数は limit で指定する(省略時20件。sortByとは独立)。 「手取り利回り順トップ10」→ sortBy:netYield と limit:10 を両方指定する(sortByだけでは10件に絞らない)。 他に「必要資金の少ない順」→ requiredFunds、「前回逆日歩が高い順」→ prevLendingInterest(一般信用推奨候補)。 sortBy 省略時は並べ替えなし。 【出力フィールドの読み方】 unit/minRequiredUnits: 権利確定日に必要な通常の株数 details[]: 優待の詳細条件一覧。各要素に以下が含まれる: candidates[].unit: その条件での必要株数 longType: 'additional'=長期優遇 / 'required'=長期必須 longCondition: 長期保有条件の概要テキスト（例: "継続保有期間1年以上"） longConditionDetail: 長期保有条件の詳細テキスト 「空クロスで必要な株数を教えて」→ details[].longConditionDetail のテキストから株数を読み取る 「長期条件を教えて」→ details[].longCondition と details[].longConditionDetail を参照する 「空クロスの有無」→ karaDates の有無を確認する（details の longType とは別物） 【details[].candidates の金額と vestingDates（複数権利月）の対応】 vestingDates が複数ある銘柄（例: ["03","09"]=年2回）で、candidates[].detail に月の但し書き （「3月のみ」「(9月)」等）が無い場合、その金額(value)は権利月ごとに同額が適用される （例: vestingDates=["03","09"], detail="500円分" → 3月に500円分・9月にも500円分もらえる。 年間合計は1000円分であり、「9月分かどうか不明」ではない）。 一方、detail に特定の月が明記されている場合（例:「(3月のみ)クオカード3,000円相当 (9月)クオカード2,000円分」）は、 明記された月にのみその内容が適用され、他の月は別の候補行（candidates の別要素）を参照する。 「○月にもらえる優待は？」と聞かれたら、月の但し書きが無い限り vestingDates に含まれる 全ての月で同じ内容がもらえると回答すること（「不明」「要確認」と答えない）。

{
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "description": "部分一致検索。対象: 銘柄コード / 銘柄名 / サマリー / 詳細説明(description) / 更新メモ(updateNote) / 優待内容の各候補テキスト(details[].candidates[].detail)。「コストコ」「株主優待券」など優待の中身でも検索できる。例: \"3397\", \"すかいらーく\", \"コストコ\""
    },
    "benefitTypes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "優待種別（OR検索）。例: [\"QUO\",\"MealTicket\"]。指定した種別のいずれかを持つ銘柄を返す。種別一覧: QUO, RiceVoucher, CashVoucher, JEFVoucher, MealTicket, FacilityTicket, ShoppingTicket, HotelTicket, TransportTicket, OtherTicket, CatalogGift, PYC, Electronics, Fashion, OtherItems, Fruit, Meat, Fish, Drink, Liquor, Rice, Sweets, OtherMeal"
    },
    "vestingDate": {
      "type": "string",
      "description": "権利確定月または月日で単一絞り込み。例: \"03\"=3月, \"03-20\"=3月20日 (vestingDates配列に対してマッチ)"
    },
    "vestingDateFrom": {
      "type": "string",
      "description": "次回権利確定日の下限 (YYYY-MM-DD)。nextVestingDate >= この値の銘柄を返す"
    },
    "vestingDateTo": {
      "type": "string",
      "description": "次回権利確定日の上限 (YYYY-MM-DD)。nextVestingDate <= この値の銘柄を返す"
    },
    "requireKara": {
      "type": "boolean",
      "description": "true=空クロスが必要な日付（karaDates）がある銘柄のみ / false=karaDatesがない銘柄のみ"
    },
    "karaDate": {
      "type": "string",
      "description": "空クロスが必要な月または月日で絞り込む。「○月に空クロスが必要な銘柄」を探す場合はここを使う。例: \"05\"=5月, \"05-20\"=5月20日。vestingDate（権利確定日）とは別物なので混同しないこと。"
    },
    "karaDateFrom": {
      "type": "string",
      "description": "次回空クロス日の下限 (YYYY-MM-DD)。例: \"2026-05-01\" → 5月以降に空クロスが必要な銘柄"
    },
    "karaDateTo": {
      "type": "string",
      "description": "次回空クロス日の上限 (YYYY-MM-DD)。例: \"2026-05-31\" → 5月末までに空クロスが必要な銘柄"
    },
    "lendingType": {
      "type": "string",
      "enum": [
        "both",
        "buying_only",
        "none"
      ],
      "description": "信用取引区分。both=制度クロス可, buying_only=空クロス必要, none=クロス不可"
    },
    "sellProhibited": {
      "type": "boolean",
      "description": "制度信用の売禁(新規売り停止)。true=売禁の銘柄のみ / false=売禁でない銘柄のみ。データ未取得は「規制なし」扱い"
    },
    "sellCaution": {
      "type": "boolean",
      "description": "制度信用の注意喚起(増担保・申込停止等)。true=注意喚起中の銘柄のみ / false=注意喚起でない銘柄のみ"
    },
    "sellRestricted": {
      "type": "boolean",
      "description": "売禁または注意喚起(制度信用の要注意銘柄)。true=いずれかに該当する銘柄のみ / false=どちらでもない銘柄のみ"
    },
    "longType": {
      "type": "string",
      "enum": [
        "none",
        "longAddition",
        "longOnly"
      ],
      "description": "長期保有条件の完全一致。none=なし, longAddition=長期優遇, longOnly=長期必須"
    },
    "hasLongCondition": {
      "type": "boolean",
      "description": "trueにすると長期条件あり銘柄 (longAddition または longOnly) のみ返す"
    },
    "anyDay": {
      "type": "boolean",
      "description": "長期条件の判定で、決まった基準日以外にも「任意の日」に保有状況を抜き打ちで確認すると明記されている銘柄かどうか。trueにするとそれに該当する銘柄のみ返す(基準日だけクロスで確保しても長期条件を満たせない可能性がある、要注意銘柄)"
    },
    "minActualYield": {
      "type": "number",
      "description": "実利回り下限 (%)。優待の申込単位のうち達成可能な最良の額面利回りで、クロスの手数料・貸株料・逆日歩は含まない。手数料込みで絞るには minNetYield を使う。株価データが無い銘柄(price未取得)はこの条件では判定できないため除外される。例: 1.0 = 1%以上"
    },
    "maxActualYield": {
      "type": "number",
      "description": "実利回り上限 (%)。優待の申込単位のうち達成可能な最良の額面利回りで、クロスの手数料・貸株料・逆日歩は含まない。手数料込みで絞るには maxNetYield を使う。株価データが無い銘柄(price未取得)はこの条件では判定できないため除外される。例: 5.0 = 5%以下"
    },
    "minValue": {
      "type": "number",
      "description": "絞り込みたい優待評価額の下限 (円)。優待自身の評価額の範囲(出力のminValue〜maxValue)がこの下限〜maxValue引数の範囲に少しでも重なる銘柄を返す(単一値の一致ではない)。例: 1000 = 1000円以上を含む銘柄"
    },
    "maxValue": {
      "type": "number",
      "description": "絞り込みたい優待評価額の上限 (円)。優待自身の評価額の範囲(出力のminValue〜maxValue)がminValue引数〜この上限の範囲に少しでも重なる銘柄を返す(単一値の一致ではない)。例: 10000 = 10000円以下を含む銘柄"
    },
    "minRequiredFunds": {
      "type": "number",
      "description": "必要資金の下限 (円)。株価×minRequiredUnits で計算。株価データが無い銘柄(price未取得)はこの条件では判定できないため除外される"
    },
    "maxRequiredFunds": {
      "type": "number",
      "description": "必要資金の上限 (円)。株価×minRequiredUnits で計算。株価データが無い銘柄(price未取得)はこの条件では判定できないため除外される"
    },
    "minPrevLendingInterest": {
      "type": "number",
      "description": "前回逆日歩率(1日あたり・株価に対する比率)の下限。例: 0.005 = 1日あたり0.5%以上"
    },
    "maxPrevLendingInterest": {
      "type": "number",
      "description": "前回逆日歩率(1日あたり・株価に対する比率)の上限。例: 0.01 = 1日あたり1%以下"
    },
    "minMarginRateMultiplier": {
      "type": "number",
      "description": "増担保金徴収措置による最高料率倍率(marginRateMultiplier)の下限。措置が無い銘柄は対象外になる。例: 5 = 5倍以上"
    },
    "maxMarginRateMultiplier": {
      "type": "number",
      "description": "増担保金徴収措置による最高料率倍率(marginRateMultiplier)の上限。措置が無い銘柄は対象外になる。例: 10 = 10倍以下"
    },
    "minRarity": {
      "type": "string",
      "enum": [
        "S",
        "A",
        "B",
        "C",
        "D",
        "E"
      ],
      "description": "一般信用クロスの取得難易度(前回権利時の在庫推移から算出)の下限。S>A>B>C>D>E。例: \"A\" → AまたはSの難しい銘柄のみ"
    },
    "maxRarity": {
      "type": "string",
      "enum": [
        "S",
        "A",
        "B",
        "C",
        "D",
        "E"
      ],
      "description": "一般信用クロスの取得難易度(前回権利時の在庫推移から算出)の上限。例: \"C\" → C,D,Eの取りやすい銘柄のみ"
    },
    "updateFrom": {
      "type": "string",
      "description": "優待内容が変更された日(update)の下限 (YYYY-MM-DD)。例: \"2026-05-01\" → 5月1日以降に優待内容が変更された銘柄"
    },
    "updateTo": {
      "type": "string",
      "description": "優待内容が変更された日(update)の上限 (YYYY-MM-DD)。例: \"2026-05-31\" → 5月末までに優待内容が変更された銘柄"
    },
    "canNormalSelling_any": {
      "type": "string",
      "enum": [
        "enableSelling",
        "enableLongSelling",
        "notEnableSelling"
      ],
      "description": "いずれかの証券会社で条件を満たす銘柄を返す (OR検索)。「どこかで一般信用売りができる銘柄」を探すときに使う。個別の canNormalSelling_* と併用すると AND になる。enableSelling=売り可, enableLongSelling=長期売りのみ"
    },
    "minRemain_any_count": {
      "type": "number",
      "description": "楽天・カブコム・SMBCのいずれかで指定した株数以上の一般信用残数がある銘柄 (OR検索)。例: 1 → どこかに在庫あり, 2000 → どこかに2000株以上"
    },
    "canNormalSelling_sbi": {
      "$ref": "#/properties/canNormalSelling_any",
      "description": "SBI 一般信用売り可否。enableSelling=売り可, enableLongSelling=長期売りのみ, notEnableSelling=不可"
    },
    "canNormalSelling_gmo": {
      "$ref": "#/properties/canNormalSelling_any",
      "description": "GMO 一般信用売り可否"
    },
    "canNormalSelling_rakuten": {
      "$ref": "#/properties/canNormalSelling_any",
      "description": "楽天 一般信用売り可否"
    },
    "canNormalSelling_kabucom": {
      "$ref": "#/properties/canNormalSelling_any",
      "description": "カブドットコム 一般信用売り可否"
    },
    "canNormalSelling_smbc": {
      "$ref": "#/properties/canNormalSelling_any",
      "description": "SMBC日興 一般信用売り可否"
    },
    "minRemain_sbi": {
      "type": "string",
      "enum": [
        "few",
        "remaining"
      ],
      "description": "SBI 一般信用残数の下限。few=△以上(△または◎), remaining=◎のみ。canNormalSelling_sbi=enableSelling と併用推奨"
    },
    "minRemain_gmo": {
      "$ref": "#/properties/minRemain_sbi",
      "description": "GMO 一般信用残数の下限。few=△以上, remaining=◎のみ"
    },
    "minRemain_rakuten": {
      "type": "number",
      "description": "楽天 一般信用残数の下限（株数）。例: 1000 = 1000株以上"
    },
    "minRemain_kabucom": {
      "type": "number",
      "description": "カブドットコム 一般信用残数の下限（株数）"
    },
    "minRemain_smbc": {
      "type": "number",
      "description": "SMBC日興 一般信用残数の下限（株数）"
    },
    "minNetYield": {
      "type": "number",
      "description": "手取り利回りの下限 (%)。例: 0.5 = 手数料を引いても0.5%以上"
    },
    "maxNetYield": {
      "type": "number",
      "description": "手取り利回りの上限 (%)"
    },
    "date": {
      "type": "string",
      "description": "netYield計算の約定日 (YYYY-MM-DD)。省略時は「今」から自動算出(JST 15:30より前なら当日、以降なら翌営業日)"
    },
    "sbiVip": {
      "type": "boolean",
      "description": "SBI大口優遇(建玉5億円以上)。既定false"
    },
    "sbiZeroRevolution": {
      "type": "boolean",
      "description": "SBIゼロ革命(電子交付設定)。既定true"
    },
    "gmoVip": {
      "type": "boolean",
      "description": "GMO VIPプラン。既定false"
    },
    "rakutenCourse": {
      "type": "string",
      "enum": [
        "zero",
        "chowari"
      ],
      "description": "楽天のコース。既定\"zero\"(ゼロコース)"
    },
    "rakutenVip": {
      "type": "boolean",
      "description": "楽天大口優遇。既定false"
    },
    "rakutenPreferentialRate": {
      "type": "boolean",
      "description": "楽天優遇金利適用。既定false"
    },
    "kabucomSor": {
      "type": "boolean",
      "description": "カブコムSOR(スマート・オーダー・ルーティング)。既定false"
    },
    "kabucomLargeLot": {
      "type": "string",
      "enum": [
        "crown",
        "diamond",
        "sapphire",
        "platinum",
        "gold",
        "silver",
        "none"
      ],
      "description": "カブコム大口優遇ランク。既定\"none\""
    },
    "excludeCodes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "除外する銘柄コード配列"
    },
    "sortBy": {
      "type": "string",
      "enum": [
        "actualYield",
        "netYield",
        "minValue",
        "requiredFunds",
        "prevLendingInterest",
        "nextVestingDate",
        "update"
      ],
      "description": "並べ替えキー。actualYield=実質利回り(手数料考慮なし) / netYield=手取り利回り(必要クロスコスト〈逆日歩除く〉を引いた後) / minValue=優待評価額 / requiredFunds=必要資金 / prevLendingInterest=前回の逆日歩率 / nextVestingDate=次回権利確定日 / update=優待内容が最後に変更された日。省略時は並べ替えなし。値を持たない銘柄は order によらず末尾"
    },
    "order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "並び順。省略時のデフォルトは sortBy 依存(nextVestingDate/requiredFunds は asc、それ以外は desc)"
    },
    "limit": {
      "type": "number",
      "description": "最大件数 (デフォルト20)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "total": {
      "type": "number",
      "description": "フィルタ後(ページングする前)の全該当件数"
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "銘柄コード"
          },
          "name": {
            "type": "string"
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "vestingDates": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "権利確定の月または月日パターン(例: [\"03\",\"09\"])。年に依存しない繰り返しパターン"
          },
          "nextVestingDate": {
            "type": "string",
            "description": "次回の具体的な権利確定日(ISO文字列)。JST日付が \"...T15:00:00.000Z\" のように前日UTC表記になる点に注意"
          },
          "karaDates": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "空クロスが必要な月/月日パターン(vestingDatesとは別物)"
          },
          "nextKaraDate": {
            "type": [
              "string",
              "null"
            ],
            "description": "次回の具体的な空クロス日(ISO文字列)"
          },
          "lendingType": {
            "type": "string",
            "enum": [
              "both",
              "buying_only",
              "none"
            ],
            "description": "制度信用区分。both=制度信用売り可 / buying_only=買いのみ可 / none=不可"
          },
          "systemLendingStatus": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "none",
                  "warn",
                  "prohibited"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "制度信用の規制状態。none=規制なし / warn=注意喚起 / prohibited=売禁。lendingTypeとは別軸で日々変動する。データ無しはundefined(規制なし扱い)"
          },
          "marginRateMultiplier": {
            "type": [
              "number",
              "null"
            ],
            "description": "増担保金徴収措置による最高料率倍率(通常の委託保証金率に対する倍率。例: 10=10倍)。systemLendingStatusとは別の措置で、売禁・注意喚起と同時に付くことも単独で付くこともある。措置無しはundefined"
          },
          "longType": {
            "type": "string",
            "enum": [
              "none",
              "longAddition",
              "longOnly"
            ],
            "description": "none=長期条件なし / longAddition=長期優遇 / longOnly=長期必須"
          },
          "anyDay": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "trueの場合、基準日以外の「任意の日」にも保有状況を抜き打ち確認する旨が長期条件に明記されている(要注意銘柄)"
          },
          "rarity": {
            "type": "string",
            "description": "前回権利時の一般信用在庫推移から算出した確保しやすさ。S(最難)>A>B>C>D>E(最易)"
          },
          "benefitTypes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unit": {
            "type": "number",
            "description": "権利確定に必要な通常の株数(1単元)"
          },
          "minValue": {
            "type": [
              "number",
              "null"
            ],
            "description": "優待評価額(円)。優待の申込単位が複数ある場合、その中の最小の評価額"
          },
          "maxValue": {
            "type": [
              "number",
              "null"
            ],
            "description": "優待評価額(円)の最大値。優待の申込単位が複数ある場合、その中の最大の評価額"
          },
          "minRequiredUnits": {
            "type": "number",
            "description": "この優待を得るために必要な最小株数。申込単位が複数ある場合はその中の最小株数"
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "利回りや手数料の計算で使用している概算株価。現在の正確な株価ではない。取得できない銘柄はundefined"
          },
          "requiredFunds": {
            "type": [
              "number",
              "null"
            ],
            "description": "最小株数(minRequiredUnits)で優待を得るために必要な資金(円) = price × minRequiredUnits"
          },
          "actualYield": {
            "type": [
              "number",
              "null"
            ],
            "description": "実利回り(%)。優待の申込単位ごとに(評価額 ÷ (株価×その単位の株数)) × 100 を計算し、達成可能な最良の値を採用する(必要な株数がminRequiredUnitsより多い単位が選ばれることがある)。長期保有条件付きの上位ランク・追加分(details[].longType='required'/'additional')はクロス(初回取得)では届かないため対象外。クロスの手数料・貸株料・逆日歩は一切含まない額面利回り"
          },
          "prevLendingInterest": {
            "type": [
              "number",
              "null"
            ],
            "description": "前回の逆日歩率。直近1回(前回の権利付き最終日)の実績のみで、複数回の平均ではない。逆日歩額を1日あたり・株価に対する比率に換算した値(0.01=1日あたり1%)で、制度信用クロスのコスト目安に使う。過去複数回分の履歴は get_benefit の negativeInterests を参照"
          },
          "update": {
            "type": [
              "string",
              "null"
            ],
            "description": "優待内容(details等)が最後に変更された日(YYYY-MM-DD)。新設や変更(株式分割による区分変更・優待内容の変更・長期優遇の廃止等)があった際に更新される。何が変わったかは updateNote を参照"
          },
          "updateNote": {
            "type": [
              "string",
              "null"
            ],
            "description": "update日時点で何が変わったか(または新設か)を記した短い注記。例: \"新設\" / \"株式分割による区分変更。ポイントアップ。長期優遇を廃止\""
          },
          "details": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "candidates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "unit": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "この候補が適用される必要株数(通常のvesting株数と異なる場合がある)"
                          },
                          "detail": {
                            "type": "string",
                            "description": "優待内容のテキスト(例: \"2,000円分\")"
                          },
                          "value": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "円換算した評価額"
                          },
                          "benefitTypes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "detail",
                          "benefitTypes"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "longType": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "additional",
                            "required"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "長期条件区分。additional=長期優遇 / required=長期必須。無ければ長期条件なし"
                    },
                    "longCondition": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "長期保有条件の概要テキスト"
                    },
                    "longConditionDetail": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "長期保有条件の詳細テキスト(空クロスの必要株数等はここから読み取る)"
                    }
                  },
                  "required": [
                    "candidates"
                  ],
                  "additionalProperties": false
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "優待内容の詳細条件一覧"
          },
          "normalLendingStatus": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "sbi": {
                    "type": "object",
                    "properties": {
                      "enableShort": {
                        "type": "boolean",
                        "description": "一般信用「短期」の売り建てが可能か"
                      },
                      "enableUnlimited": {
                        "type": "boolean",
                        "description": "一般信用「無期限/長期」の売り建てが可能か"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "none",
                          "remaining",
                          "few"
                        ],
                        "description": "在庫ランク。none=在庫なし / few=△ / remaining=◎"
                      }
                    },
                    "required": [
                      "enableShort",
                      "enableUnlimited",
                      "status"
                    ],
                    "additionalProperties": false
                  },
                  "gmo": {
                    "type": "object",
                    "properties": {
                      "enableShort": {
                        "type": "boolean",
                        "description": "一般信用「短期」の売り建てが可能か"
                      },
                      "enableUnlimited": {
                        "type": "boolean",
                        "description": "一般信用「無期限/長期」の売り建てが可能か"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "none",
                          "remaining",
                          "few"
                        ],
                        "description": "在庫ランク。sbiと同様"
                      },
                      "limit": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "description": "在庫の上限株数(取得できた場合)"
                      }
                    },
                    "required": [
                      "enableShort",
                      "enableUnlimited",
                      "status"
                    ],
                    "additionalProperties": false
                  },
                  "rakuten": {
                    "type": "object",
                    "properties": {
                      "enableShort": {
                        "type": "boolean",
                        "description": "一般信用「短期」の売り建てが可能か"
                      },
                      "enableUnlimited": {
                        "type": "boolean",
                        "description": "一般信用「無期限/長期」の売り建てが可能か"
                      },
                      "status": {
                        "type": "number",
                        "description": "在庫株数"
                      }
                    },
                    "required": [
                      "enableShort",
                      "enableUnlimited",
                      "status"
                    ],
                    "additionalProperties": false
                  },
                  "kabucom": {
                    "type": "object",
                    "properties": {
                      "enableShort": {
                        "type": "boolean",
                        "description": "一般信用「短期」の売り建てが可能か"
                      },
                      "enableUnlimited": {
                        "type": "boolean",
                        "description": "一般信用「無期限/長期」の売り建てが可能か"
                      },
                      "status": {
                        "type": "number",
                        "description": "在庫株数"
                      },
                      "premium": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "プレミアム料率(文字列)"
                      }
                    },
                    "required": [
                      "enableShort",
                      "enableUnlimited",
                      "status"
                    ],
                    "additionalProperties": false
                  },
                  "smbc": {
                    "type": "object",
                    "properties": {
                      "enableShort": {
                        "type": "boolean",
                        "description": "一般信用「短期」の売り建てが可能か"
                      },
                      "enableUnlimited": {
                        "type": "boolean",
                        "description": "一般信用「無期限/長期」の売り建てが可能か"
                      },
                      "status": {
                        "type": "number",
                        "description": "在庫株数"
                      }
                    },
                    "required": [
                      "enableShort",
                      "enableUnlimited",
                      "status"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "sbi",
                  "gmo",
                  "rakuten",
                  "kabucom",
                  "smbc"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "証券会社別の一般信用在庫の現在ステータス"
          },
          "crossCost": {
            "type": [
              "number",
              "null"
            ],
            "description": "手取り利回りが最良になる組み合わせ(申込単位×証券会社×売り方式)での一般信用クロスの必要コスト(円)。一般信用のみが対象のため逆日歩は含まない(発生しない)。netYield計算時のみ付く。今実際にできる一般信用クロスが無い銘柄等は付かない"
          },
          "crossCostBroker": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "sbi",
                  "gmo",
                  "rakuten",
                  "kabucom",
                  "smbc"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "crossCostの組み合わせで採用された証券会社"
          },
          "crossCostSellMethod": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "general_short",
                  "general_long",
                  "system"
                ],
                "description": "general_short=一般信用「短期」 / general_long=一般信用「無期限・長期」 / system=制度信用"
              },
              {
                "type": "null"
              }
            ],
            "description": "crossCostの組み合わせで採用された売り方式"
          },
          "netValue": {
            "type": [
              "number",
              "null"
            ],
            "description": "優待評価額 - crossCost"
          },
          "netYield": {
            "type": [
              "number",
              "null"
            ],
            "description": "手取り利回り(%) = netValue / 必要資金 × 100"
          }
        },
        "required": [
          "code",
          "name",
          "vestingDates",
          "nextVestingDate",
          "lendingType",
          "longType",
          "rarity",
          "benefitTypes",
          "unit",
          "minRequiredUnits"
        ],
        "additionalProperties": false
      },
      "description": "itemsの各要素はrarity等のフィルタで使うのと同じ意味のフィールドを持つ"
    },
    "assumptions": {
      "type": "object",
      "properties": {
        "sbiVip": {
          "type": "boolean",
          "description": "SBI大口優遇の前提"
        },
        "sbiZeroRevolution": {
          "type": "boolean",
          "description": "SBIゼロ革命(電子交付設定)の前提"
        },
        "gmoVip": {
          "type": "boolean",
          "description": "GMO VIPプランの前提"
        },
        "rakutenCourse": {
          "type": "string",
          "enum": [
            "zero",
            "chowari"
          ],
          "description": "楽天のコースの前提"
        },
        "rakutenVip": {
          "type": "boolean",
          "description": "楽天大口優遇の前提"
        },
        "rakutenPreferentialRate": {
          "type": "boolean",
          "description": "楽天優遇金利適用の前提"
        },
        "kabucomSor": {
          "type": "boolean",
          "description": "カブコムSORの前提"
        },
        "kabucomLargeLot": {
          "type": "string",
          "enum": [
            "crown",
            "diamond",
            "sapphire",
            "platinum",
            "gold",
            "silver",
            "none"
          ],
          "description": "カブコム大口優遇ランクの前提"
        },
        "tradeDate": {
          "type": "string",
          "description": "netYield計算に使った約定日(YYYY-MM-DD)。省略時は「今」から自動算出"
        }
      },
      "required": [
        "sbiVip",
        "sbiZeroRevolution",
        "gmoVip",
        "rakutenCourse",
        "rakutenVip",
        "rakutenPreferentialRate",
        "kabucomSor",
        "kabucomLargeLot",
        "tradeDate"
      ],
      "additionalProperties": false,
      "description": "netYield計算に使った証券会社プラン・約定日の前提"
    }
  },
  "required": [
    "total",
    "items"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

銘柄コードで株主優待を1件取得する。sections で返す情報を選ぶ(不要なものは返さない)。 - basic (既定): 銘柄の基本情報。優待内容・権利確定日(vestingDates)・ 空クロス日(karaDates)・信用区分(lendingType)・制度信用の規制状態(systemLendingStatus: none/warn=注意喚起/prohibited=売禁)・増担保の最高料率倍率(marginRateMultiplier)・ 長期条件・難易度・株価・必要資金・実質利回り(actualYield)・ 現時点の一般信用残数(normalLendingStatus)・details(候補と長期保有条件)。 - negativeInterests: 逆日歩(制度信用売りで発生しうる、金額が事前に確定しない追加費用)の履歴。 prev(前回権利付最終日の1件)/ worst10(過去ワースト10、逆日歩/日 の降順)/ latest(直近10日)。 negativeInterestPerDiem / highestNegativeInterestPerDiem は「円/株」の文字列で lendingDays 日分。 1日あたりは negativeInterestPerDiem / lendingDays。balancePrice はその日の建値。 逆日歩は過去実績であり将来を保証・予測するものではない点をユーザーに必ず伝えること。 - remainingHistories: 一般信用売りの在庫ステータスの推移。prev(前回権利前3ヶ月)/ latest(直近1ヶ月)。 negativeInterests / remainingHistories は銘柄ごとに個別管理された詳細データが必要で、無い銘柄では notes に理由が入る。 basic のみ(既定)なら詳細データは取得しないため軽量。

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "銘柄コード。例: \"3397\""
    },
    "sections": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "basic",
          "negativeInterests",
          "remainingHistories"
        ]
      },
      "description": "返す情報の種類(配列)。省略時は [\"basic\"]。逆日歩履歴が欲しいときは [\"basic\",\"negativeInterests\"]、在庫推移も含めるなら [\"basic\",\"negativeInterests\",\"remainingHistories\"]"
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "銘柄コード"
    },
    "name": {
      "type": [
        "string",
        "null"
      ]
    },
    "summary": {
      "type": [
        "string",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "benefitTypes": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "vestingDates": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "権利確定の月または月日パターン(年に依存しない繰り返しパターン)"
    },
    "karaDates": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "空クロスが必要な月/月日パターン(vestingDatesとは別物)"
    },
    "nextVestingDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "次回の具体的な権利確定日(ISO文字列)"
    },
    "nextKaraDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "次回の具体的な空クロス日(ISO文字列)"
    },
    "vestingDateConcrete": {
      "type": [
        "string",
        "null"
      ],
      "description": "次回権利確定日(ISO文字列。日付フィルタ用の内部値、nextVestingDateとほぼ同じ)"
    },
    "karaDateConcrete": {
      "type": [
        "string",
        "null"
      ]
    },
    "longType": {
      "type": [
        "string",
        "null"
      ],
      "description": "長期条件。通常は none/longAddition/longOnly のいずれか"
    },
    "lendingType": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "both",
            "buying_only",
            "none"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "制度信用区分。both=制度信用売り可 / buying_only=買いのみ可 / none=不可"
    },
    "systemLendingStatus": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "none",
            "warn",
            "prohibited"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "制度信用の規制状態。none=規制なし / warn=注意喚起 / prohibited=売禁。lendingTypeとは別軸で日々変動する"
    },
    "marginRateMultiplier": {
      "type": [
        "number",
        "null"
      ],
      "description": "増担保金徴収措置による最高料率倍率(通常の委託保証金率に対する倍率。例: 10=10倍)。systemLendingStatusとは別の措置で、売禁・注意喚起と同時に付くことも単独で付くこともある。措置無しはundefined"
    },
    "rarity": {
      "type": [
        "string",
        "null"
      ],
      "description": "一般信用クロスの取得難易度(前回権利時の在庫推移から算出)。S(最難)>A>B>C>D>E(最易)"
    },
    "unit": {
      "type": [
        "number",
        "null"
      ],
      "description": "権利確定に必要な通常の株数(1単元)"
    },
    "minValue": {
      "type": [
        "number",
        "null"
      ],
      "description": "優待評価額(円)。優待の申込単位が複数ある場合、その中の最小の評価額"
    },
    "maxValue": {
      "type": [
        "number",
        "null"
      ],
      "description": "優待評価額(円)の最大値。優待の申込単位が複数ある場合、その中の最大の評価額"
    },
    "minRequiredUnits": {
      "type": [
        "number",
        "null"
      ],
      "description": "この優待を得るために必要な最小株数。申込単位が複数ある場合はその中の最小株数"
    },
    "anyDay": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "基準日以外の「任意の日」にも保有状況を抜き打ち確認する旨が長期条件に明記されているか(要注意銘柄)"
    },
    "update": {
      "type": [
        "string",
        "null"
      ],
      "description": "優待内容(details等)が最後に変更された日(YYYY-MM-DD)。新設や変更(株式分割による区分変更・優待内容の変更・長期優遇の廃止等)があった際に更新される。何が変わったかは updateNote を参照"
    },
    "updateNote": {
      "type": [
        "string",
        "null"
      ],
      "description": "update日時点で何が変わったか(または新設か)を記した短い注記。例: \"新設\" / \"株式分割による区分変更。ポイントアップ。長期優遇を廃止\""
    },
    "siteUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "price": {
      "type": [
        "number",
        "null"
      ],
      "description": "利回りや手数料の計算で使用している概算株価。現在の正確な株価ではない。取得できない銘柄はundefined"
    },
    "actualYield": {
      "type": [
        "number",
        "null"
      ],
      "description": "実利回り(%)。優待の申込単位ごとに(評価額 ÷ (株価×その単位の株数)) × 100 を計算し、達成可能な最良の値を採用する(必要な株数がminRequiredUnitsより多い単位が選ばれることがある)。長期保有条件付きの上位ランク・追加分(details[].longType='required'/'additional')はクロス(初回取得)では届かないため対象外。クロスの手数料・貸株料・逆日歩は一切含まない額面利回り"
    },
    "requiredFunds": {
      "type": [
        "number",
        "null"
      ],
      "description": "最小株数(minRequiredUnits)で優待を得るために必要な資金(円) = price × minRequiredUnits"
    },
    "prevLendingInterest": {
      "type": [
        "number",
        "null"
      ],
      "description": "前回の逆日歩率。直近1回(前回の権利付き最終日)の実績のみで、複数回の平均ではない。逆日歩額を1日あたり・株価に対する比率に換算した値(0.01=1日あたり1%)で、制度信用クロスのコスト目安に使う。過去複数回分の履歴は sections:[\"negativeInterests\"] を参照"
    },
    "details": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "candidates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "unit": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "この候補が適用される必要株数(通常のvesting株数と異なる場合がある)"
                    },
                    "detail": {
                      "type": "string",
                      "description": "優待内容のテキスト(例: \"2,000円分\")"
                    },
                    "value": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "円換算した評価額"
                    },
                    "benefitTypes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "detail",
                    "benefitTypes"
                  ],
                  "additionalProperties": false
                }
              },
              "longType": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "additional",
                      "required"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "長期条件区分。additional=長期優遇 / required=長期必須。無ければ長期条件なし"
              },
              "longCondition": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "長期保有条件の概要テキスト"
              },
              "longConditionDetail": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "長期保有条件の詳細テキスト(空クロスの必要株数等はここから読み取る)"
              }
            },
            "required": [
              "candidates"
            ],
            "additionalProperties": false
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "優待内容の詳細条件一覧"
    },
    "normalLendingStatus": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "sbi": {
              "type": "object",
              "properties": {
                "enableShort": {
                  "type": "boolean",
                  "description": "一般信用「短期」の売り建てが可能か"
                },
                "enableUnlimited": {
                  "type": "boolean",
                  "description": "一般信用「無期限/長期」の売り建てが可能か"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "none",
                    "remaining",
                    "few"
                  ],
                  "description": "在庫ランク。none=在庫なし / few=△ / remaining=◎"
                }
              },
              "required": [
                "enableShort",
                "enableUnlimited",
                "status"
              ],
              "additionalProperties": false
            },
            "gmo": {
              "type": "object",
              "properties": {
                "enableShort": {
                  "type": "boolean",
                  "description": "一般信用「短期」の売り建てが可能か"
                },
                "enableUnlimited": {
                  "type": "boolean",
                  "description": "一般信用「無期限/長期」の売り建てが可能か"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "none",
                    "remaining",
                    "few"
                  ],
                  "description": "在庫ランク。sbiと同様"
                },
                "limit": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "在庫の上限株数(取得できた場合)"
                }
              },
              "required": [
                "enableShort",
                "enableUnlimited",
                "status"
              ],
              "additionalProperties": false
            },
            "rakuten": {
              "type": "object",
              "properties": {
                "enableShort": {
                  "type": "boolean",
                  "description": "一般信用「短期」の売り建てが可能か"
                },
                "enableUnlimited": {
                  "type": "boolean",
                  "description": "一般信用「無期限/長期」の売り建てが可能か"
                },
                "status": {
                  "type": "number",
                  "description": "在庫株数"
                }
              },
              "required": [
                "enableShort",
                "enableUnlimited",
                "status"
              ],
              "additionalProperties": false
            },
            "kabucom": {
              "type": "object",
              "properties": {
                "enableShort": {
                  "type": "boolean",
                  "description": "一般信用「短期」の売り建てが可能か"
                },
                "enableUnlimited": {
                  "type": "boolean",
                  "description": "一般信用「無期限/長期」の売り建てが可能か"
                },
                "status": {
                  "type": "number",
                  "description": "在庫株数"
                },
                "premium": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "プレミアム料率(文字列)"
                }
              },
              "required": [
                "enableShort",
                "enableUnlimited",
                "status"
              ],
              "additionalProperties": false
            },
            "smbc": {
              "type": "object",
              "properties": {
                "enableShort": {
                  "type": "boolean",
                  "description": "一般信用「短期」の売り建てが可能か"
                },
                "enableUnlimited": {
                  "type": "boolean",
                  "description": "一般信用「無期限/長期」の売り建てが可能か"
                },
                "status": {
                  "type": "number",
                  "description": "在庫株数"
                }
              },
              "required": [
                "enableShort",
                "enableUnlimited",
                "status"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "sbi",
            "gmo",
            "rakuten",
            "kabucom",
            "smbc"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "証券会社別の一般信用在庫の現在ステータス"
    },
    "negativeInterests": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "prev": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string",
                      "description": "ISO 8601文字列。JST深夜0時を指すため \"...T15:00:00.000Z\" は翌日のJST日付を表す"
                    },
                    "holiday": {
                      "type": "boolean"
                    },
                    "exceeded": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "貸株超過株数"
                    },
                    "negativeInterestPerDiem": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "逆日歩(品貸料) 円/株の文字列。lendingDays日分の合計"
                    },
                    "balancePrice": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "逆日歩算出時の建値(株価) 円"
                    },
                    "loanBalance": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "lendingBalance": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "lendingDays": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "逆日歩の対象日数(通常1、月またぎ等で複数)"
                    },
                    "highestNegativeInterestPerDiem": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "その日の最高逆日歩 円/株"
                    }
                  },
                  "required": [
                    "date",
                    "holiday"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ],
              "description": "前回権利付最終日の逆日歩(1件)"
            },
            "worst10": {
              "type": "array",
              "items": {
                "$ref": "#/properties/negativeInterests/anyOf/0/properties/prev/anyOf/0"
              },
              "description": "過去の逆日歩ワースト10(逆日歩/日 の降順)"
            },
            "latest": {
              "type": "array",
              "items": {
                "$ref": "#/properties/negativeInterests/anyOf/0/properties/prev/anyOf/0"
              },
              "description": "直近10日"
            }
          },
          "required": [
            "worst10",
            "latest"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "sections に \"negativeInterests\" を指定し、この銘柄の逆日歩履歴データが存在するときだけ付く"
    },
    "remainingHistories": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "prev": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "lendingType": {
                    "type": "string",
                    "enum": [
                      "both",
                      "buying_only",
                      "none"
                    ]
                  },
                  "date": {
                    "type": "string"
                  },
                  "holiday": {
                    "type": "boolean"
                  },
                  "status": {
                    "type": "object",
                    "additionalProperties": {},
                    "description": "証券会社別の一般信用在庫ステータス(生データ)"
                  }
                },
                "required": [
                  "lendingType",
                  "date",
                  "holiday",
                  "status"
                ],
                "additionalProperties": false
              },
              "description": "前回権利付最終日の前3ヶ月"
            },
            "latest": {
              "type": "array",
              "items": {
                "$ref": "#/properties/remainingHistories/anyOf/0/properties/prev/items"
              },
              "description": "直近1ヶ月"
            }
          },
          "required": [
            "prev",
            "latest"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "sections に \"remainingHistories\" を指定し、この銘柄の一般信用在庫推移データが存在するときだけ付く"
    },
    "notes": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "要求されたsectionの一部が取得できなかった場合の理由"
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "銘柄が見つからない場合のメッセージ。このときcode以外の他フィールドは付かない"
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

株主優待クロス取引(現物買い+信用売りを同時に建てて優待だけ受け取る手法)の手数料を試算する。 【対象範囲】 ・同一証券会社内で「買い」と「売り」の両方を建てるケースのみを計算する。証券会社をまたいだ 組み合わせ(例: 楽天で買ってカブコムで売る)は計算しない。 ・buyMethod: 'spot'=現物買い(sbi/gmo/rakuten/kabucom) / 'system_margin_then_receipt'=制度信用買い+現引き(smbcのみ) ・sellMethod: 'general_short'=一般信用(短期) / 'general_long'=一般信用(無期限・長期) / 'system'=制度信用 ユーザーへの回答時はこれらの値をそのまま出さず、日本語(現物買い、制度信用買い+現引き、短期一般信用、 無期限一般信用、制度信用)に訳して説明すること。 【sellMethod=systemの行について】 逆日歩(金額が事前に確定しない追加費用)が別途発生しうる。total はあくまで「逆日歩が0だった場合の金額」 であり、確定額ではないことを必ず説明すること。前回の逆日歩率が分かる場合は note に参考値として付くが、 将来の逆日歩を予測するものではない。 【note フィールドについて】 一般信用の売り建てが現在できない・残数が無い証券会社も除外せず参考値として計算し、その旨を note に 記載する。note が無い行は現時点で実際にクロス可能。 【日付フィールドについて】 vestingDate=権利確定日(基準日)、lastDayWithRights=権利付最終日、exRightsDate=権利落ち日。 ユーザーが「いつまでに買えばいいか」を知りたいときは lastDayWithRights を案内すること (vestingDate は権利が確定する日そのものであり、買い付けの締切ではない)。 【assumptions フィールドについて】 実際に使用した証券会社プラン設定(ゼロ革命の有無、楽天のコース、カブコムの大口優遇ランク等)を毎回 そのまま返す。呼び出し側のAIは回答時に必ずこの内容(特にユーザーによって異なりうる設定)を明示し、 実際の契約プランと違う場合は指定し直せることを案内すること。 例:「楽天は"ゼロコース"、カブコムは大口優遇なしを前提に計算しています。異なるプランをご利用でしたら教えてください」

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "銘柄コード。例: \"7476\""
    },
    "units": {
      "type": "number",
      "description": "クロスする株数。省略時は minRequiredUnits(優待に必要な最小株数)を使う"
    },
    "price": {
      "type": "number",
      "description": "実勢株価を上書きする場合に指定。省略時は取得済みの概算株価を使う"
    },
    "date": {
      "type": "string",
      "description": "約定日 (YYYY-MM-DD)。省略時は「今注文したとき」の約定日を自動算出する(JST 15:30より前なら当日、以降なら翌営業日。土日祝ならさらに翌営業日まで繰り上げる)"
    },
    "sbiVip": {
      "type": "boolean",
      "description": "SBI大口優遇(建玉5億円以上)。既定false"
    },
    "sbiZeroRevolution": {
      "type": "boolean",
      "description": "SBIゼロ革命(電子交付設定)。既定true"
    },
    "gmoVip": {
      "type": "boolean",
      "description": "GMO VIPプラン。既定false"
    },
    "rakutenCourse": {
      "type": "string",
      "enum": [
        "zero",
        "chowari"
      ],
      "description": "楽天のコース。既定\"zero\"(ゼロコース)"
    },
    "rakutenVip": {
      "type": "boolean",
      "description": "楽天大口優遇。既定false"
    },
    "rakutenPreferentialRate": {
      "type": "boolean",
      "description": "楽天優遇金利適用。既定false"
    },
    "kabucomSor": {
      "type": "boolean",
      "description": "カブコムSOR(スマート・オーダー・ルーティング)。既定false"
    },
    "kabucomLargeLot": {
      "type": "string",
      "enum": [
        "crown",
        "diamond",
        "sapphire",
        "platinum",
        "gold",
        "silver",
        "none"
      ],
      "description": "カブコム大口優遇ランク。既定\"none\""
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "crossUnit": {
      "type": "number",
      "description": "クロスする株数"
    },
    "price": {
      "type": "number",
      "description": "計算に使った株価(円)。入力のpriceを省略した場合は取得済みの概算株価(現在の正確な株価ではない)を使う"
    },
    "totalPrice": {
      "type": "number",
      "description": "price × crossUnit"
    },
    "tradeDate": {
      "type": "string",
      "description": "約定日 (YYYY-MM-DD)"
    },
    "vestingDate": {
      "type": "string",
      "description": "権利確定日(基準日)"
    },
    "lastDayWithRights": {
      "type": "string",
      "description": "権利付最終日。買い付けの締切はこちら(vestingDateではない)"
    },
    "exRightsDate": {
      "type": "string",
      "description": "権利落ち日。クロスの決済(現渡し等)を入れる日"
    },
    "interestDays": {
      "type": "number",
      "description": "信用金利/貸株料の対象日数"
    },
    "managementFeeMonths": {
      "type": "number",
      "description": "事務管理費がかかる月数"
    },
    "assumptions": {
      "type": "object",
      "properties": {
        "sbiVip": {
          "type": "boolean",
          "description": "SBI大口優遇の前提"
        },
        "sbiZeroRevolution": {
          "type": "boolean",
          "description": "SBIゼロ革命(電子交付設定)の前提"
        },
        "gmoVip": {
          "type": "boolean",
          "description": "GMO VIPプランの前提"
        },
        "rakutenCourse": {
          "type": "string",
          "enum": [
            "zero",
            "chowari"
          ],
          "description": "楽天のコースの前提"
        },
        "rakutenVip": {
          "type": "boolean",
          "description": "楽天大口優遇の前提"
        },
        "rakutenPreferentialRate": {
          "type": "boolean",
          "description": "楽天優遇金利適用の前提"
        },
        "kabucomSor": {
          "type": "boolean",
          "description": "カブコムSORの前提"
        },
        "kabucomLargeLot": {
          "type": "string",
          "enum": [
            "crown",
            "diamond",
            "sapphire",
            "platinum",
            "gold",
            "silver",
            "none"
          ],
          "description": "カブコム大口優遇ランクの前提"
        }
      },
      "required": [
        "sbiVip",
        "sbiZeroRevolution",
        "gmoVip",
        "rakutenCourse",
        "rakutenVip",
        "rakutenPreferentialRate",
        "kabucomSor",
        "kabucomLargeLot"
      ],
      "additionalProperties": false,
      "description": "実際に使用した証券会社プラン設定"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "broker": {
            "type": "string",
            "enum": [
              "sbi",
              "gmo",
              "rakuten",
              "kabucom",
              "smbc"
            ]
          },
          "buyMethod": {
            "type": "string",
            "enum": [
              "spot",
              "system_margin_then_receipt"
            ],
            "description": "spot=現物買い(sbi/gmo/rakuten/kabucom) / system_margin_then_receipt=制度信用買い+現引き(smbcのみ)"
          },
          "sellMethod": {
            "type": "string",
            "enum": [
              "general_short",
              "general_long",
              "system"
            ],
            "description": "general_short=一般信用「短期」 / general_long=一般信用「無期限・長期」 / system=制度信用"
          },
          "buyCommission": {
            "type": "number",
            "description": "買い注文の取引手数料(円)"
          },
          "buyInterest": {
            "type": "number",
            "description": "買い建て分の信用金利(円)。現物買いの証券会社は常に0"
          },
          "sellCommission": {
            "type": "number",
            "description": "売り注文の取引手数料(円)"
          },
          "sellInterest": {
            "type": "number",
            "description": "売り建て分の信用金利/貸株料(円)"
          },
          "lendingInterest": {
            "type": "number",
            "description": "buyInterest + sellInterest"
          },
          "managementFee": {
            "type": "number",
            "description": "信用売り建玉の事務管理費(名義書き換え料)(円)"
          },
          "premiumFee": {
            "type": "number",
            "description": "プレミアム料(円)。カブコムの一般信用(無期限)のみ非ゼロ"
          },
          "total": {
            "type": "number",
            "description": "この行(証券会社×売り方式)の合計コスト(円)"
          },
          "note": {
            "type": "string",
            "description": "参考値である旨の注記(一般信用の取扱なし/残数なし/制度信用の逆日歩リスク等)。無ければ現時点で実際にクロス可能"
          }
        },
        "required": [
          "broker",
          "buyMethod",
          "sellMethod",
          "buyCommission",
          "buyInterest",
          "sellCommission",
          "sellInterest",
          "lendingInterest",
          "managementFee",
          "premiumFee",
          "total"
        ],
        "additionalProperties": false
      },
      "description": "証券会社×売り方式ごとの手数料内訳。totalの昇順"
    },
    "message": {
      "type": "string",
      "description": "計算できなかった場合の理由。このときcode以外の他フィールドは付かない"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

権利日を入力すると、クロス取引に必要な各種日付・日数を計算して返す。 【入力 vestingDate】 ・"2026-09-30" のような具体的な日付(その年で固定) ・"9月末" / "09" / "9"（月のみ）→ その月末で、次に到来する回 ・"9月20日" / "09-20" / "9/20" / "0920" → その日で、次に到来する回 【tradeDate】省略時は「今注文したとき」の約定日(JST 15:30より前なら当日、以降なら翌営業日、 土日祝はさらに繰り上げ)。「今から」系の日数(interestDays 等)はこの日を起点にする。 【返す主なフィールド】 ・vestingDate: 権利確定日(基準日) ・lastDayWithRights: 権利付最終日 ・exRightsDate: 権利落ち日 ・interestDays: 今建てた場合の信用金利/貸株料の対象日数(決済が間に合わなければ -1) ・negativeInterestDays: 逆日歩の対象日数(権利付最終日が金曜だと土日を挟んで増える) ・managementFeeMonths: 信用売り建玉の事務管理費がかかる月数 ・crossable: 今から建てて権利落ち日までに決済が間に合うか ・shortSellingLiberation: 一般信用「短期」つなぎ売りの解禁スケジュール。 - sbiGmo: SBI・GMOは同一ルール(営業日ベース、「権利落ち日を含めて15営業日前」)。 liberationDate=売建可能日、orderAcceptedFrom=その前営業日(19:00頃から新規売り注文を受付、翌営業日に先着約定)。 - rakuten: 実効権利確定日の13暦日前を求め、休場日なら翌営業日に調整して最早売建日を計算。orderAcceptedFrom=その前営業日(19時頃から受付)。実際の取扱・在庫・個別期日は別途確認。 - auカブコム・SMBC日興は短期一般信用の取扱いが無いため対象外(詳細は note 参照)。 ・prevYear: 前年の同一権利の基準日(get_benefit の negativeInterests / remainingHistories の prev データと突き合わせるのに使う) ・businessDaysUntilLastDayWithRights / calendarDaysUntilLastDayWithRights: 権利付最終日までの残り 日付は "YYYY-MM-DD" 形式の文字列で返す。

{
  "type": "object",
  "properties": {
    "vestingDate": {
      "type": "string",
      "description": "権利日。例: \"9月末\" / \"9月20日\" / \"2026-09-30\""
    },
    "tradeDate": {
      "type": "string",
      "description": "約定日 (YYYY-MM-DD)。省略時は「今」から自動算出"
    }
  },
  "required": [
    "vestingDate"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "input": {
      "type": "string",
      "description": "入力された権利日指定(正規化前の生テキスト)"
    },
    "tradeDate": {
      "type": "string",
      "description": "起点にした約定日"
    },
    "vestingDate": {
      "type": "string",
      "description": "権利確定日(基準日)"
    },
    "lastDayWithRights": {
      "type": "string",
      "description": "権利付最終日。この日までに現物を約定していれば権利が取れる"
    },
    "exRightsDate": {
      "type": "string",
      "description": "権利落ち日。クロスの決済(現渡し等)を入れる日"
    },
    "deliveredDate": {
      "type": "string",
      "description": "tradeDateの現物/信用建て分の受渡日"
    },
    "businessDaysUntilLastDayWithRights": {
      "type": "number",
      "description": "tradeDateから権利付最終日までの営業日数(tradeDate自身は除く)"
    },
    "calendarDaysUntilLastDayWithRights": {
      "type": "number",
      "description": "tradeDateから権利付最終日までの暦日数"
    },
    "interestDays": {
      "type": "number",
      "description": "今建てた場合の信用金利/貸株料の対象日数。決済が間に合わなければ-1"
    },
    "negativeInterestDays": {
      "type": "number",
      "description": "逆日歩(品貸料)の対象日数。権利付最終日が金曜だと土日を挟んで増える"
    },
    "managementFeeMonths": {
      "type": "number",
      "description": "信用売り建玉の事務管理費がかかる月数(今から権利まで)"
    },
    "crossable": {
      "type": "boolean",
      "description": "interestDays !== -1。今から建てて権利落ち日までに決済が間に合うか"
    },
    "canWeekendOrder": {
      "type": "boolean",
      "description": "今(tradeDate起点)から土日をまたぐ注文ができるか"
    },
    "shortSellingLiberation": {
      "type": "object",
      "properties": {
        "sbiGmo": {
          "type": "object",
          "properties": {
            "liberationDate": {
              "type": "string",
              "description": "売建可能日(この日ザラ場から在庫が出る)"
            },
            "orderAcceptedFrom": {
              "type": "string",
              "description": "その前営業日。19:00頃から新規売り注文を受付(翌営業日に先着約定)"
            }
          },
          "required": [
            "liberationDate",
            "orderAcceptedFrom"
          ],
          "additionalProperties": false,
          "description": "SBI・GMOは同一ルール(営業日ベース、「権利落ち日を含めて15営業日前」)"
        },
        "rakuten": {
          "type": "object",
          "properties": {
            "orderAcceptedFrom": {
              "type": "string",
              "description": "ルール上の最早売建日の前営業日。19時頃の受付目安、取扱・在庫は別途確認"
            }
          },
          "required": [
            "orderAcceptedFrom"
          ],
          "additionalProperties": false
        },
        "note": {
          "type": "string",
          "description": "auカブコム・SMBC日興は短期一般信用の取扱いが無いため対象外、等の補足"
        }
      },
      "required": [
        "sbiGmo",
        "rakuten",
        "note"
      ],
      "additionalProperties": false,
      "description": "一般信用「短期」つなぎ売りの解禁スケジュール"
    },
    "prevYear": {
      "type": "object",
      "properties": {
        "vestingDate": {
          "type": "string"
        },
        "lastDayWithRights": {
          "type": "string"
        }
      },
      "required": [
        "vestingDate",
        "lastDayWithRights"
      ],
      "additionalProperties": false,
      "description": "前年の同一権利。get_benefit の negativeInterests/remainingHistories の prev データの基準日と突き合わせるのに使う"
    }
  },
  "required": [
    "input",
    "tradeDate",
    "vestingDate",
    "lastDayWithRights",
    "exRightsDate",
    "deliveredDate",
    "businessDaysUntilLastDayWithRights",
    "calendarDaysUntilLastDayWithRights",
    "interestDays",
    "negativeInterestDays",
    "managementFeeMonths",
    "crossable",
    "canWeekendOrder",
    "shortSellingLiberation",
    "prevYear"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}