概要
PlayMiningスカラーシップの概要については、スカラーシップ管理をご覧ください。
PlayMiningスカラーシップでは、OpenAPIにて契約の締結や解約、契約状況の確認を行うAPIを用意しています。
PMPと連携するゲームはこのAPIを利用することで、契約期間や貸与可能なNFT、チャレンジできるステージやクエスト、報酬条件などを自由に設計し、契約ページの仕様も含めゲームに最適化したスカラーシップ機能を提供することが可能となります。
スカラーシップ機能を提供する方法について、仕様や実装方法や注意点を説明致します。
仕様
OpenAPIの仕様
PlayMiningスカラーシップの主な仕様に加えて、以下の仕様で提供しています。
- 専用ページとはデータベースが異なるため、契約情報はOpenAPIを使ってのみ確認可能です。
- APIリクエストはホワイトリストで制限をかけています。ゲーム側でリクエストを行うバックエンドのIPアドレスを許可することで利用可能となります。
graph LR
user([ユーザー])
subgraph "スカラーシップ"
sv[APIサーバー]
end
subgraph "ゲーム"
fe[フロントエンド]
be[バックエンド]
end
user --> fe
fe --> be
be --IPアドレスを許可した上でリクエスト--> sv
sv --事前にゲーム側バックエンドのIPアドレスを許可--> sv
利用規約
利用規約は４か国語（英語、日本語、インドネシア語、繁体字）で提供しています。
初回利用者が合意する利用規約は、以下URLより取得し、言語に合わせて表示してください。
※利用規約のURLは、ユーザー情報取得APIのレスポンスにも入っております。
環境情報
環境名 | エンドポイント |
開発環境 | http://13.112.209.191:3000 |
検証環境 | https://api.stg.scholarship.playmining.com |
本番環境 | https://api.scholarship.playmining.com |
検証環境と本番環境はHTTPSリクエストです。HTTPリクエストはエラーとなります。
API仕様書(swagger)
URL：http://52.195.58.81/
Basic認証ユーザー名：view
Basic認証パスワード：scholarship
提供APIについて
一部のAPIは内部的に別APIをリクエストします。
そのAPIでエラーとなった場合は、そのAPIのエラーコードをゲームへ返します。そのためスカラーシップのエラーとは内容が異なる場合があります。
リクエストに必要な、ヘッダーのAuthorizationやパラメータのcontents_idは、PMPにて払い出したものを指定してください。（PMPへのリクエストと同様にAuthorizationやcontents_idをご指定ください。）
ヘッダー情報 | |
Content-type | application/json |
Authorization | Bearer [APIKEY] |
ユーザー登録API
/users（POST）
スカラーシップシステム上でユーザー（PMID）を登録するAPIです。
ユーザー登録完了により、利用規約に同意したものとみなされ、スカラーシップ機能を利用可能となります。
この登録がされない限りユーザーはスカラーシップを利用することができませんので、スカラーシップ機能提供時には、確実に利用規約同意の処理を行いユーザー登録を行ってください。
また、後述のPlayMiningスカラーシップOpenAPIを利用する にも記載しておりますが、利用規約が更新された後、ユーザーが最新の利用規約に同意されていない場合は、改めてユーザーへ利用規約への同意を促してください。
同意後に本APIをリクエストすることで最新バージョンに同意したこととなります。
パラメータに関しては、特段複雑な仕様はないため割愛します。
ユーザー情報取得API
/users/detail（GET）
スカラーシップの利用規約に同意済みであるユーザーの情報を取得するAPIです。
ユーザーの利用規約同意状況や、オーナーまたはスカラーとしての総獲得DEP額、昨日獲得したDEP額を返します。
後述のPlayMiningスカラーシップOpenAPIを利用する にも記載しておりますが、利用規約が更新された際には、レスポンスパラメータのagreed_versionとlatest_versionが不一致となりますので、その際は再度ユーザーへ利用規約への同意を促してください。
- リクエスト
特段複雑な仕様はないため割愛します。
- レスポンス
パラメータ | 内容 |
user | |
agreed_version | 同意済みの利用規約バージョンです。 |
owner_dep_balance | オーナーとしての総獲得DEP額です。 |
scholar_dep_balance | スカラーとしての総獲得DEP額です。 |
owner_yesterday_dep_balance | オーナーとしての昨日獲得したDEP額です。 |
scholar_yesterday_dep_balance | スカラーとしての昨日獲得したDEP額です。 |
terms | |
latest_version | リクエスト時点での利用規約の最新バージョン情報です。 |
url | S3に格納されている最新利用規約のURLです。 |
契約一覧取得API
/contracts（GET）
ユーザーの過去すべての契約を一覧で取得するAPIです。
貸借対象NFT、オーナー/スカラー情報、契約日/更新日などを返します。
ページャーを導入しています。
- リクエスト
パラメータ | 内容 |
uid | ユーザーのPMIDです。 |
limit | （任意）1ページあたりで取得する契約数です。 |
page | （任意）取得するページ番号です。
limit=2, page=2の場合、過去から遡って3,4件目の契約情報を取得します。
limit=10, page=1の場合、過去から遡って10件目までの契約情報を取得します。 |
- レスポンス
パラメータ | 内容 |
contract_id | 1契約あたりに採番される契約IDです。
後続の成約、取り下げ、拒否、解約、契約詳細確認にはこの情報が必要です。 |
nfts | |
token_id | トークンIDです。 |
url | トークン画像のURLにです。 |
owner_uid | オーナーのPMIDです。 |
scholar_uid | スカラーのPMIDです。 |
owner_ratio | オーナーの分配率です。 |
owner_earned | オーナーとしての総獲得DEP額です。 |
scholar_earned | オーナーとしての総獲得DEP額です。 |
current_status | 現在のステータスです。 |
created_at | 契約登録された日時です。 |
contracted_at | 成約された日時です。 |
updated_at | 契約ステータスが更新された日時です。 |
契約登録API
/contracts（POST）
オーナーが指定する条件で契約を登録する際に利用するAPIです。
DBに契約レコードを追加し、契約ステータスを「Applied（契約申請中）」にします。
このタイミングで、オーナーが所持する貸出対象NFTはトークンロックされます。
この処理によってDBに契約が存在しなければ、後述のPlayMiningスカラーシップOpenAPIを利用する を直接叩いてもエラーとなります。
前述の通り、契約IDで管理されているため、ゲーム側でも契約IDを保持してください。
- リクエスト
パラメータ | 内容 |
owner_uid | オーナーのPMIDです。 |
scholar_uid | （任意）スカラーのPMIDです。 |
nfts | 貸出NFTの配列です。配列で指定し、要素はStringで指定してください。
貸出可能ではないNFT（貸出中、出品中）が含まれる場合はエラーとなります。 |
owner_ratio | オーナーの分配率です。 |
- レスポンス
パラメータ | 内容 |
contract_id | 契約IDです。 |
成約API
/contracts（PATCH）
スカラーが契約合意し、成約となる際に利用するAPIです。
「Applied（契約申請中）」の契約ステータスを「Active（契約中）」に更新します。
契約中NFT一覧APIにてスカラーのPMIDでリクエストすることで、借用したNFTのトークン情報が取得可能です。
- リクエスト
パラメータ | 内容 |
contract_id | 1契約あたりに採番される契約IDです。
契約登録時に採番されたIDを入力してください。 |
scholar_uid | スカラーのPMIDです。 |
- レスポンス
特段複雑な仕様はないため割愛します。
解約API
/contracts/cancel
契約を終了する際に利用するAPIです。
「Active（契約中）」の契約ステータスを「Terminated（解約済み）」に更新します。
オーナーが所持する貸出対象NFTのトークンロックを解除し、利用可能にします。
解約後での契約情報の更新は不可能です。
パラメータに関しては、特段複雑な仕様はないため割愛します。
契約拒否API
/contracts/reject
スカラーがオーナーの契約申請を拒否する際に利用するAPIです。
「Applied（契約申請中）」の契約ステータスを「Declined（契約拒否）」に更新します。
オーナーが所持する貸出対象NFTのトークンロックを解除し、利用可能にします。
契約拒否後での契約情報の更新は不可能です。
パラメータに関しては、特段複雑な仕様はないため割愛します。
契約取り下げAPI
/contracts/withdraw
オーナーが契約申請を取り下げる際に利用するAPIです。
「Applied（契約申請中）」の契約ステータスを「Withdrawn（契約取り下げ）」に更新します。
オーナーが所持する貸出対象NFTのトークンロックを解除し、利用可能にします。
契約取り下げ後での契約情報の更新は不可能です。
パラメータに関しては、特段複雑な仕様はないため割愛します。
契約ステータス更新確認API
/contracts/updated-status
ゲーム内でユーザーに通知をする際に利用するAPIです。
特定期間内で契約ステータスに更新があった契約情報を返します。
- リクエスト
パラメータ | 内容 |
uid | ユーザーのPMIDです。 |
from | 取得期間の開始日時です。 |
to | （任意）取得期間の終了日時です。 |
- レスポンス
パラメータ | 内容 |
contracts | |
contract_id | 契約IDです。 |
update_at | 更新された日時です。 |
updated_status | 更新後の契約ステータスです。 |
単一契約詳細確認API
/contracts/{contract_id}/detail
契約情報を詳しく表示する際に利用するAPIです。
契約一覧取得APIと類似した情報に加え、いつ/誰に/どれほどの報酬が付与されたかを返します。
- リクエスト
パラメータ | 内容 |
contract_id | 契約IDです。bodyでの指定ではなく、URLに入力してリクエストします。 |
- レスポンス
パラメータ | 内容 |
nfts | |
token_id | トークンIDです。 |
url | トークン画像のURLにです。 |
owner_uid | オーナーのPMIDです。 |
scholar_uid | スカラーのPMIDです。 |
owner_earned | オーナーとしての総獲得DEP額です。 |
scholar_earned | オーナーとしての総獲得DEP額です。 |
current_status | 現在のステータスです。 |
history | |
record_id | 報酬分配履歴IDです。 |
owner_reward | 報酬分配履歴IDに紐づくオーナー獲得DEP額です。 |
scholar_reward | 報酬分配履歴IDに紐づくスカラー獲得DEP額です。 |
created_at | 報酬分配日時です。 |
分配率取得API
オーナーとスカラーの報酬額を算出する際に利用するAPIです。
オーナーPMID、スカラーPMID、オーナー分配率のみをレスポンスとして返します。
契約一覧取得APIや単一契約詳細確認APIにも同様の情報が含まれていますが、リクエストの負荷を抑えるために別途APIにしています。
報酬分配時にはこちらのAPIを利用していただきますようお願いいたします。
パラメータに関しては、特段複雑な仕様はないため割愛します。
分配報酬共有API
オーナー/スカラーへの報酬支払いが完了したタイミングで、スカラーシップシステム側に報酬額を連携する際に利用するAPIです。
スカラーシップシステムでは、ユーザーごとに獲得日時と獲得DEP額を集計し、単一契約詳細確認APIなどで返しています。
この情報共有があることで、ユーザーはどれほど稼ぐことができたのかを把握することができるため、報酬支払い後は必ずこのAPIで情報を共有いただきますようお願いいたします。
- リクエスト
パラメータ | 内容 |
contract_id | 契約IDです。 |
uid | 報酬を支払ったユーザーのPMIDです。 |
amount | 支払った報酬額です。 |
- レスポンス
特段複雑な仕様はないため割愛します。
契約ステータスの遷移について
flowchart TD
start([未契約]) ==オーナーが契約申請する==> applied[契約申請中]
applied ==オーナーが取り下げる==> withdrawn[契約取り下げ]
applied ==スカラーが受理する==> active[契約中] ==オーナー又はスカラーが解約申請する==> terminated[解約済み]
applied ==スカラーが契約を拒否する==> declined[契約拒否]
実装方法
スカラーシップ機能利用開始
スカラーシップを利用するためには、前述の通り、PlayMiningスカラーシップOpenAPIを利用する への同意が必要です。
ユーザーがスカラーシップを利用する（ゲーム内スカラーシップページへアクセスした）タイミングで、ユーザー情報取得APIをリクエストしてください。
「未登録」または「agreed_version」が「latest_version」と一致しない場合は、最新の利用規約を表示し、同意を促してください。
ユーザーが同意をした際に、ユーザー登録APIをリクエストしてください。
その後、再度ユーザー情報取得APIをリクエストし、「agreed_version」が「latest_version」と一致していることを確認の上、ゲーム内スカラーシップページへの遷移行ってください。
sequenceDiagram
autonumber
Actor user
participant game as ゲーム
participant shs as スカラーシップ
participant pmp as PMP
user ->>+ game: ゲーム内スカラーシップページアクセス
game ->>+ shs: ユーザー情報取得APIリクエスト
shs -->>- game: レスポンス（ユーザー情報）
alt 未登録または最新利用規約未同意の場合
game ->>+ shs: 利用規約html取得
shs -->>- game: 利用規約情報レスポンス
game -->> user: 利用規約表示
user ->> game: 利用規約同意
game ->>+ shs: ユーザー登録APIリクエスト
shs ->> shs: ユーザー情報更新
shs -->>- game: レスポンス
game ->>+ shs: ユーザー情報取得APIリクエスト
shs -->>- game: レスポンス（ユーザー情報）
end
game ->> game: 最新利用規約同意済みバリデーション
game -->>- user: ゲーム内スカラーシップページ表示
契約登録〜成約までの流れ
オーナーとスカラーが確定している場合
PlayMiningスカラーシップは、NFT貸借の契約を管理するところまでを役割として担っています。
制約（「このNFTは貸し出せない」「契約期間」など）を掛ける場合はゲーム側でハンドリングしてください。
スカラーシップ管理 にも記載していますが、契約申請はNFTを所持しているオーナーから実施します。
契約申請があった際には、PlayMiningスカラーシップOpenAPIを利用する をリクエストしてください。
スカラーが契約に合意した際に、PlayMiningスカラーシップOpenAPIを利用する をリクエストしてください。
成約APIが正常に処理されると、スカラーにて該当NFTが利用可能となります。
sequenceDiagram
autonumber
Actor owner
Actor scholar
participant game as ゲーム
participant shs as スカラーシップ
participant pmp as PMP
owner ->>+ game: ゲーム内スカラーシップページにて契約申請
game ->>+ shs: 契約登録APIリクエスト
shs ->> shs: DBへ契約情報登録（Applied）
shs ->>+ pmp: オーナー貸出対象NFTトークンロック
pmp -->>- shs: レスポンス
shs -->>- game: レスポンス（契約ID）
game -->>- owner: 契約申請完了表示
scholar ->>+ game: ゲーム内スカラーシップページにて契約合意
game ->>+ shs: 成約APIリクエスト
shs ->> shs: DBへ契約情報更新（Active）
shs ->>+ pmp: 貸出対象NFTの利用者更新
pmp -->>- shs: レスポンス
shs -->>- game: レスポンス
game -->>- owner: 成約完了表示
スカラー公募の場合
オーナーがスカラーを募集する形で契約登録することも可能です。
PlayMiningスカラーシップOpenAPIを利用する をリクエスト時に、スカラーPMIDは入力せずにリクエストしてください。
ゲーム内でスカラーが契約を探して合意したタイミングでPlayMiningスカラーシップOpenAPIを利用する をリクエストしてください。
sequenceDiagram
autonumber
Actor owner
Actor scholar
participant game as ゲーム
participant shs as スカラーシップ
participant pmp as PMP
owner ->>+ game: ゲーム内スカラーシップページにて契約申請
game ->>+ shs: 契約登録APIリクエスト（スカラーPMIDなし）
shs ->> shs: DBへ契約情報登録（Applied）
shs ->>+ pmp: オーナー貸出対象NFTトークンロック
pmp -->>- shs: レスポンス
shs -->>- game: レスポンス（契約ID）
game -->>- owner: 契約申請完了表示
scholar ->>+ game: 契約を検索し適当な契約に合意
game ->>+ shs: 成約APIリクエスト
shs ->> shs: DBへ契約情報更新（Active）
shs ->>+ pmp: 貸出対象NFTの利用者更新
pmp -->>- shs: レスポンス
shs -->>- game: レスポンス
game -->>- owner: 成約完了表示
契約状況の表示について
契約ステータスが更新された際のゲーム内での通知やゲーム内スカラーシップページでの契約ステータスを確認することも可能です。
ゲームに通知機能がある場合は、PlayMiningスカラーシップOpenAPIを利用する を用いて、ステータスに更新があった旨をユーザーに通知していただいても構いません。
また、ゲーム内スカラーシップページで契約一覧を表示する場合は、PlayMiningスカラーシップOpenAPIを利用する やPlayMiningスカラーシップOpenAPIを利用する を用いて、情報を表示してください。
下記シーケンス図は例です。ゲームのページ構成などによって適宜検討ください。
sequenceDiagram
autonumber
Actor user
participant game as ゲーム
participant shs as スカラーシップ
user ->>+ game: ゲームメインページへ遷移
game ->>+ shs: 契約ステータス更新確認APIリクエスト
shs -->>- game: レスポンス（ステータスに更新があった契約情報）
game -->>- user: 契約情報を通知などで表示
user ->>+ game: スカラーシップ契約一覧ページ
game ->>+ shs: 契約一覧取得APIリクエスト
shs -->>- game: レスポンス（契約一覧情報）
game -->>- user: 契約一覧表示
user ->>+ game: 契約情報を選択
game ->>+ shs: 単一契約詳細確認APIリクエスト
shs -->>- game: レスポンス（契約詳細情報）
game -->>- user: 契約詳細表示
解約、契約拒否、契約取り下げについて
APIをリクエストして完了となります。
それぞれのAPIは、ステータス管理の観点でAPIを分けていますが、処理自体は変わりません。
注意点として、解約/契約拒否/契約取り下げは、リクエスト後に即時解約、即時NFT返還となります。特に解約処理において、デイリータスクなどを実装している場合は、即時解約後に別スカラーが即時契約、を繰り返すことによって、オーナーがデイリータスク報酬を乱獲するなどの不正行為に繋がる恐れがあるのでご注意ください。
解約は、契約ステータスが「Active（契約中）」の場合のみ可能です。
契約拒否/契約取り下げは、契約ステータスが「Applied（契約申請中）」の場合にのみ可能であり、拒否はスカラーから、取り下げはオーナーから申請する仕様です。このAPIリクエストを間違えると、契約一覧を取得した際に意図しないステータスでレスポンスが返りますのでご注意ください。前述のとおり、これらのステータス遷移後にステータスを更新することは原則できません。
sequenceDiagram
autonumber
Actor owner
Actor scholar
participant game as ゲーム
participant shs as スカラーシップ
participant pmp as PMP
alt オーナーが契約を取り下げる場合
owner ->>+ game: 契約取り下げ申請
game ->>+ shs: 契約取り下げAPIリクエスト
shs ->> shs: 契約情報更新（Withdrawn）
shs ->>+ pmp: オーナー貸出対象NFTトークンアンロック
pmp -->>- shs: レスポンス
shs -->>- game: レスポンス
game -->>- owner: 契約取り下げ完了表示
else スカラーが契約を拒否する場合
scholar ->>+ game: 契約拒否申請
game ->>+ shs: 契約拒否APIリクエスト
shs ->> shs: 契約情報更新（Declined）
shs ->>+ pmp: オーナー貸出対象NFTトークンアンロック
pmp -->>- shs: レスポンス
shs -->>- game: レスポンス
game -->>- scholar: 契約拒否完了表示
else 契約を解約する場合
owner ->>+ game: オーナーまたはスカラーから解約申請
game ->>+ shs: 解約APIリクエスト
shs ->> shs: DBへ契約情報登録（Terminated）
shs ->>+ pmp: オーナー貸出対象NFTトークンアンロック
pmp -->>- shs: レスポンス
shs -->>- game: レスポンス
game -->>- owner: 解約完了表示
end
ゲームプレイ（クエストクリア）による報酬配布
スカラーが報酬を受け取る条件をクリアした際に、契約の分配率に応じてオーナーとスカラーに報酬を分配します。
PlayMiningスカラーシップOpenAPIを利用する をリクエストし、レスポンスのowner_ratioをもとにオーナー獲得額とスカラー獲得額を算出し、DEP付与APIにて報酬を支払ってください。
報酬計算時の小数点に関しては、特に取り決めはありません（小数点第18位まで可能）。
ちなみにスカラーシップ専用ページを利用しているゲームでは、現時点で少数第3位まで（小数点第4位で四捨五入）として分配しています。
報酬支払い後は、スカラーシップシステム側で報酬額を管理するため、オーナーとスカラーそれぞれのPMIDでPlayMiningスカラーシップOpenAPIを利用する をリクエストしてください。
シーズン制の場合は、シーズン終了のタイミングで分配率取得API、DEP付与API、分配報酬共有APIをリクエストしてください。
sequenceDiagram
autonumber
actor owner
participant ownerwallet as オーナーウォレット
actor scholar
participant scholarwallet as スカラーウォレット
participant game as ゲーム
participant scholarship as スカラーシップ
participant pmp as PMP
scholar ->>+ game: ゲーム内でのクエストクリア
game ->> scholar: クエストクリア画面など表示
game ->>+ scholarship: 単一契約詳細確認APIリクエスト
scholarship -->>- game: 契約情報（owner_ratio）
game ->>+ game: オーナー/スカラーの報酬額算出
game ->> pmp: スカラーPMIDでDEP付与APIリクエスト
pmp ->> scholarwallet: スカラーのウォレットへDEP入金
game ->> scholarship: スカラーPMIDで分配報酬共有APIリクエスト
game ->> pmp: オーナーPMIDでDEP付与APIリクエスト
pmp ->> ownerwallet: オーナーのウォレットへDEP入金
game ->> scholarship: オーナーPMIDで分配報酬共有APIリクエスト
