sumsub-resolve-currency

Sumsub — 通貨とチェーンの解決

1 つのエンドポイントで 2 つの側面を扱いますが、その内容はまったく異なります。

type=fiat	type=crypto
ISO 4217 コードのフラットなリストを、ライブで取得します	100 を超えるチェーンにまたがる、数千もの資産があります
チェーンもコントラクトもなく、曖昧さもありません	1,000 を超えるシンボルが、複数のチェーン上に存在します
解決方法＝「リストにあるかどうか」	解決方法＝(symbol, chain, [contract]) → 資産を 1 つに特定します

このスキルの大半は暗号資産側についてです。トランザクションが気づかないうちに誤るのは、こちらだからです。法定通貨はリストへの登録有無を確認します。

エンドポイント

動詞	パス	用途
GET	/resources/kyt/currency?type=crypto	暗号資産カタログです。サーバー側で静的に管理されており、セッション中は安全にキャッシュできます。
GET	/resources/kyt/currency?type=fiat	レートプロバイダーからライブで組み立てられる法定通貨コードです。

type を省略すると、法定通貨のリストが返されます。チェーンリストを取得する公開エンドポイントはありません。暗号資産カタログに含まれる cryptoChain の重複しない値から導き出してください。レートエンドポイントもありません。Sumsub は内部で換算し、使用したレートを公開していません。

各暗号資産エントリーには、currencyCode、cryptoChain、contractAddress、chainId、name、coinmarketcapId、coingeckoId が含まれます。

認証 — App Token + secret（サンドボックスのみ）

認証リファレンスに従って署名します。仕組みについては、sumsub-api-authを参照してください。

⚠️ サンドボックスのトークンのみ使用してください。 ヘルパースクリプトは、SUMSUB_ALLOW_PROD=1 が設定されていない限り、sbx: で始まらないトークンを拒否します。このエンドポイントは読み取り専用ですが、このルールはこれらのスキル全体に適用されます。サンドボックス用のペアは、https://cockpit.sumsub.com/checkus/home?sbx=true（Connect Sumsub to your AI agent -> Build & configure -> Generate token）で取得してください。

変数	例
SUMSUB_APP_TOKEN	sbx:...
SUMSUB_SECRET_KEY	対応するシークレットです。
SUMSUB_BASE	任意です。既定値は https://api.sumsub.com です。

重要なルール

シンボルは資産ではありません。 USDT と USDC はそれぞれ、カタログ内の 12 を超える異なる資産を指します。ETH も複数の資産を指します。暗号資産の識別子は (currencyCode, cryptoChain) のペアであり、それでも一意でない場合は contractAddress を加えます。

📘 空の cryptoChain は欠落ではなく、値です。 これはそのチェーン固有のネイティブコインを意味します。チェーン指定なしの BTC はビットコインです。cryptoChain: BTC を指定した BTC も同じものです（サーバーはこのよくある誤りを正規化します）。一方、ラップされた別のチェーン上の BTC は、まったく異なる資産です。

🚧 曖昧な場合に既定値が選ばれることはありません。解決結果は空になります。 検索で複数の行に一致すると、サーバーは Multiple currencies found をログに記録し、通貨を一切返しません。そのため、チェーン指定がない場合に現れる症状は「レートが間違っている」ではなく「通貨が認識されない」です。さらに、その通貨に依存する後続処理はすべて、気づかないうちに機能が低下します。

手順

1. 種類を決めます。 コードが大文字 3 文字で、法定通貨リストに含まれている場合、ユーザーが別の意図を示していない限り、法定通貨として扱ってください。意図が重なる場合に注意してください。ユーザーが「USD」と言うとき、USD という名前のトークンを指していることはほとんどありません。

2. カタログを取得します。 ${CLAUDE_SKILL_DIR}/scripts/get_currencies.sh crypto（または fiat）を使用してください。セッション中はキャッシュします。暗号資産リストは大きく、静的です。

3. 解決します。 ${CLAUDE_SKILL_DIR}/scripts/resolve_currency.py にカタログとクエリを渡してください。大文字への変換と前後の空白の除去、チェーンの別名の展開、code == chain の場合のネイティブコインとしての扱いを行います。複数候補がある場合は、いずれかを選ぶのではなく、候補リストを提示して失敗します。

4. 送信する正確なフィールドを報告してください。 単に「対応しています」とだけ伝えてはいけません。

   "info": {
     "currencyCode": "USDT",
     "currencyType": "crypto",
     "cryptoParams": { "cryptoChain": "TRX" }
   }
   

5. 換算にも対処してください — 以下を参照してください。呼び出し側が忘れがちな部分です。

amountInDefaultCurrency — 省略する前にお読みください

info.amountInDefaultCurrency と info.defaultCurrencyCode は、レポート通貨での送金額を表します。省略可能に見えますが、次の3つの点から省略できません。

🚧 トラベルルールのしきい値は amountInDefaultCurrency と比較されます。 この値がない場合、しきい値の比較は完全にスキップされ、送金額がどれほど少なくてもトラベルルールのフローが実行されます。このフィールドを省略しても精度が失われるだけではなく、動作が変わります。同じことは、ホストされていないウォレットの確認しきい値にも当てはまります。

🚧 この値は取り込み時に確定します。 Sumsub はトランザクションの作成時に一度だけ計算し、保存します。その時点で誤っていたレートはレコードに残ります。後から修正するには、再読み込みではなくバックフィルが必要です。

📘 アセットを解決できない場合、変換するものはありません。 認識されない (symbol, chain) の組み合わせでは変換が行われません。これが cryptoChain の指定漏れにコストがかかるもう1つの理由です。

推奨事項： 自社システムで使用した値がわかる場合は、amountInDefaultCurrency と defaultCurrencyCode を明示的に指定してください。これにより、自社の帳簿と Sumsub のレコードが確実に一致し、管理できない時点のサードパーティのレートに依存せずに済みます。

チェーンのエイリアス

チェーン名は大文字に変換され、前後の空白が削除された後、検索前に固定のエイリアステーブルでマッピングされます。ETHEREUM、BSC、TRC20、MATIC、POLYGON、BEP20、TRON、SOLANA、AVAX_C など約20種類以上が、正規のチェーン名に解決されます。テーブルにない文字列はそのまま使用されるため、TRON20 や ERC-20 のようなわずかな違いでも一致しません。

このテーブルはどのエンドポイントからも参照できません。全リストは references/crypto-catalogue.md にあります。ユーザーが指定したチェーン文字列を解決できない場合は、アセットが未対応だと判断する前に、エイリアスと照合してください。

トラベルルールの詳細

上記のしきい値の動作に加えて、選択するアセットによっては、取引所間の交換が可能かどうかが決まる場合があります。各カタログエントリーには、相手方プロトコル独自の用語へのマッピングが含まれますが、対応範囲は限られています。

特定のプロトコルに対応するマッピングがあるカタログエントリーは一部に限られます。対応数は Sygna が最も多く、次に GTR、CODE の順ですが、いずれも全体のごく一部です。週次のリスティングジョブで新しいアセットが追加されるにつれて対応範囲は広がるため、想定で済ませずに確認してください。

相手方が使用するプロトコルに対応するマッピングがないアセットは、その相手方へのメッセージに含められません。何も送信される前に交換の検証が失敗し、データの問題のように見える notEnoughCounterpartyData が表示されます。珍しいトークンでトラベルルールの交換がこの理由で失敗した場合は、ペイロードのデバッグを始める前に用語の対応範囲を確認してください。詳しくは sumsub-integrate-travel-rule を参照してください。

出力

• 解決済み — 一致したエントリーと、送信すべき正確な currencyCode／currencyType／cryptoChain。シンボルが既知の重複に該当する場合は、呼び出し元が特定できるよう contractAddress に言及してください。
• 曖昧 — チェーンとコントラクトを含む候補行と、ユーザーが回答する必要のある質問。一つを選んではいけません。
• 見つからない — 不明なのがシンボルなのか、チェーンだけなのかを伝え、未対応と判断する前にエイリアステーブルを確認してください。

使用例

• examples/resolve-usdt-tron.json — よくあるケース：チェーンを指定して重複するシンボルを特定します。
• examples/resolve-ambiguous.json — チェーンを指定せずに同じシンボルを使用するケース。推測せず、失敗させる必要があります。
• examples/resolve-native.json — ネイティブコインの例。チェーンが空の場合の意味を示します。
• examples/resolve-fiat.json — メンバーシップのテスト。

関連項目

• references/crypto-catalogue.md — カタログのフィールド、エイリアステーブル、サーバーの解決手順、衝突の統計情報。
• sumsub-create-transaction — 解決されたフィールドの送信先。
• sumsub-integrate-travel-rule — しきい値とプロトコルの用語体系。