NasuCoin Connect API

認証とデータ形式

要求と応答はJSONです。変更操作は POST、参照操作は表に記載したメソッドを使います。POSTでは Content-Type: application/json を指定してください。金額は整数NC、時刻は特記のない限りUNIX秒です。

カードなどから使う場合は、/API/Common/RequestLogin にNC IDまたはユーザー名とパスワードを送ります。返された sessionId を以降の Authorization: Bearer <SESSION_ID> に設定します。セッションはURLへ含めず、共有するカードやワールドにも保存しないでください。

POST /API/Common/RequestLogin
Content-Type: application/json

{"ncid":"NC-EXAMPLE","password":"<YOUR_PASSWORD>"}

Webサイトは mode: "web" でログインし、HttpOnly Cookieを使います。Webの変更要求には、本人の /API/Account/GetProfile で取得したCSRF値を X-CSRF-Token ヘッダーへ設定します。Cookie・CSRF方式では、ブラウザーへ秘密のセッションIDを返しません。

ブラウザーからの通信は、サイト自身またはサーバーに登録された許可Originから行います。Webの登録・ログイン・回復とCookieによる変更操作にはサイト自身のOriginが必要です。ネイティブクライアントのBearer認証では Origin を省略できます。送る場合は許可Originである必要があります。Cookieと異なるBearerを同時に送った場合、無効なBearerからCookie認証へ自動では切り替わりません。

Common・Currency・Connect・銀行管理はカードのBearer認証とWeb Cookie認証に対応します。Web専用のアカウント設定・スキン・UMC・NumbersはWeb Cookieを使います。記憶ログインを扱うCard APIはXRift本人確認とカードのBearer認証を使用します。銀行管理とNumbers管理照会には、サーバーで確認した管理者権限が必要です。

CheckLogin・GetCurrent・GetCard・GetEvents の ncid は、認証した本人のNC IDです。他人の送金先名だけを確認するには Account/Find を使います。カードのセッションは30分、最大12時間です。CheckLogin・AcceptConnectで30分の期限を更新し、Web Cookieは12時間です。セッションの期限は応答の expiresAt・absoluteExpiresAt を参照してください。

APIへのアクセスは3秒間に20件までです。ログイン後は同じNC口座のクライアント全体、未ログイン時は送信元IPで合算します。21件目はHTTP 429の excessive_access となり、30秒間アクセスを停止します。Retry-After ヘッダーの秒数を待ってから本人の明示操作で再確認してください。パスワードを連続3回間違えると、そのアカウントのパスワードログインは30分間ロックされ、HTTP 429の password_locked を返します。ロック中の試行で時間は延長されません。変更操作を自動で繰り返さないでください。

送金とConnect

通常の送金では送金元としてログインします。requestId は8～128文字で、操作ごとに1つ生成し、結果が確定するまで同じ本文と一緒に保持します。UUID形式を利用できます。同じ本人の異なる操作に同じIDを使い回さないでください。メモは任意で最大500文字です。

金額は正の整数です。Connectを指定しない通常の直接送金は既定で1回1,000,000 NCまで、利用者の口座残高は1,000,000,000 NCまでです。Connect経由では設定された1回の金額・日次回数の上限と受取人口座の残高上限を確認します。金額や上限に小数・数値文字列は使えません。

POST /API/Currency/Remittance
Authorization: Bearer <SESSION_ID>
Content-Type: application/json

{"requestId":"example-request-0001","fromNCID":"NC-SENDER",
 "toNCID":"NC-RECEIVER","amount":1000,"memo":"イベント賞品"}

Connectは送金元が作成する送金ルールです。connectId は1～128文字、limitNC は1回の送金上限、dailyLimit は同じ送金先への1日あたりの回数です。日付は日本時間で区切り、回数の 0 は無制限です。Connect IDだけでは送金できません。

1. 送金元が設定画面または Connect/Create でConnectを作ります。
2. 受取人が自分の現在のセッションから Common/AcceptConnect を呼びます。
3. 同じ受取人セッションで、送金元NC ID・Connect ID・受取人NC IDを指定して Currency/Remittance を呼びます。

POST /API/Common/AcceptConnect
Authorization: Bearer <RECEIVER_SESSION_ID>
Content-Type: application/json

{"requestId":"accept-example-0001","fromNCID":"NC-SENDER",
 "connectId":"my-event"}

許可は現在の受取人セッションだけで30分間有効です。10～15分ごとに、新しい更新要求IDで AcceptConnect を再実行すると期限を更新できます。ログインをやり直した場合やConnect設定が変更された場合は、新しい許可を取り直します。無効化されたConnectは利用できません。

POST /API/Currency/Remittance
Authorization: Bearer <RECEIVER_SESSION_ID>
Content-Type: application/json

{"requestId":"connect-payment-0001","fromNCID":"NC-SENDER",
 "toNCID":"NC-RECEIVER","connectId":"my-event","amount":1000}

通信結果が不明なとき

応答が途切れても、サーバーでは送金が成立している場合があります。新しい要求IDで送り直さず、元の要求IDを Currency/GetRemittance に渡して確認してください。未確認なら元の要求ID・本文で再送します。同じ要求IDで異なる内容を送ると拒否されます。

GET /API/Currency/GetRemittance?requestId=example-request-0001
Authorization: Bearer <SESSION_ID>

照会結果の status: "confirmed" は送金確定です。status: "failed" と同じ requestId・error が返れば、その要求の拒否が確定しています。remittance_not_found の場合は元の本文で再送できます。認証切れ・通信エラーだけで失敗と決めず、同じ本人でログインし直して照合してください。

スキン・設定変更・銀行調整でも、未確定の操作は同じ要求IDと本文で再確認します。UMC交換は、未送信の受付を CreateExchange の同じ要求で継続し、送信済み・結果不明の交換は CheckExchange で照合します。CheckExchange は新しい送金を行いません。

応答形式と例

以下は架空の値を使った主要フィールドの抜粋です。未知の追加フィールドは無視できるように実装してください。account は認証した本人の口座情報です。Connect送金の場合も、受取人として呼び出せば受取人の情報を返します。

RequestLogin・CheckLogin

通常のログイン成功はHTTP 200です。sessionId と互換フィールド walletToken は同じ秘密値です。scope は "wallet"、deviceId は認証セッションの識別子です。物理カードの登録IDである cardId は返しません。

{"sessionId":"<SESSION_ID>","walletToken":"<SESSION_ID>",
 "scope":"wallet","deviceId":"dev_example",
 "expiresAt":1800001800,"absoluteExpiresAt":1800043200,
 "account":{"accountNumber":"NC-EXAMPLE","displayName":"ナスコ",
            "balance":10000,"currency":"NC","isAdmin":false},
 "rewards":{"day":"2027-01-15","card":{"claimed":false},"web":{"claimed":false}}}

mode:"web" のログインは Set-Cookie と、口座フィールドを最上位に置いた {accountNumber, username, displayName, balance, currency, appearance, isAdmin, csrfToken} を返します。秘密のセッションIDは返しません。

CheckLogin の成功は {loggedIn:true, account} です。Bearerの場合は上記の deviceId, scope, expiresAt, absoluteExpiresAt, rewards も返します。期限切れ・失効・認証情報なしはHTTP 401と {"error":"wallet_authentication_required"} または {"error":"authentication_required"} です。loggedIn:false のHTTP 200ではありません。本人以外のNC IDの指定はHTTP 403です。

GetCurrent・GetCard

{"ncid":"NC-EXAMPLE","balance":10000,
 "account":{"accountNumber":"NC-EXAMPLE","balance":10000,"currency":"NC"}}

GetCard は口座の表示名・残高・外観を取得するAPIです。同じ口座情報を account と card の両方へ返し、物理カードの発行や登録は行いません。Bearerでは認証セッション・有効期限・ボーナス情報も返します。表示に使うフィールドは次のとおりです。

{"card":{"accountNumber":"NC-EXAMPLE","username":"example",
 "displayName":"ナスコ","balance":10000,"currency":"NC","ncPerCredit":10,
 "isAdmin":false,
 "appearance":{"skin":{"id":"nc-default","name":"NCスタンダード",
   "category":"default","imageUrl":null,"width":1024,"height":640,"custom":false},
   "avatarUrl":null,"avatarWidth":256,"avatarHeight":256}}}

appearance.skin.imageUrl はスキン画像、appearance.avatarUrl はアイコン画像です。画像なしは null です。スキンの id を識別に使い、表示名をIDとして使わないでください。

GetEvents

items は新しい順の本人履歴です。amount は入金が正・出金が負、balanceBefore・balanceAfter はその取引の前後残高です。nextBefore が null でなければ Account/GetEvents?before=... で続きを取得できます。

{"items":[{"id":12,"transactionId":"tx_example","kind":"transfer_in",
 "amount":1000,"balanceBefore":9000,"balanceAfter":10000,
 "createdAt":1800000000,"status":"confirmed","counterparty":"NC-SENDER",
 "requestId":"example-request-0001","sessionId":null,"creditDelta":0,
 "detail":{"connectId":null,"memo":"イベント賞品"}}],"nextBefore":null}

status は取引の処理状態、detail は種類ごとの補足です。sessionId・creditDelta は過去記録との互換項目で、ログインの秘密セッションIDではありません。新方式ではゲームのBET・配当・CREDIT履歴は記録しません。

AcceptConnect

{"status":"accepted","fromNCID":"NC-SENDER","toNCID":"NC-RECEIVER",
 "connectId":"my-event","expiresAt":1800001800,"limitNC":10000,"dailyLimit":0}

expiresAt はこの受取許可の期限です。上限はその時点で有効な送金元のConnect設定です。

Remittance・GetRemittance

送金の成功と、その要求IDによる照会は同じ確定結果を返します。transactionId は確定した台帳取引のIDです。GetRemittance の照会キーは requestId のみです。

{"status":"confirmed","requestId":"example-request-0001",
 "transactionId":"tx_example","fromNCID":"NC-SENDER","toNCID":"NC-RECEIVER",
 "amount":1000,"account":{"accountNumber":"NC-SENDER","balance":9000}}

確定拒否の保存記録を GetRemittance で照会するとHTTP 200で次の形式を返します。最初の送金操作の拒否では、対応するHTTP 4xxと同形式を返す場合があります。

{"status":"failed","requestId":"example-request-0001","error":"insufficient_funds"}

記録が見つからなければHTTP 404の {"error":"remittance_not_found"} です。照会はその要求を実行した本人に限定されます。確定時の account は保存された結果なので、現在残高が必要なら GetCurrent を使います。

その他のAPIの返却形式

UMC交換は両方向とも手数料10%、10単位、既定で10～1,000,000です。実際の上限はGetStatusの exchange を参照してください。NCとUMCの本人連携は1対1で保持され、UMC認証の期限切れやNCのログアウトで解除されません。認証状態は authenticated、有効期限は authExpiresAt で確認します。FinishLogin の remember:true は、OTPで本人確認した後に専用のUMC APIキーを作成し、サーバーの専用領域へ暗号化保存します。通常のNCログアウト・サーバー再起動後も利用でき、authMode:"api_key"・authorizationSaved:true で確認できます。authExpiresAt:null は期限指定なしです。UMC側での失効やNCアカウント回復後は再認証が必要です。キー作成中の結果不明時は自動再発行せず、再度OTP確認して作成済みキーを照合・解除してから、別の明示操作で作り直します。authorizationState は none/jwt/active/issuing/revoking/revoked/invalid です。remember を省略またはfalseにすると従来の一時認証となり、UMCのJWT期限と最大7日の短い方までRAMに保持します。RevokeAuthorization は新しいStartLoginで取得したchallengeIdとOTPを受け取り、保存した専用キーをUMC側で失効させます。口座の紐付けは残ります。OTP・秘密キー・JWTはAPI応答・ブラウザー保存領域・金融DBへ含めません。

API一覧

参照欄の GET / POST はどちらでも照会できます。GETのパラメーターはクエリー、POSTはJSON本文へ渡します。セッションIDやパスワードをクエリーへ入れることは禁止です。

指定済みの7本

新しい設定・Connect・管理機能

既存のアカウント・設定機能

カード認証・記憶ログイン

NCカードの物体はXRiftインスタンス内で管理します。Webのカード・接続端末一覧と発行・失効の管理画面は撤去しました。/API/Card/List・/API/Card/Create・/API/Card/Revoke・/API/Card/ListDevices は廃止し、HTTP 410を返します。代わりの発行APIはありません。

サーバーは有効な認証セッションを保持し、失効・期限切れ時に削除します。XRiftアカウントの記憶、NC残高、取引、プロフィール・スキンは別に保持します。通常の終了は LogoutSession、明示的な記憶解除は Logout または UnlinkXRift を使います。

既存の日次ボーナス・スキン

既存のUMC連携・交換

ナスコナンバーズ

抽選は毎日20:00（日本時間）です。購入番号は "0042" のような4桁文字列で渡します。1枚1,000 NCまたは1,000 UMCで、当選金も購入時の通貨です。4桁一致100,000、下3桁一致50,000、下2桁一致10,000のうち最上位の賞だけを受け取ります。販売回・締切はGetSalesの drawNo・cutoffUnix を使い、価格・配当も応答値を確認してください。NC購入と自分のWeb購入履歴の確認にはUMC連携は不要です。

POST /API/Daily/Numbers/Purchase
Content-Type: application/json
X-CSRF-Token: <CSRF_TOKEN>

{"requestId":"numbers-example-0001","currency":"NC","drawNo":24,"number":"0042"}

購入成立は state:"accepted" と paymentState:"completed" です。購入状態は payment_pending / accepted / rejected / expired / refund_pending / refunded、支払い状態は queued / sending / unknown / completed / rejected / cancelled です。GetSales.pendingPurchase が返った場合は新しい購入を作らず、その本人の要求を復旧します。queued の購入だけ、明示操作で同じrequestId・currency・drawNo・numberのPurchaseを継続できます。sending / unknown はCheckPurchaseで照会します。

Purchaseの応答が途切れた場合は、まず元のrequestIdでCheckPurchaseを呼びます。未発見はHTTP 404と numbers_purchase_not_found です。この場合だけ、保持した元の本文で明示的にPurchaseを再送できます。rejectedRequest.requestId が元の要求と一致すれば拒否確定です。CheckPurchaseのrequestId省略時に記録がなければ purchase:null を返します。

UMCの入金が締切後に確認されたくじは抽選対象にせず、同じUMCで返金します。refund_pending と refunded を区別し、当選金・返金は payoutKind と payoutState で送金完了まで確認してください。抽選結果は既存の抽選元から取り込み、Web購入が別の当選番号を抽選することはありません。

稼働確認

Texas Hold’em

ResoniteとXRiftの全インスタンスで共有するサーバー進行卓です。物理的な台や座る位置に関係なく、自動で人間の空席へ参加します。1卓は人間最大5人で、満員なら別の卓を作ります。本人認証必須。Bearer、またはPOST本文のsessionIdを利用できます。Web Cookieの書込みはCSRF必須です。10 NC / 10 UMC = 1 CREDIT、購入した通貨で出金します。

接頭辞は /API/Game/TexasHoldem/。GetTables・GetStateはGET/POST、その他はPOSTです。

Action・Leave・ShowにはGetStateが返したtableIdを使います。変更要求は同じrequestId・同じ本文で再確認します。異なる本文は409。ACK後にGetStateで最新状態を取得します。UMCのsending/unknownは結果不明のため新規送信せずGetStateで確認してください。サーバーは公式取引履歴で確認できるまで購入CREDITを発行しません。NC/UMCの結果不明でも要求を捨てないでください。

UMC専用sessionは無操作30分、公式UMC認証の期限以下です。GetStateで延長し、サーバー再起動時は再ログインします。一般NC送金・プロフィールAPIには使用できません。GuestはNC口座を作らずレート0・ランキングと月間賞金対象外です。CREDIT・席・未確定送金があるGuestは返却完了までGuestを維持し、後のNC連携へ過去レートを遡及しません。連携が変わった古いNC専用sessionは返却復旧だけとなり、NC残高・本人札・記録は表示しません。

GetStateのbankBalanceはNC残高（Guestは0）、canBuyNCはNC購入可否です。meSeatは現在の席、viewerSeatは表示中ハンドの本人席です。handRankは本人・任意公開・ショーダウンで許可された札だけから算出。winAmountは未コール返金を含めないポット獲得額で、0より大きい席が勝者です。native:trueではplayer0Rank～player4Rank、player0WinAmount～player4WinAmountを返します。照会対象のtransferKind・transferCurrency・transferCreditも返し、対象がない場合は空文字・空文字・0です。

次ハンド待機中はmeSeatが予約席、viewerSeatはnull（nativeは-1）です。進行中CPUと予約席の番号が重なる場合でも、そのCPUの札や操作権限はありません。本人の札・役・操作判定にはviewerSeatとlegalを使い、物理席番号やmeSeatだけから推定しないでください。

記録は /API/Records/TexasHoldem/ のGetSummary、GetHands（直近100戦）、GetHand（handId必須）、GetRanking（period=all / month）で取得します。全員の札を含む終了後記録は、その対戦の参加者だけが閲覧できます。期待値・最良候補は公開情報による推定モデルの評価で、厳密な最適解の保証ではありません。

レート0から開始。最初に3000へ到達するまではマイナスなし、以後は操作品質と収支プラスにより1戦-10～+15。月間は日本時間の月初に切替え、前月上位3人へ100,000 / 50,000 / 30,000 NCを一度だけ付与します。

旧APIからの移行

JSON APIは /API/ 配下に統一しました。旧 /nc/api/v1/ の経路はHTTP 410と {"error":"api_route_retired"} を返します。例外は既存Web Cookieを移行する読取専用の GET /nc/api/v1/me と稼働確認の GET /nc/api/v1/health だけです。新しいクライアントは通常、この2つの旧経路を使用しません。

Web Cookieは Path=/ です。旧Web Cookieを持つ利用者の初回アクセス時だけ、新GetProfileが401なら旧meを1回読み、その後に新GetProfileを再照会します。新しいログイン・回復・ログアウトでは旧 Path=/nc Cookieを失効します。

旧スロット用のlocal/session/hold/recover/checkpoint・台snapshot・Webゲーム連携APIは廃止しました。旧スロットのBET・配当・CREDIT残高は保存しません。旧スロットのNC移動は Currency/Remittance、結果照会は Currency/GetRemittance を使います。新しいTexas Hold’emは別のサーバー進行ゲームで、専用APIがCREDITと進行を保持します。通信断は確定済みNC取引を取り消しません。未確定の送金要求ID・本文を保持し、同じ本人で照会・再送してください。

スキンなどの静的画像URLはJSON APIとは別で、/nc/static/・/nc/media/ を継続します。account.ncPerCredit や過去の履歴項目が残っていても、旧CREDIT保存APIが利用できることを意味しません。

主なエラー