trust-check-mcp

trust-check-mcp

PaladinFi Trust Check のオープンクライアントと API 仕様 — Base 上の AI エージェント向けに、ウォレットの OFAC SDN 無料スクリーニングとサンプルフィクスチャによる Trust Check プレビューを提供します。このリポジトリには、公開 REST API と MCP API の仕様、動作するコード例、薄型のクライアントラッパーが含まれています。ホスト型バックエンドはプロプライエタリです。

Malcontent Games LLC（PaladinFi として事業を運営）が運営しています。

---

PaladinFi Trust Check とは？

Base 上の AI エージェント向けに、ウォレットを OFAC SDN リストと照合する無料のスクリーニング機能です。MCP ツールを 1 回呼び出すだけで、米国財務省 OFAC SDN リストに対する allow / block の二者択一の判定が返されます。

• 認証不要。 API キー、サインアップ、請求は不要です。
• 米国財務省 OFAC SDN の最新データ。 財務省の XML フィードから毎日更新されます。
• レスポンスごとに鮮度メタデータを付与。 _ofac_list_updated_at（ISO タイムスタンプ）と _ofac_sdn_count がすべてのレスポンスの trust ブロック内に含まれるため、呼び出し元は当方の記録管理に頼らず、データの古さを確認できます。
• レスポンスに署名。 すべての /ofac レスポンスには、正規化された JSON 本文に対する Ed25519 署名（_signature、_signature_alg、_signature_pubkey_hex）が付与されるため、利用側は送信元の完全性を検証できます。
• レート制限。 IP ごとに毎秒 1 リクエスト、バースト 3 リクエスト、同時接続 3 件です。
• カストディなし、読み取り専用。 資金の取り扱い、calldata、署名機能、トランザクション実行はありません。

この MCP は、制裁スクリーニング向けのオフチェーン HTTP 機能です。コントラクト内のゲートロジック（セトルメントコントラクト内で実行される Solidity のモディファイア）には、オンチェーンの制裁オラクルが引き続き標準の機能となります。

インストール（MCP）

Claude Code または Streamable-HTTP トランスポートをサポートする MCP 互換クライアントの場合：

claude mcp add --transport http --scope user paladin-trust https://trust.paladinfi.com/mcp

追加する前に、ホストが稼働していることを確認してください：

curl -i https://trust.paladinfi.com/health
# Expect: HTTP/1.1 200 OK

mcp add の実行後、クライアントを再起動してください。次の 3 つのツールが利用可能になります。

• trust_check_ofac_free(address, chainId?) — 米国財務省 OFAC SDN リストによるウォレットのライブスクリーニングです。_real: true と鮮度メタデータに加え、recommendation: "allow" | "block" が返されます。
• trust_check_preview(address, chainId?) — より広範な Trust Check レスポンス形式のサンプルフィクスチャによるプレビューです。trust ブロックには _preview: true が含まれ、すべてのファクターは real: false で、推奨は sample- が接頭辞として付与されます。プレビューの判定を、実際のスワップ、署名、または本番環境のエージェントによる意思決定のゲートに使用しないでください。
• trust_check_health() — 稼働状況、対応チェーン、OFAC リストの更新タイムスタンプと件数を確認します。

完全なツールスキーマについては、mcp-tools.json を参照してください。

REST API

MCP サーバーは 3 つの REST エンドポイントを提供します。バックエンドは、PaladinFi の他のサービスと同じオリジン（swap.paladinfi.com）でホストされています。この MCP は読み取り専用の OFAC スクリーニングに限定されており、より広範なプラットフォームの calldata、署名機能、トランザクション機能は公開しません。REST エンドポイントは curl から直接呼び出せます：

# Free OFAC SDN screen
curl -X POST https://swap.paladinfi.com/v1/trust-check/ofac \
  -H "content-type: application/json" \
  -d '{"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'

# Sample-fixture preview
curl -X POST https://swap.paladinfi.com/v1/trust-check/preview \
  -H "content-type: application/json" \
  -d '{"chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}'

完全なスキーマについては、openapi.yaml を参照してください。

chainId に関する注意： OFAC SDN スクリーニングはウォレットアドレス単位で、チェーンに依存しません。同じ 0x アドレスは、ネットワークに関係なくリストに掲載されるか、されないかのどちらかです。chainId は完全版の /v1/trust-check エンドポイントとの一貫性を保つために受け付けますが、OFAC の照合対象を限定するものではありません。

対象範囲と制限

項目	値
チェーン	Base メインネット（chainId 8453）
ソース	米国財務省 OFAC SDN XML フィード
管轄区域	米国 OFAC SDN のみです。EU、国連、英国、その他の制裁制度には対応していません。米国外の管轄区域における利用者は、現地で適用されるリストとの照合を行う責任があります。
更新頻度	財務省の XML フィードから毎日取得
リストの規模	ウォレット／EOA アドレス約 93 件（最新の _ofac_sdn_count を参照）
レート制限	1 リクエスト／秒＋バースト 3＋IP あたり同時実行 3
認証	匿名（API キー不要、登録不要）
料金	無料

レスポンス形式

trust_check_ofac_free

鮮度と対象範囲を示すマーカーは、trust ブロック内にあります。トップレベルには Ed25519 署名と、有料の完全構成エンドポイントへの参照も含まれます。

{
  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chainId": 8453,
  "trust": {
    "recommendation": "allow",
    "factors": [
      { "source": "ofac", "signal": "not_listed", "weight": 0, "details": "", "real": true }
    ],
    "version": "1.1",
    "_real": true,
    "_scope": "ofac-only (wallet-address screen; use /v1/trust-check for full composition: GoPlus + Etherscan + anomaly heuristics)",
    "_ofac_list_updated_at": "2026-05-31T04:08:06Z",
    "_ofac_sdn_count": 93
  },
  "_signature": "<base64 Ed25519>",
  "_signature_alg": "ed25519",
  "_signature_pubkey_hex": "272b6b62230d9da810f3ed64b5e5147f1ae062cb46ad7f25044b0aab1d18fb6f"
}

制裁対象アドレスの場合も同じ形式で返されますが、trust.recommendation: "block" となり、要素 { "source": "ofac", "signal": "sdn_listed" } が含まれます。

判定を使用する前に、プログラムで安全性を確認してください。

resp = httpx.post("https://swap.paladinfi.com/v1/trust-check/ofac",
                  json={"chainId": 8453, "address": addr}).json()
trust = resp["trust"]
assert trust["_real"] is True                    # not a fixture
assert trust["_scope"].startswith("ofac-only")   # not a different evaluation path
verdict = trust["recommendation"]                # "allow" or "block"

trust_check_preview

これはサンプル用のフィクスチャであり、ライブ評価ではありません。同じエンベロープ（address、chainId、trust と、トップレベルの request_id および _mcp_paid_endpoint_info）を使用しますが、trust 内では _preview: true が設定され、recommendation には sample- が付加され（例："sample-allow"）、risk_score は null、すべての要素の real は false となり、trust._message には実際の判定として使用しないよう警告が含まれます。プレビューには _real フィールドはありません。フィクスチャと実際のスクリーニング結果を見分けるには、_preview: true マーカーと sample- プレフィックスを確認してください。

更新頻度

OFAC SDN リストは https://www.treasury.gov/ofac/downloads/sdn.xml から毎日取得されます。メモリ内リストの正確なタイムスタンプは、レスポンスごとに trust._ofac_list_updated_at で返されるため、別の記録管理レイヤーを信頼せずにデータの古さを検知できます。

ソースフィードに接続できない場合、メモリ内リストは保持され、_ofac_list_updated_at には最後に正常に更新された時刻が引き続き反映されます。リストが古くなっても、自動的に block へ切り替わることはありません。許容できる最大経過時間を適用する責任を負う利用者は、自身で _ofac_list_updated_at を確認してください。

ログと保持期間

サーバーは、リクエストのタイムスタンプ、送信元 IP（レート制限の計算のみ）、照会されたアドレスを標準の nginx アクセスログに記録します。ログは運用上のデバッグのために 30 日間保持された後、ローテーションされます。レート制限の時間枠を超えて、利用者の身元と照会されたアドレスとの永続的な関連付けが構築されることはありません。分析、サードパーティーによる追跡、個人識別情報の補完は行いません。

レート制限の動作

1 リクエスト／秒＋バースト 3 を超えるリクエストには HTTP 429 が返されます。レート制限の時間枠は IP ごとに適用され、IP の禁止や段階的なブロックはありません。時間枠が過ぎた後の次のリクエストは通常どおり処理されます。再試行するタイミングは Retry-After ヘッダーに示されます。

このエンドポイントの利用には、PaladinFi Terms が適用されます。

関連パッケージ

複数のシグナル（OFAC＋GoPlus のトークンセキュリティ＋Etherscan のソース検証＋異常検知ヒューリスティクス）を組み合わせた評価向けに、PaladinFi は他の npm パッケージを提供しています。詳細は paladinfi.com/trust-check を参照してください。この MCP から複数シグナル対応パッケージへ移行するには、選択した npm パッケージをこの MCP と併せて、または置き換えてインストールしてください。ツール名が重複しているため、呼び出し箇所を書き換えずに移行できます。

オンチェーン制裁オラクルとの使い分け

	オンチェーンオラクル	trust_check_ofac_free
アクセス方法	決済コントラクト上での Solidity 呼び出し	HTTP POST（匿名）
最適な用途	コントラクト内のゲートロジック（修飾子）	オフチェーンエージェント、ボット、ウェブアプリ、MCP クライアント
レスポンス	単純な bool	鮮度メタデータを含む構造化 JSON
料金	呼び出しごとにガス代	無料＋レート制限あり
対象範囲	多くの場合、複数の管轄区域	米国 OFAC SDN のみ

これらは相互に補完する手段です。エージェントやウェブ UI での表示にはオフチェーン HTTP スクリーニングを、決済コントラクトにはオンチェーン修飾子を使用します。

使用例

依存関係はなく、コピー＆ペーストですぐに実行できます。デフォルトでは、問題のないアドレスとOFACに実際に掲載されているアドレスを1つずつスクリーニングするため、初回実行でallowとblockの両方を確認できます。引数として任意のアドレスを渡せます。終了コード： すべて問題なしの場合は0、掲載されているアドレスが1つでもある場合は1、リクエストエラーの場合は2です。CIや送信前チェックにそのまま組み込めます。

• examples/python/check_address.py — Python 3（標準ライブラリのみ。pip installは不要です）。実行方法：python check_address.py。
• examples/typescript/check_address.ts — 組み込みのfetchを使用するTypeScript。実行方法：npx tsx check_address.ts。

同じエンドポイントをブラウザー／Reactに統合する方法については、チュートリアルpaladinfi.com/docs/screen-wallets/をご覧ください。

ドキュメント

• ホスト型MCPエンドポイント：trust.paladinfi.com/mcp
• ライブ/health：trust.paladinfi.com/health
• Apexのドキュメント：paladinfi.com/trust-check/
• スワップルーティング用の姉妹MCP：paladin-swap-mcp

お問い合わせ

• 一般：[email protected]
• セキュリティ：SECURITY.mdをご覧ください

法務情報

Malcontent Games LLC, doing business as PaladinFiが運営しています。swap.paladinfi.comのホスト型バックエンドと、trust.paladinfi.comのMCPサーバーはプロプライエタリです。このリポジトリには、クライアント向けの仕様とサンプルが含まれており、MITライセンスの下で提供されます。