ドキュメントに戻る

BFH Forge API

API リファレンス

BFH Forge API の全エンドポイントリファレンスです。すべてのルートに OAuth2 Bearer トークンが必要です。

https://api.bravefrontierheroes.com認証必須スコープ: openid profile

概要

ベースURL

https://api.bravefrontierheroes.com

認証

Authorization: Bearer <access_token>

すべてのリクエストに、Authorization ヘッダーで有効な OAuth2 アクセストークンを Bearer トークンとして付与する必要があります。アクセストークンは、連携ガイドに記載の Authorization Code フロー（または PKCE フロー）で取得してください。

必要なスコープ: openid profile

バトルシミュレーション

バトルシミュレーション

POST/v1/battle/simulate
認証必須

アタッカーとディフェンダーが所持するアセットでステートレスなバトルを実行します。DBへの書き込みは発生しません。レスポンスにはリプレイ表示に使う battleKey が含まれます。

バトルリプレイURL

battleKey を使ってリプレイURLを組み立てます。returnUrl は必須で、あなたのサイトへ戻るURLを指定してください。

https://bravefrontierheroes.com/battle/{battleKey}?returnUrl=https://{your-site}.com

リザルトコード

0 — DRAW（引き分け）1 — WIN（アタッカー勝利）2 — LOSE（アタッカー敗北）

ステップ1 — アセットの準備

シミュレーションリクエストを組み立てる前に、各プレイヤーが所持するヒーロー・スフィアのトークンIDを把握し、必要に応じて保存済みデッキ設定を取得します。

GET/v1/me/units

認証ユーザーが所持するヒーロートークンIDの配列を返します。

GET/v1/me/spheres

認証ユーザーが所持するスフィアトークンIDの配列を返します。

GET/v1/deck/templates

保存済みデッキ設定を返します。各テンプレートはシミュレーションリクエストのボディとしてそのまま使用できます。

POST/v1/heroes

ヒーローIDからマスターデータ（ステータス・スキルリスト・エクステンション）を取得し、skill_orders や extension_ids に使用する正しい値を確認します。

GET /v1/me/units — Request

GET /v1/me/units HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>

Response

{
  "status": "OK",
  "wallet_address": "0x4D8bF583BD2DD813B5e7ddEF05f268eC33f46458",
  "count": 3,
  "units": ["200000143", "200000153", "200000159"]
}

GET /v1/me/spheres — Request

GET /v1/me/spheres HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>

Response

{
  "status": "OK",
  "wallet_address": "0x4D8bF583BD2DD813B5e7ddEF05f268eC33f46458",
  "count": 2,
  "spheres": ["30550169", "30620332"]
}

GET /v1/deck/templates — Request

GET /v1/deck/templates HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>

Response

{
  "deck_templates": [
    {
      "units": [
        { "hero_id": 200000143, "position": 0, "skill_orders": [0, 1, 2],
          "extension_ids": [30550169, 30620332, 0, 0, 0, 0], "accessory_id": 0 },
        { "hero_id": 200000153, "position": 1, "skill_orders": [0, 1, 2],
          "extension_ids": [], "accessory_id": 0 }
      ]
    }
  ],
  "quest_deck_templates": []
}

POST /v1/heroes — Request

POST /v1/heroes HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "hero_ids": [200000143, 200000153]
}

ステップ2 — リクエストの構築

アタッカーとディフェンダーの UID および各サイド最大5体のデッキユニットを指定します。各ユニットは以下の SimulateDeckUnitRequest スキーマで定義します。

SimulateDeckUnitRequest

FieldTypeDescription
hero_idintegerヒーローアセットのトークンID（GET /v1/me/units から取得）。対応するUIDのプレイヤーが所持するIDである必要があります。
positioninteger (0–4)デッキ内のスロットインデックス（0〜4）。各ユニットは異なる position を持つ必要があります。
skill_ordersinteger[]スキルの発動順を決める、スキルスロットインデックスの配列です。インデックスはヒーローマスターデータのスキルリストに対応します。空配列を渡すとデフォルト順が使われます。
extension_idsinteger[]エクステンションスロットに装備するスフィアのトークンIDです。各IDは対応するプレイヤーUIDが所持している必要があります。
accessory_idintegerアクセサリースロットに装備するスフィアのトークンIDです。装備なしの場合は 0 を指定します。

リクエスト

POST /v1/battle/simulate HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "attacker_uid": 12345,
  "attacker_units": [
    {
      "hero_id": 200000143,
      "position": 0,
      "skill_orders": [0, 1, 2],
      "extension_ids": [30550169, 30620332, 0, 0, 0, 0],
      "accessory_id": 0
    },
    {
      "hero_id": 200000153,
      "position": 1,
      "skill_orders": [0, 1, 2],
      "extension_ids": [],
      "accessory_id": 0
    }
  ],
  "defender_uid": 67890,
  "defender_units": [
    {
      "hero_id": 200000159,
      "position": 0,
      "skill_orders": [0, 1, 2],
      "extension_ids": [],
      "accessory_id": 0
    }
  ]
}

ステップ3 — レスポンスの解析

レスポンスにはバトル結果、リプレイキー、バトルメタ情報、および主要カウンターが含まれます。

BattleResponse — key fields

FieldTypeDescription
resultinteger (0–2)バトル結果の整数値。0 = DRAW、1 = WIN（アタッカー）、2 = LOSE（アタッカー）。
battleKeystringホストされたバトルリプレイ画面用のキーです。https://bravefrontierheroes.com/battle/{battleKey}?returnUrl=... に組み込んで利用します。
battleTypeintegerシミュレーターで使用されたバトルタイプIDです。
attackerTakenDamagedefenderTakenDamageinteger各サイドが受けた合計ダメージ量（HP）です。
actionCountsactionLimitinteger実行アクション数と上限値です。actionCounts が actionLimit に達した場合、アクション上限で終了しています。
playerNameopponentNamestringアタッカー(playerName)とディフェンダー(opponentName)の表示名です。
uidsListinteger[]このシミュレーション結果に含まれる UID の配列です。
rulesMapobject<boolean>有効化されたバトルルールのキー・真偽値マップです。

レスポンス

{
  "result": 1,
  "battleKey": "abc-123",
  "battleType": 7,
  "attackerTakenDamage": 500,
  "defenderTakenDamage": 1000,
  "actionCounts": 50,
  "actionLimit": 100,
  "playerName": "Player1",
  "opponentName": "Player2",
  "uidsList": [12345, 67890],
  "rulesMap": {
    "rule_01": true
  }
}

ユーザーエンドポイント

GET/v1/me
認証必須

認証ユーザーのプロフィール（UID・ゲーム内名・ウォレットアドレス・土地ステータス・ギルド情報・ゲーム統計）を返します。

GET/v1/user/{id}
認証必須

数値のUIDを指定して任意のユーザーの公開プロフィールを返します。

GET/v1/user/by-address/{address}
認証必須

Ethereumウォレットアドレス（0x プレフィックス付き）でユーザーを検索します。

アセットエンドポイント

アセット管理サービス（AMS）からトークンIDを返します。取得したIDは /v1/heroes・/v1/spheres やバトルシミュレーションリクエストの入力として使用します。

GET/v1/me/units

認証ユーザーが所持するヒーロートークンIDを返します。

GET/v1/me/spheres

認証ユーザーが所持するスフィアトークンIDを返します。

ヒーロー・スフィア（マスターデータ）

ヒーローとスフィアのゲームマスターデータを取得します。IDsの配列を空にすると全件取得できます。

GET/v1/hero/{id}

ヒーロー1体のマスターデータ（基本ステータス・属性・スキルリスト・利用可能なエクステンションスロット）を返します。

POST/v1/heroes

複数ヒーローのマスターデータをまとめて取得します。hero_ids を省略または空配列にすると全ヒーローを返します。

GET/v1/sphere/{id}

スフィア1個のマスターデータを返します。

POST/v1/spheres

複数スフィアのマスターデータをまとめて取得します。sphere_ids を省略または空配列にすると全スフィアを返します。

デッキテンプレート

GET/v1/deck/templates

認証ユーザーが保存したデッキ設定（通常デッキ・クエストデッキの両方）を返します。各テンプレートはユニットリストが完全に構成されており、シミュレーションリクエストにそのまま利用できます。

リクエスト

GET /v1/deck/templates HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>

レスポンス

{
  "deck_templates": [
    {
      "units": [
        { "hero_id": 200000143, "position": 0, "skill_orders": [0, 1, 2],
          "extension_ids": [30550169, 30620332, 0, 0, 0, 0], "accessory_id": 0 },
        { "hero_id": 200000153, "position": 1, "skill_orders": [0, 1, 2],
          "extension_ids": [], "accessory_id": 0 }
      ]
    }
  ],
  "quest_deck_templates": []
}

ランクマッチ

GET/v1/rankmatches

進行中のランクマッチイベントIDを一覧します。status=finished を渡すと終了済みイベントも含めて返します。

GET/v1/rankmatches/{id}/history

指定のランクマッチにおける認証ユーザーのバトル履歴ログを返します。

GET/v1/rankmatches/{id}/me

指定のランクマッチにおける認証ユーザーの順位・スコア・参加状況を返します。

GET/v1/rankmatches/{id}/participants

ランクマッチの全参加者をページネーション形式で返します。offset と limit パラメータに対応（最大1000件）。

GET /v1/rankmatches — Request

GET /v1/rankmatches?status=ongoing HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>

レスポンス

[101, 102, 103]

プレイヤーマッチ

GET/v1/playermatches

現在進行中の公開プレイヤー対戦ルームのパスワード一覧を返します。

トレード

GET/v1/trade/hero

現在出品中のヒーロートレード一覧をフィルタリング・ソートつきで返します。rarity_filter・status_filter・param_filter・uid・asset_id・sort_type・sort_order・attribute_filter・offset・limit に対応。

status_filter 値: 0=EXHIBITION、1=TRADE、2=DONE、3=CANCELLED、4=EXPIRED、5=TRANSACTION

sort_type 値: 0=NEW、1=GUM_LOW、2=GUM_HIGH、3=CE_LOW、4=CE_HIGH、5=RARITY、6=LV、7=HP、8=ATK、9=MAG、10=DEF、11=MDEF、12=AGI

リクエスト

GET /v1/trade/hero?limit=10&sort_type=0&sort_order=1 HTTP/1.1
Host: api.bravefrontierheroes.com
Authorization: Bearer <access_token>
GET/v1/trade/sphere

ヒーロートレードと同一のフィルタリング・ソートオプションでスフィアトレード一覧を返します。

BFH Developer Portal