paladin-swap

paladin-swap-mcp

PaladinFi Swap のオープンクライアントと API 仕様 — Base 上の AI エージェント向けに、複数のアグリゲーターを競合させるスワップルーターです。このリポジトリには、公開 REST API と MCP API の仕様、動作するコード例、薄いクライアントラッパーが含まれています。ホスト型バックエンド swap.paladinfi.com はプロプライエタリです。

ルーティングの範囲。 PaladinFi Swap は、連携している上流アグリゲーター（現在は 0x と Velora）に並行して問い合わせ、手数料控除後の買付数量が多い方を返します。返されるルートが、DeFi 市場全体で利用可能な最良、最低コスト、または最適なものであるとは表明しません。「最良の執行」などの表現は、米国証券法で特別な意味を持つ用語であるため、意図的に使用していません。

---

PaladinFi Swap とは？

オンチェーンスワップを実行する必要があるAI エージェント向けに構築されたスワップルーターです。エージェントが単一のツールを呼び出すと、サービスは実行準備が整った calldata を返します。ウォレットが署名して送信します。

• トランザクションの送信先となるルーターアドレス
• すべてのルーティングが事前に設定されたcalldata
• 最小買付数量（スリッページ保護はオンチェーンで適用）
• アフィリエイト手数料はすでに組み込み済み — お客様側で個別に会計処理する必要はありません

エージェントは、アグリゲーター連携、スリッページ処理、手数料ロジックの実装を省けます。1 回の呼び出しで、実行可能なデータが得られます。

このサービスは非カストディアルです。PaladinFi がユーザーの資金を保有、署名、移動することはありません。すべてのトランザクションは、ユーザー自身のウォレット（またはユーザーに代わって動作するエージェント）によって署名され、送信されます。

インストール（MCP）

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

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

クライアントを再起動します。次の 3 つのツールが利用可能になります。

• swap_quote(sellToken, buyToken, sellAmount, taker, chainId?, slippageBps?) — 0x と Velora を競合させたルート（手数料控除後の買付数量が最大のもの）。実行準備が整った calldata を返します。
• trust_check_preview(address, chainId?) — 信頼ゲートのサンプルフィクスチャによるプレビューです。_real: false を返し、すべての要素は real: false で、推奨事項には sample- が付きます（例：sample-allow）。実際のスワップ、署名、本番環境のエージェントの判断で、プレビューの判定をゲートとして使用しないでください。 本番環境での信頼評価には、/v1/trust-check に POST してください（x402 経由で有料、1 回あたり $0.001 USDC）。または npm プラグイン @paladinfi/eliza-plugin-trust / @paladinfi/agentkit-actions を使用してください。
• swap_health() — 稼働状態、手数料設定、ソースごとのカウンター、小数桁キャッシュの状態、最後に実行された Velora 起動時カナリアの判定、セレクター適用状態を返します。

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

MCP 標準への準拠

要件	状態
ツールの title と annotations（readOnlyHint、openWorldHint、idempotentHint、destructiveHint）	✓ v0.11.74 以降。MCP の tools/list メソッドで確認できます
ツール名が64文字以下	✓ 最長は trust_check_preview（19文字）です
ストリーマブル HTTP トランスポート	✓ https://swap.paladinfi.com/mcp で利用できます
公開 OpenAPI 3.0 スキーマ	✓ /openapi.yaml で利用できます
レート制限の文書化	✓ paladinfi.com/swap に記載されています（/v1/quote は毎秒5リクエスト＋バースト30、/mcp は毎秒10リクエスト＋バースト30、IPごとに同時接続5件）
x402 有料ツールチャレンジ	✓ /v1/trust-check の有料エンドポイントで利用できます。MCP の trust_check_preview ツールは、明示的な誤用防止バナー（_real: false、_HUMAN_DO_NOT_USE_AS_REAL_VERDICT、sample- 推奨事項プレフィックス）付きのサンプルフィクスチャ出力に制限されています。設計上のプレビューであり、実際の判定ではありません
ツールの説明が限定的かつ正確	✓ 正確なスキーマについては mcp-tools.json をご覧ください
ブラウザー起点のクライアント（CORS）	✓ v0.11.75 以降、/v1/quote で利用できます。許可リストは paladinfi.com と www.paladinfi.com のみで、その他のオリジンはプリフライト時にブロックされます
実データを利用できる無料の導入用エンドポイント	✓ v0.11.77 以降、POST /v1/trust-check/ofac では OFAC SDN ウォレットスクリーニングのみを実行します（匿名、毎秒1リクエスト＋バースト3のレート制限、財務省 XML を毎日更新）。レスポンスには、/v1/trust-check の複数ソースを組み合わせた完全版へのアップグレード案内として _paid_endpoint_info が含まれます。対象範囲はウォレットの OFAC チェックです（トークンコントラクトの制裁リストは今後のバージョンで対応予定です）。
MCP レジストリーへの登録	✓ このパッケージは io.github.paladinfi/paladin-swap として登録されています。§4.A に準拠した trust-check 専用版（決済関連の機能、calldata、トランザクション実行なし）は、別パッケージ com.paladinfi/trust-check-mcp として提供されています。ストリーマブル HTTP は trust.paladinfi.com/mcp で利用できます。決済関連機能との隣接がデプロイの障害となる場合は、trust-check 版をご利用ください。

MCP ToolAnnotations に準拠しています。

• swap_quote — タイトルは "Get Swap Quote"。readOnlyHint: true（calldata を返し、サーバーの状態は変更しません）、openWorldHint: true（Base 上の上流アグリゲーター 0x AllowanceHolder と Velora Augustus v6.2 を呼び出します）
• trust_check_preview — タイトルは "Token Trust Check (Preview)"。readOnlyHint: true、idempotentHint: true（アドレスごとに決定的なサンプルフィクスチャを返します）、openWorldHint: true（有料モードの上流要素ソースがプロセス境界を越えます。形状の不一致に備えた防御的な契約違反ハンドラーを備えています）
• swap_health — タイトルは "Swap Service Health"。readOnlyHint: true、openWorldHint: false（自サービスの状態のみを調査します）

エージェントの利用手順

MCP 対応エージェント（例：Claude Code）がスワップの意図を処理する際の代表的な呼び出しチェーンです。具体的なツール呼び出しの形式はクライアントによって異なります。重要なのは、スワップルーターが実行可能な状態の calldata を返すため、エージェント自身がルーティングロジックを組み立てる必要がない点です。

ユーザー： 「Baseで100 USDCをWETHにスワップしてください。」

1. 任意の取引前の信頼性チェック（無料、サンプルフィクスチャのみ）。スワップを組み立てる前に、エージェントは trust_check_preview を呼び出して、購入するトークンのコントラクトのリスク特性を確認できます。

// Tool call
{
  "tool": "trust_check_preview",
  "arguments": {
    "address": "0x4200000000000000000000000000000000000006",
    "chainId": 8453
  }
}

// Response (truncated)
{
  "_real": false,
  "_HUMAN_DO_NOT_USE_AS_REAL_VERDICT": "Preview-only fixture. See README.",
  "trust": {
    "recommendation": "sample-allow",
    "_preview": true,
    "factors": [
      { "real": false, "source": "ofac",      "signal": "clear" },
      { "real": false, "source": "goplus",    "signal": "clear" },
      { "real": false, "source": "etherscan", "signal": "verified-contract" }
    ]
  }
}

プレビューはサンプルフィクスチャのみです。判定を利用する前に、エージェントは _real === true であることを確認する必要があります。本番環境での判定には、/v1/trust-check（有料、x402 経由で1回あたり$0.001 USDC）を呼び出すか、npm プラグイン @paladinfi/eliza-plugin-trust／@paladinfi/agentkit-actions を使用してください。

2. calldata付きの競争力ある見積もり。 エージェントは swap_quote を呼び出し、ルートと実行可能なトランザクションを取得します。

// Tool call
{
  "tool": "swap_quote",
  "arguments": {
    "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "buyToken":  "0x4200000000000000000000000000000000000006",
    "sellAmount": "100000000",
    "taker":      "0xUserAgentWallet",
    "chainId":    8453,
    "slippageBps": 50
  }
}

// Response (illustrative; values depend on live pool state)
{
  "source":           "velora",
  "chainId":          8453,
  "router":           "0x6a000f20005980200259b80c5102003040001068",
  "calldata":         "0xe3ead59e000000000000000000000000...",
  "buyAmount":        "43200000000000000",
  "minBuyAmount":     "42984000000000000",
  "sellAmount":       "100000000",
  "gas":              "318707",
  "ourFeeBps":        10,
  "ourFeeRecipient":  "0xeA8C33d018760D034384e92D1B2a7cf0338834b4"
}

source は、このペアで手数料控除後の購入量が多かった上流アグリゲーター（0xまたはVelora）を示します。10 bpsの手数料はすでにcalldataに組み込まれています。表示される buyAmount はユーザーの手取り額（手数料控除後、スリッページ控除前）です。minBuyAmount は、指定された50 bpsのスリッページ許容度を反映しています。

3. 署名して送信。 エージェントは、署名のためにトランザクションの内容（to=router, data=calldata, value=0（ERC20 → ERC20の場合））をユーザーのウォレットに提示します。PaladinFiが署名を受け取ることはありません。ウォレットがトランザクションをBaseに直接ブロードキャストします。

4. 確認。 スリッページはオンチェーンで適用されます。実際の約定で minBuyAmount を下回る場合、スワップはリバートします。エージェントはトランザクションハッシュを報告し、ユーザーのウォレットにはBaseで確定した購入量が表示されます。10 bpsの手数料は、同じトランザクションの一部としてアトミックに公開済みのトレジャリーアドレス（/health）へ送金されます。2回目のオンチェーン処理は不要です。

エンドツーエンドで非カストディアル。 PaladinFiが資金を保有、署名、移動することは一切ありません。MCP サーバーはメタデータを返し、ウォレットが実行します。侵害されたスワップルーターが返せるのはcalldataのみです。悪意のあるcalldataであっても、v0.11.71の外部ルーター＋セレクター＋0x Settlerターゲットの許可リスト（下記ロードマップを参照）と、ユーザー自身のウォレット側の承認上限によって制限されます。

インストール（REST）

MCPは不要です。エンドポイントに直接アクセスしてください。

curl -sS https://swap.paladinfi.com/v1/quote \
  -H 'content-type: application/json' \
  -d '{
    "chainId": 8453,
    "sellToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "buyToken":  "0x4200000000000000000000000000000000000006",
    "sellAmount": "5000000",
    "taker": "0xYOUR_AGENT_WALLET"
  }'

REST仕様の全文は openapi.yaml を参照してください。

無料のOFAC SDNウォレットスクリーニング（MCP不要、キー不要、登録不要）については、paladinfi.com/docs/screen-wallets/ のcURLとReactフックを使った手順を参照してください。POST /v1/trust-check/ofac は allow または block の判定を返します。匿名で利用でき、レート制限は1 r/s、バーストは3です。

エンドポイント

メソッド	パス	目的	料金
GET	/health	稼働状態、手数料設定、ソースごとのカウンター、小数桁キャッシュの状態、直近のVeloraカナリア判定、セレクター適用状態	無料
POST	/v1/quote	calldata付きの競争力あるルート見積もり — 0xとVeloraのうち手数料控除後の購入量が最も多いもの	無料
POST	/v1/trust-check	トークンコントラクトのリアルタイム信頼性評価（OFAC SDN、GoPlus、Etherscan、異常検知ヒューリスティック）	x402経由で1回あたり$0.001 USDC
POST	/v1/trust-check/preview	信頼性チェックの応答形式をサンプルフィクスチャでプレビュー（リアルタイムのデータソースは評価されません）	無料
POST	/mcp	MCP Streamable-HTTPトランスポート（3つのツール — mcp-tools.json を参照）	無料

応答形式（抜粋）

{
  "source": "velora",
  "chainId": 8453,
  "router": "0x6a000f20005980200259b80c5102003040001068",
  "calldata": "0x...",
  "buyAmount": "2160000000000000",
  "minBuyAmount": "2138000000000000",
  "sellAmount": "5000000",
  "gas": "318707",
  "ourFeeBps": 10,
  "ourFeeRecipient": "0xeA8C33d018760D034384e92D1B2a7cf0338834b4",
  "estimatedOurFeeAmount": "2160000000000",
  "estimatedOurFeeToken": "0x4200000000000000000000000000000000000006"
}

source は、この見積もりで選ばれた上流アグリゲーター（"0x"または"velora"）です。taker から、to=router, data=calldata, value=0（ERC20→ERC20の場合）としてトランザクションを送信してください。

例

• examples/python/quote_and_swap.py — web3.pyを使ったPython
• examples/typescript/quote_and_swap.ts — viemを使ったTypeScript

手数料

10ベーシスポイント（0.1%）の一律手数料が買いトークンに対してかかります。手数料は見積もり額ではなく、実際の約定額に基づいて計算されるため、見積もりから約定までの間にプールの状態が変化しても、想定以上の金額を支払うことはありません。PaladinFi の 10 bps は、上流アグリゲーターのインテグレーター手数料の仕組み（0x の swapFeeBps／Velora の partnerFeeBps）を通じて買いトークン側から徴収されるため、レスポンスに表示される buyAmount には、上流プロトコル手数料と当社の 10 bps の両方がすでに反映されており、約定時に追加で差し引かれることはありません。

手数料は PaladinFi のトレジャリーに直接送られるため、お客様側でオンチェーンの受領手続きを行う必要はありません。手数料の受取アドレスは /health で公開されており、オンチェーンで監査できます。/v1/quote エンドポイントは無料で利用でき、呼び出しごとの料金や追加のスプレッドはありません。（有料なのは /v1/trust-check エンドポイントのみで、x402 経由で 1 回あたり $0.001 USDC です。）

対応資産

• チェーン： Base（8453）。Ethereum メインネット、Arbitrum、Optimism、BNB は今後対応予定です。
• トークン： Base 上で 0x または Velora が対応する任意の ERC20。対応範囲は両方のアグリゲーターの合算です。主要なトークンペア（USDC、WETH、cbBTC、USDT、DAI、AERO）は両方でルーティングできますが、流動性の低いトークンはどちらか一方でしかルーティングできない場合があります。

Trust Check のデータソース

有料の /v1/trust-check エンドポイントは、トークンコントラクトを定義済みの公開データソース一式と照合し、recommendation: "allow" | "warn" | "block" という単一の判定と、ソースごとの内訳を返します。現在参照しているソースと、検証可能性を確認するための情報は以下のとおりです。

ソース	チェック対象	検証可能性
OFAC SDN list（米国財務省）	制裁対象のアドレス（コントラクト自体、デプロイヤー、関連が判明しているウォレット）	ホスト型バックエンドで、財務省 Sanctions List Service のフィード https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML から毎日リストを更新します。抽出されるアドレスデータセットは、Feature[@FeatureTypeID="345"]/FeatureVersion/VersionDetail[@DetailTypeID="1432"] エントリーの和集合です（FeatureTypeID 345 = ETH/EVM アドレス、DetailTypeID 1432 = デジタル通貨アドレス詳細）。前回の検証時点で読み込まれていた件数は 87 ETH アドレスです（2026-04-30）。元となる財務省のフィードは一般公開され、ダウンロードできるため、どのクライアントでもデータセットを独自に再生成し、一致があった場合に検証できます。
GoPlus Token Security API	ハニーポットのパターン、ミント権限、所有権の放棄、送金の一時停止、ブラックリスト機能、アンチホエール機能、隠れた所有者、スリッページ変更機能	呼び出しごとに https://api.gopluslabs.io/api/v1/token_security/8453?contract_addresses=<address> へクエリします。GoPlus のレスポンスを正規化し、公開する factors 配列に格納します。GoPlus の完全なレスポンスは一般公開されているため、購入者は任意のシグナルを独自に監査できます。
Etherscan / BaseScan のソースコード検証（統合 Etherscan v2 API 経由）	ソースコードの検証済み状態とプロキシパターンの検出（getSourceCode レスポンスの Proxy / Implementation フィールド経由）	呼び出しごとに https://api.etherscan.io/v2/api?chainid=8453&module=contract&action=getsourcecode&address=<address> へクエリします。一般公開されているソースコードは、検証済みであれば basescan.org で独自に確認できます。
異常検知ヒューリスティクス（PaladinFi 内部）	コントラクトの経過時間（1時間未満／24時間未満／7日未満）、アドレス種別の分類（eth_getCode によるコントラクトと EOA の判別）、外向きトランザクション履歴の有無（nonce=0 のチェック）	ヒューリスティクスのロジックはホスト型バックエンドのモジュール address_anomaly.py で実行されます。出力されたシグナル（contract_age_under_*、address_kind_*、no_outbound_history）はそれぞれレスポンスに含まれるため、購入者は直接 RPC を呼び出して結論を再現したり、変更したりできます。

プレビュー版と有料版の違い。 /v1/trust-check/preview（無料）は、_real: false マーカーが付いた静的なフィクスチャを返します。上記のライブデータソースは一切照会しません。/v1/trust-check（有料、x402 経由で $0.001 USDC）は、4 つすべてを参照します。プレビューは、インテグレーターが料金を支払わずにリクエスト形式を検証し、レスポンススキーマを確認できるように用意されています。エージェントは判定を使用する前に、トップレベルの _real フィールドが true であることを確認する必要があります。

リクエストのログ記録。 呼び出しごとに、PaladinFi はタイムスタンプ、照会されたアドレス、送信元 IP、課金／レート制限の参照情報を含むリクエストログエントリーを保持します。これは収益の会計処理、レート制限の適用、不正利用の検出に使用され、分析や転売には使用されません。PaladinFi は、評価済みトークンや購入者のクエリ履歴を別個のデータベースで管理していません。

ロードマップ

• Base 上での 0x Settler ルーティング
• Base 上での 0x と Velora 間の最良価格ルーティング（v0.11.66 以降、2026-05-04）
• swap_quote、swap_health、trust_check_preview ツールを備えた MCP Streamable-HTTP トランスポート
• x402 経由の有料 /v1/trust-check エンドポイント（1回あたり $0.001 USDC）
• ソースごとの 4 バイト calldata セレクターと Settler ターゲット許可リスト（v0.11.71 — ルーター差し替え／ディスパッチャー乗っ取り攻撃に対する多層防御）
• Ethereum メインネット、Arbitrum、BNB、Optimism — 予定
• Permit2 ネイティブフロー（approve トランザクションを省略）— 予定

ステータス

本番稼働中です。エンドポイントは稼働しており、監視され、Base 上のオンチェーンテストトランザクションによってエンドツーエンドで検証されています。現在の手数料設定、バージョン、ソースごとのカウンターについては、/health をご覧ください。

このリポジトリの内容

ファイル／フォルダー	用途
README.md	このファイル
LICENSE	MIT — このリポジトリ内のすべての内容を対象とします
SECURITY.md	脆弱性の報告方法と対象範囲
openapi.yaml	公開 REST API の OpenAPI 3.0 仕様
mcp-tools.json	MCP ツールのスキーマ
examples/	動作するコード例（Python、TypeScript）
.github/workflows/ci.yml	CI：プッシュ／PR 時に YAML／JSON 構文と OpenAPI 3.0 スキーマを検証

このリポジトリに含まれないもの： ホスト型バックエンド（プロプライエタリ）。このリポジトリは、インストール手順、スキーマ、統合用コードサンプルを含む公開クライアント部分です。

お問い合わせ

• メール：[email protected]
• マーケティング：paladinfi.com
• API：swap.paladinfi.com/health
• ランディングページ：paladinfi.com/swap/

法的事項

Malcontent Games LLC（PaladinFi の名称で事業を運営するミシガン州の有限責任会社）が運営しています。本サービスは、サードパーティのアグリゲーター（現在は 0x と Velora）を通じて見積もりをルーティングします。資産の管理権はお客様が保持し、すべてのトランザクションにお客様のエージェントが署名します。PaladinFi がユーザー資金を保有することはありません。

ホスト型サービスの利用には、PaladinFi 利用規約およびプライバシーポリシーが適用されます。

ライセンス

このリポジトリの内容は、MIT License に基づいて公開されています。ホスト型バックエンドはプロプライエタリであり、対象には含まれません。