Advan: Solana trading tools

Advan

Advan は、AI エージェントに Solana の取引ツールを提供する、オープンソースの MCP サーバーおよび HTTP API です。見積もりと未署名のスワップトランザクションは Jupiter Swap API V2 から取得します。トークンリスクとウォレットポートフォリオの読み取りには、x402（正確なスキーム、USDC）による支払いが必要です。

このサーバーは非カストディアルです。トランザクションに署名することはなく、取引キーを読み込むこともありません。build_swap_tx は、ユーザー自身のウォレット（taker）で署名するための、未署名の Base64 トランザクションを返します。SOLANA_KEYPAIR_PATH を読み取るのは scripts/e2e-devnet-x402.ts のみです。

パッケージ名は advan-mcp です（このツリーが作成された 2026-10-25 時点では npm に未登録です）。公開する前に package.json の "name" フィールドを変更してください。advan-mcp の bin 名はそのままで構いません。

手数料

手数料（ホステッドエンドポイント）： Advan 経由で構築されたスワップには、Jupiter の紹介プログラムを通じて 1.00%（100 bps）のプラットフォーム手数料が含まれます。Jupiter がその手数料の 20%を受け取るため、Advan の純収益は 0.80%です。署名する前に、すべての見積もりで手数料を確認できます（platformFee）。token_risk と wallet_portfolio の呼び出しには、x402（Solana メインネット）経由で 1 回あたり $0.02 USDC の費用がかかります。見積もりは無料です。非カストディアルのため、すべてのトランザクションはご自身のウォレットで署名します。Advan がキーや資金を保有することはありません。セルフホストしたコピーでは、運営者が独自の手数料を設定しない限り、料金は発生しません。

ホステッドエンドポイント

• https://advan.fly.dev
• Streamable HTTP MCP：https://advan.fly.dev/mcp

PUBLIC_BASE_URL はこのオリジンです。Fly が TLS を終端し、アプリが http:// を案内してしまうため、x402 リソース URL と Bazaar メタデータではこの値を使用します。

デプロイ手順については、docs/DEPLOY-FLY.md を参照してください。

呼び出せる機能

ツール	価格	機能
get_quote	無料	taker を指定せずに Jupiter の GET /swap/v2/order を呼び出します。見積もりのみです。
build_swap_tx	無料	同じエンドポイントに taker を指定して呼び出します。未署名トランザクションと送信方法のヒントを返します。
token_risk	X402_PRICE_USD（デフォルトは $0.01）	RPC の mint／freeze authority、Jupiter Tokens V2、RugCheck の概要を取得し、スコアを付けます。
wallet_portfolio	同上	getBalance + getTokenAccountsByOwner（Token および Token-2022）、Jupiter Price V3 を取得します。

Jupiter のベース URL は https://api.jup.ag（Swap API V2）です。lite-api.jup.ag は使用しません。任意の JUPITER_API_KEY は x-api-key として送信されます。キーなしでのアクセスは毎秒約 0.5 リクエストです。これを超えると Jupiter は HTTP 429 を返し、Advan はバックオフして最大 3 回待機した後に再試行します。本番環境では JUPITER_API_KEY を設定してください。複数のエージェントが呼び出すようになったら、ポータルキーを使用してください。

想定される手数料

Jupiter の紹介手数料。 JUPITER_REFERRAL_ACCOUNT が設定されている場合、すべての注文で referralAccount と referralFee が送信されます。許可される範囲は 50–255 bps（デフォルトは 50）です。Jupiter がこの手数料の 20%を受け取るため、ユーザーに 50 bps を請求すると、紹介パートナーの純収益は 40 bps になります。これは、Jupiter が通常課す 2–10 bps のプラットフォーム手数料に代わるものです。紹介手数料なしで Jupiter を呼び出す場合よりも、見積もり額は高くなります。

Jupiter は手数料の mint（SOL、次にステーブルコイン、LST、その他のトークンの順）を選択します。その mint の紹介用トークンアカウントが存在しない場合でもスワップは成功しますが、手数料は徴収されません。Advan はすべての注文レスポンスを確認します。

• referralAccount が設定されたアカウントと一致すること
• gasless が false の場合、feeBps が設定された手数料と等しいこと
• gasless が true の場合、feeBps が設定された手数料以上であること（gasless のコストによって bps が追加される場合があります）
• feeMint に設定済みの紹介用トークンアカウントがあり、そのアカウントが mint に対する紹介アカウントの V2 関連トークンアカウントであること（allowOwnerOffCurve を指定し、mint のトークンプログラム（Token または Token-2022）の下で作成されていること）。これは initializeReferralTokenAccountV2 が作成するアカウントです。別のアカウントに差し替えられている場合、検証に失敗します。レガシーの referral_ata PDA は、そのアカウントがすでにオンチェーンに存在する場合に限り許可されます。
• 起動時に、Advan は設定された各紹介用トークンアカウントが SOLANA_RPC_URL 上に存在するか確認します。存在しない V2 アカウントは記録されます。不正なアカウント、または存在しないレガシー PDA がある場合、起動は拒否されます。 FEE_CHECK_MODE=fail（デフォルト）では、手数料自体が誤っている場合、見積もりとトランザクションは返されません。warn では、feeCheck.ok: false を付けて返し、いずれの場合も fee_check_failure イベントをログに記録します。

トークン間のルートでは、アカウントを作成していない feeMint が選ばれることがあります。REFERRAL_MISSING_MINT_MODE=requote（デフォルト）では、referralAccount／referralFee を付けずにそのペアを再度見積もり、見積もりを返して referral_requote のログ行を書き込みます。fail ではスワップを拒否します。warn では元の注文を feeCheck.ok: false とともに返します。そのペアに手数料を適用する場合は、npm run setup:referral で REFERRAL_MINTS にミントを追加してください。

アカウントを未設定のままにすると、注文はリファラルなしで送信されます（その旨の起動時警告が表示されます）。JUPITER_REFERRAL_REQUIRED=true にすると、アカウントと wSOL、USDC、USDT のトークンアカウントがない場合、起動を拒否します。

x402。 token_risk と wallet_portfolio は正確なスキームを使用します。購入者は X402_NETWORK 上で、X402_PAY_TO に USDC を支払います。デフォルトのネットワークは Solana devnet（solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1）、devnet の USDC は 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU です。Mainnet は solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp、USDC は EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v です。受取側の USDC トークンアカウントは、あらかじめ作成しておく必要があります（npm run setup:payto-ata）。

@coinbase/cdp-sdk/x402 が @x402/evm を読み込むため、これは依存関係に含まれています。Advan が登録するのは Solana の正確なスキームのみです。

CDP_API_KEY_ID と CDP_API_KEY_SECRET が設定されている場合、主要なファシリテーターは Coinbase CDP です。CDP の /supported プローブに失敗すると PayAI（https://facilitator.payai.network）が使用され、CDP のキーがない場合は PayAI のみが使用されます。検証と決済は、支払い要件に広告された extra.feePayer が含まれるファシリテーターに送信されます。処理中の支払いが別のファシリテーターに引き継がれることはありません。そのファシリテーターでは手数料支払者が一致せず、決済が失敗するためです。CDP で安全に切り替え可能な障害が発生すると、Advan は CDP をダウン状態として記録し、次の支払いチャレンジを PayAI の手数料支払者で再構築します。次のプローブは起動時に開始したタイマーではなく、障害発生から X402_CDP_RECOVERY_INTERVAL_MS 後（デフォルトは 5 分）にスケジュールされます。/supported が正常に応答すると、CDP が主要なファシリテーターに戻り、支払い要件が再読み込みされ、facilitator_recovered のログ行が書き込まれます。再読み込みに失敗するかタイムアウトした場合、Advan は支払い要件を空のままにせず、PayAI に戻して要件を再読み込みします。ファシリテーターが広告したすべての手数料支払者が保持されるため、CDP の手数料支払者が変更されても、CDP で決済できます。GET /health は、cdp が primary、down、unconfigured のいずれかであることを報告し、ダウン中は cdpNextProbeAt も報告します。決済のタイムアウトや HTTP 5xx は、切り替えの対象になりません。検証の失敗は、ファシリテーターからの理由とともに x402_verification としてログに記録されます。クライアントに表示される 402 の本文と PAYMENT-REQUIRED エラーには、payment could not be verified と記載されます。

Solana のブロックハッシュを含む MCP の支払い要件は、有料の呼び出しごとに構築されます。HTTP ではリクエストごとに構築されます。どちらも X402_RPC_URL を使用します。これはデフォルトで X402_NETWORK から設定され、SOLANA_RPC_URL が使われることはありません。

無料枠の終了後に CDP が公表している手数料は、決済成功 1 回あたり $0.001 です。PayAI の Solana mainnet exact の手数料は $0.00133 です。Devnet での PayAI の決済は無料です。価格が、該当する手数料に X402_MIN_FEE_MULTIPLE（デフォルトは 5）を掛けた額を下回る場合、Advan は起動時に警告を表示します。X402_PRICE_GUARD=refuse の場合は終了します。$0.01 は PayAI の mainnet 手数料の約 7.5 倍です。$0.005 では足りません。

get_quote と build_swap_tx は制限されません。

ガード

見積もりまたはトランザクションを返す前に、次の条件を確認します。

• 指定された slippageBps は MAX_SLIPPAGE_BPS（デフォルトは300）以下である必要があります
• クライアントがスリッページを指定しない場合も、レスポンス内のJupiterのRTSE値は上限以下である必要があります
• 上限が設定されている場合、amount は MAX_INPUT_AMOUNT 以下（基本単位）である必要があります。未設定の場合は、起動時に警告が表示されます。
• 米ドル換算額（amount × Jupiter Price V3）は MAX_TRADE_USD（デフォルトは1000）以下である必要があります。MAX_TRADE_USD=off を設定すると無効になります。上限が有効なときに価格を取得できない場合、取引は拒否されます。両方の上限が無効の場合は、起動時に強い警告が表示されます。
• 価格インパクトの絶対値は MAX_PRICE_IMPACT_PCT（デフォルトは5）以下である必要があります。Jupiterの priceImpactPct は小数として扱われます

スワップ署名

build_swap_tx は、デフォルトで管理対象のパスを使用します（SWAP_SELF_BROADCAST_DEFAULT=false）。

• JupiterZ（RFQ）ルートを使用できます。マーケットメーカーの共同署名が必要で、Jupiterが { signedTransaction, requestId } を指定して POST https://api.jup.ag/swap/v2/execute を呼び出す際に追加します。
• ルーターが jupiterz の場合、レスポンスには submit.method: "jupiter"、requestId、coSignRequired が含まれます。
• トランザクションフィールドは未署名です。テイカーのウォレットで署名してから、速やかに /execute に送信してください（lastValidBlockHeight または expireAt）。

selfBroadcast: true を渡すか、環境変数のデフォルトを設定すると、excludeRouters=jupiterz を指定して送信します。この場合、テイカー以外の signatureFeePayer はツールによって拒否され、JupiterZルートのままのレスポンスも拒否されます。テイカーは自身のRPCを使って、そのトランザクションに署名してブロードキャストします。

インストール

Node.js 20以降が必要です。

npm install
npm run build
cp .env.example .env

Stdio（Claude Desktop、Cursor、または公開後の npx）：

npm start
# or, once published:
npx advan-mcp

HTTP（プレーンJSONおよび /mcp 上のStreamable HTTP MCP）：

npm run start:http
# listens on $HOST:$PORT, default 127.0.0.1:8787
# Docker sets HOST=0.0.0.0. Set ADVAN_ALLOWED_HOSTS when you bind a public interface.

Docker：

docker build -t advan .
docker run --env-file .env -p 8787:8787 advan

イメージの USAGE_LOG_PATH のデフォルトは /data/usage.jsonl です。エントリーポイントはrootで起動し、/data の所有者を node に変更します（ボリュームがマウントされていない場合は /data を作成します）。その後、su-exec によってサーバーを node として実行します。使用状況ログを保持するには、ボリュームをマウントしてください。

docker run --env-file .env -p 8787:8787 -v advan-data:/data advan

.env.example からコピーした開発用 .env では、HOST=127.0.0.1 が設定されているため、コンテナ外部からポートにアクセスできません。ポートを公開するには、その環境変数ファイルで HOST=0.0.0.0 を設定するか、-e HOST=0.0.0.0 を渡してください。Flyでは fly.toml で HOST を設定します。

イメージで実行されるのはHTTPサーバーのみです。リファラル設定スクリプトはチェックアウトしたリポジトリから実行してください（npm install により、JupiterのリファラルSDKが開発依存関係としてインストールされます）。

Claude DesktopとCursor

有料ツールには、x402に対応したクライアントが必要です。Claude DesktopとCursorでは、token_risk および wallet_portfolio に対して支払い要求（または支払い未設定）エラーが表示されます。これらのクライアントは get_quote と build_swap_tx に使用し、有料ツールには scripts/e2e-devnet-x402.ts または createx402MCPClient を使用してください。

Claude Desktopの claude_desktop_config.json：

{
  "mcpServers": {
    "advan": {
      "command": "node",
      "args": ["/absolute/path/to/advan/dist/index.js"],
      "env": {
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
        "JUPITER_API_KEY": "",
        "JUPITER_REFERRAL_ACCOUNT": "",
        "JUPITER_REFERRAL_FEE_BPS": "50",
        "JUPITER_REFERRAL_TOKEN_ACCOUNT_SOL": "",
        "JUPITER_REFERRAL_TOKEN_ACCOUNT_USDC": "",
        "JUPITER_REFERRAL_TOKEN_ACCOUNT_USDT": "",
        "MAX_SLIPPAGE_BPS": "300",
        "MAX_TRADE_USD": "1000",
        "X402_PAY_TO": "",
        "X402_PRICE_USD": "0.01",
        "X402_NETWORK": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
        "CDP_API_KEY_ID": "",
        "CDP_API_KEY_SECRET": ""
      }
    }
  }
}

Cursorの .cursor/mcp.json では、同じ mcpServers オブジェクトを使用します。開発中は、リポジトリのルートから command に npx、args に ["tsx", "src/index.ts"] を指定できます。

HTTP API

POST の本文は JSON です。無料ルートはツールの結果を返します。有料ルートは、クライアントが PAYMENT-SIGNATURE を付けて再試行するまで、PAYMENT-REQUIRED とともに 402 を返します（x402 V2）。ウォレットを持たないブラウザーにはファシリテーターのペイウォール HTML が表示されます。Accept: application/json を送信する API クライアントには、unpaidResponseBody から JSON 本文も返されます。

メソッド	パス	本文
GET	/health	—
GET	/healthz	—
GET	/stats	—
POST	/v1/get_quote	{ "inputMint", "outputMint", "amount", "slippageBps"? }
POST	/v1/build_swap_tx	quote フィールドに taker、省略可能な selfBroadcast、省略可能な receiver を加えたもの
POST	/v1/token_risk	{ "mint" }
POST	/v1/wallet_portfolio	{ "owner" }
POST	/mcp	Streamable HTTP MCP（ステートレスな JSON レスポンス）

amount は基本単位で指定する整数文字列です。アドレスは base58 形式です。slippageBps は 0～10000 の整数で、その後 MAX_SLIPPAGE_BPS によって上限が設定されます。

例：

curl -s http://127.0.0.1:8787/healthz
curl -s http://127.0.0.1:8787/health
curl -s http://127.0.0.1:8787/v1/get_quote \
  -H 'content-type: application/json' \
  -d '{"inputMint":"So11111111111111111111111111111111111111112","outputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"10000000"}'

/stats は JSONL 使用状況ログを集計します。集計内容は、呼び出し数、今日の呼び出し数（UTC）、エラー数、fee_check_failure 行数、x402 の検証数／決済数／決済失敗数、受け取った USDC の基本単位数、インテグレーター紹介手数料の推定値（手数料 mint の feeBps の 80％）です。オンチェーンで発生した手数料は紹介用トークンアカウントの残高（referral.jup.ag または npm run claim:referral）であり、この推定値ではありません。

各ログ行は、kind が tool、fee_check_failure、referral_requote、x402_settlement、x402_verification、facilitator_failover、facilitator_recovered のいずれかである JSON オブジェクトです。また、該当する場合は tool、ts、latencyMs、success、error、errorCode、paymentStatus、facilitator、feeBps、feeMint、estimatedIntegratorFeeRaw、usdcAtomic も含まれます。/health はデータ RPC のオリジンと x402 RPC のオリジンを個別に報告します。

紹介設定

チェックアウトディレクトリから実行します（開発用依存関係 @jup-ag/referral-sdk が必要です）。

REFERRAL_PAYER_PUBKEY=<your wallet> REFERRAL_NAME=advan npm run setup:referral

このスクリプトは、Jupiter の紹介プロジェクト DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc を使用して、未署名のトランザクション（紹介アカウント、次に wSOL、USDC、USDT のトークンアカウント）を出力します。そのウォレットから順番に署名して送信してください。出力された紹介アカウントとトークンアカウントを .env に設定します。REFERRAL_MINTS を指定すると、手数料 mint を追加できます。REFERRAL_PARTNER_PUBKEY のデフォルト値は支払者です。

REFERRAL_PAYER_PUBKEY=<partner> JUPITER_REFERRAL_ACCOUNT=<account> npm run claim:referral

未署名の claimAllV2 トランザクションが出力されます。どちらのスクリプトでも署名は行われません。

Devnet x402 テスト

1. キーペアを作成し、ATA のセットアップに必要な場合のみ devnet SOL をリクエストします。x402 の exact スキームではファシリテーターが手数料を負担するため、購入者が呼び出しの支払いに必要なのは devnet USDC であり、SOL ではありません。
2. Circle のフォーセット（Solana Devnet）から devnet USDC を取得します。ミントアドレスは 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU です。
3. 受取人の USDC アカウントを作成します（未署名のため、自分で署名してください）。このスクリプトは X402_RPC_URL を使用します。未設定の場合は X402_NETWORK に対応するパブリック RPC を使用します。SOLANA_RPC_URL は読み込みません。

X402_NETWORK=solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 \
X402_PAY_TO=<payee pubkey> \
REFERRAL_PAYER_PUBKEY=<account that pays rent> \
X402_RPC_URL=https://api.devnet.solana.com \
npm run setup:payto-ata

4. X402_PAY_TO と X402_NETWORK（devnet）を設定して HTTP サーバーを起動します。token_risk で mainnet のミントアドレスを読み込む場合は、SOLANA_RPC_URL を mainnet のままにします。使用したいパブリック devnet RPC が別にある場合のみ X402_RPC_URL を設定します。未設定の場合、Advan は devnet の CAIP ID から https://api.devnet.solana.com を導出します。X402_RPC_URL を mainnet に向けないでください。CDP キーを使用するか、未設定のままにします（devnet では PayAI が無料です）。X402_PRICE_USD は 0.01 または 0.005 に設定できます。
5. 購入者のキーペアで支払います。X402_CLIENT_RPC_URL は USDC の送金に使用する購入者側の RPC です。パブリック devnet RPC は到達できないことが多いため、利用可能なものを設定してください。このスクリプトは token_risk と wallet_portfolio の料金を支払います。X402_NETWORK が devnet の場合、E2E_MINT のデフォルトは devnet USDC（4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU）です。それ以外の場合は mainnet USDC がデフォルトです。

SOLANA_KEYPAIR_PATH=./devnet-payer.json \
ADVAN_HTTP_URL=http://127.0.0.1:8787 \
X402_NETWORK=solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 \
X402_CLIENT_RPC_URL=https://api.devnet.solana.com \
npm run e2e:devnet

token_risk と wallet_portfolio は SOLANA_RPC_URL を読み込みます（デフォルトは mainnet）。支払い用ブロックハッシュの取得元は X402_RPC_URL のみです。devnet のポートフォリオに含まれるネイティブ SOL の価格も、devnet には SOL/USD の板情報がないため、Jupiter の mainnet wSOL 市場から取得されます。どちらが使用されたかは、レスポンスの sol.priceSource フィールドで確認できます。

MCP のスモークテスト（stdio および Streamable HTTP：ツールの一覧表示、オプションで Jupiter に get_quote と build_swap_tx をリクエストし、未払いの token_risk に対する支払い要求ペイロードを解析します）：

npm run smoke:mcp
SKIP_LIVE=1 npm run smoke:mcp

開発

npm run lint
npm run typecheck
npm test
npm run build

CI では Node 20 でこの 4 つのステップを実行します。ユニットテストでは Jupiter、RPC、ファシリテーターをモックします。

検討中の決定事項

これらはハードコードされたウォレットではなく、設定項目です。

• 紹介手数料 のデフォルトは最低値の 50 bps です。引き上げると（最大 255）、収益は増えますが、見積もりの競争力は低下します。Jupiter の取り分は 20% です。
• x402 の価格 のデフォルトは $0.01 です。これにより、PayAI の mainnet 決済（$0.00133）は価格の約 13% 未満に収まります。より低い利益幅を許容する場合は X402_PRICE_USD=0.005 に設定します。mainnet では 5 倍チェックで警告が表示されます。
• パッケージ名 advan-mcp は、2026-10-25 時点では未使用のようでした。.github/workflows/npm-publish.yml は GitHub リリース時（または手動のワークフロー実行時）に公開します。公開には、NPM_TOKEN として保存した npm トークンが引き続き必要です。
• Fly.io のホスティング は fly.toml と docs/DEPLOY-FLY.md に記載されています。Dockerfile は 8787 でリッスンします。本番トラフィックを受ける前に、SOLANA_RPC_URL に実際の RPC URL を設定してください。api.mainnet-beta.solana.com はレート制限されています。
• CDP キーは無料で作成できます。毎月、最初の 1,000 件の決済成功は無料で、その後は $0.001 です。devnet の決済がこの上限に含まれるかどうかは、CDP のドキュメントに記載されていません。
• PayAI には合計 1,000 件の無料クレジットがあります（月ごとではありません）。devnet の決済は無料です。チャージするかどうかは、支出に関する判断です。
• 自己ブロードキャストのデフォルト は、JupiterZ が競合できるようオフになっています。すべてのクライアントが独自にトランザクションをブロードキャストする場合は、SWAP_SELF_BROADCAST_DEFAULT をオンにします。
• FEE_CHECK_MODE のデフォルトは fail です。インテグレーター手数料が適用されなかったトランザクションでも返す場合に限り、warn を使用します。
• X402_PRICE_GUARD のデフォルトは warn です。低すぎる価格の場合にプロセスを停止する必要があれば、本番環境では refuse に設定します。