Defi Copilot

DeFi Copilot

Stellar上のAIエージェント向けに、利用ごとに支払うDeFiインテリジェンスを提供します。x402プロトコルを使用して構築されており、エージェントはサブスクリプションではなく、意思決定ごとに料金を支払います。

概要

DeFi CopilotはStellarネイティブのDeFiインテリジェンスレイヤーです。AIエージェントがx402プロトコルを使用してリクエストごとに支払い、自律的にDeFiデータを照会し、スワップを実行し、DeFiプロトコルとやり取りできます。APIキーは不要です。サブスクリプションも不要です。人による承認も必要ありません。

2つの利用方法：

• MCP サーバー — Claude DesktopまたはMCP互換のAIにインストールすると、エージェントが自動的に照会と支払いを行います
• REST API — x402決済プロトコルを使用する標準HTTPで、あらゆるHTTPクライアントで利用できます

稼働中のバックエンド： https://api.fxjrin.com

---

動作の仕組み

User / AI Agent
      |
      | (natural language or direct API call)
      v
MCP Server (defi-copilot-mcp)
      |
      | GET /defi/yield/best
      v
Backend API (port 3000)
      |
      | 402 Payment Required
      v
Agent builds + signs Stellar USDC tx
      |
      | x-payment header
      v
Facilitator verifies + settles (port 4022)
      |
      | on-chain settlement on Stellar
      v
Return DeFi intelligence

---

プロジェクト構成

defi-copilot/
  src/
    server.ts                  # Express server
    routes/
      yield.ts                 # GET /defi/yield/best
      swap.ts                  # GET /defi/swap/best
    services/
      scorer.ts                # Market data + Blend on-chain APY + DEX quotes
    utils/
      x402-middleware.ts       # x402 payment verification
      network.ts               # Network config (testnet/mainnet)
      http.ts                  # IPv4-forced HTTP client (undici)
      init.ts                  # Server wallet setup script
    facilitator/
      index.ts                 # Local x402 facilitator (port 4022)
    agent/
      client.ts                # Agent payment client with auto-create wallet
      demo.ts                  # Demo script
  mcp-server/
    src/
      index.ts                 # MCP tools + auto-create wallet
      network.ts               # Network config for MCP
      http.ts                  # IPv4-forced HTTP client (undici)

---

前提条件

• Node.js v18+
• npm v9+
• Git

---

インストール

1. リポジトリをクローンする

git clone https://github.com/fxjrin/defi-copilot.git
cd defi-copilot

2. バックエンドの依存関係をインストールする

npm install

3. MCP サーバーの依存関係をインストールする

cd mcp-server
npm install
cd ..

---

設定

バックエンドの .env

.envファイルはnpm run initによって自動的に生成されます。手動で設定する場合は、defi-copilot/のルートに.envを作成してください。

# Stellar network: testnet or mainnet
STELLAR_NETWORK=testnet

# Server wallet — receives x402 payments
# Generated automatically by: npm run init
SERVER_SECRET_KEY=
SERVER_PUBLIC_KEY=

PORT=3000

---

クイックスタート

ステップ1 — サーバーウォレットを初期化する

セットアップスクリプトを実行すると、サーバーウォレットが自動的に生成され、資金が入金されます。

npm run init

このスクリプトでは、以下が行われます。

1. サーバー用の新しいStellarキーペアを生成します
2. Friendbot経由でXLMを入金します（テストネットのみ）
3. USDCのトラストラインを設定します
4. 認証情報を.envに保存します

出力例：

DeFi Copilot — Initial Setup
Network: testnet
Generating server wallet...
  Public key : GXXXX...
  Secret key : SXXX*...XXXX (saved to .env)
  Credentials saved to .env
  Funding via Friendbot...
  XLM funded successfully
  Waiting for account activation...
Setting up USDC trustline...
  USDC trustline created
Final balances:
  USDC: 0.0000
  XLM: 10000.0000
Setup complete!
Run: npm start

ステップ2 — サーバーを起動する

npm start

APIサーバー（ポート3000）とx402ファシリテーター（ポート4022）が同時に起動します。

出力例：

[api]          🚀 DeFi Copilot API running on port 3000
[api]             Network : testnet
[api]             Wallet  : GXXXX...
[facilitator]  ⚡ Local x402 Facilitator running on port 4022

ステップ3 — デモを実行する

別のターミナルでnpm startが実行中であることを確認してから、次を実行します。

npm run demo

デモエージェントは独自のウォレットを自動的に作成し、USDCを入金して、自動的に支払いを行います。

出力例：

DeFi Copilot Agent Demo
Initializing agent wallet...
  No wallet found — creating new agent wallet on Stellar testnet...
  Funding with XLM via Friendbot...
  XLM funded successfully
  Setting up USDC trustline...
  Swapping XLM to USDC...
  USDC funded successfully
  Agent wallet ready: GXXXX...

DEMO 1: Where should I put my USDC?
  Agent requesting: http://localhost:3000/defi/yield/best
  Payment required: 0.0010 USDC
  Payment accepted!
  Strategy   : Deposit to Fixed V2 on Blend Finance
  APY        : 9.47% (live on-chain)
  Risk       : low
  Confidence : 95%

DEMO 2: Best route to swap 500 XLM to USDC?
  Agent requesting: http://localhost:3000/defi/swap/best
  Payment accepted!
  Route          : SDEX Orderbook
  Expected output: 75.88 USDC
  Slippage       : 0.005%
  Confidence     : 99%

---

APIリファレンス

GET /health

無料です。サーバーのステータスを返します。

{
  "status": "ok",
  "network": "testnet",
  "server_wallet": "GXXXX..."
}

GET /defi/yield/best

料金：x402経由で0.001 USDC

クエリパラメーター：

• asset — USDCまたはXLM（デフォルト：USDC）
• amount — 数値（デフォルト：1000）

レスポンス：

{
  "strategy": "Deposit to Fixed V2 on Blend Finance",
  "protocol": "Blend Finance",
  "apy": "9.47%",
  "risk": "low",
  "reasoning": "Live Blend Finance on-chain APY. Pool comparison: Fixed V2: USDC 9.47% | YieldBlox V2: USDC 0.07%",
  "confidence": 0.95,
  "marketData": {
    "xlmPrice": "0.1518 USDC",
    "spread": "0.3945%",
    "volume24h": "4531.6K XLM",
    "source": "Blend Finance (on-chain Soroban) + Stellar mainnet DEX"
  },
  "alternatives": [...]
}

GET /defi/swap/best

料金：x402経由で0.001 USDC

クエリパラメーター：

• from — 送信元アセット（デフォルト：XLM）
• to — 送信先アセット（デフォルト：USDC）
• amount — 数値（デフォルト：100）

レスポンス：

{
  "from": "XLM",
  "to": "USDC",
  "amount": 500,
  "route": ["SDEX Orderbook"],
  "expectedOutput": "75.88 USDC",
  "slippage": "0.005%",
  "priceImpact": "low",
  "marketPrice": "1 XLM = 0.1518 USDC",
  "confidence": 0.99,
  "reasoning": "DEX comparison: SDEX Orderbook: 75.88 USDC | Stellar DEX: 75.80 USDC | Stellar AMM: 75.70 USDC"
}

x402決済フロー

1. Client → GET /defi/yield/best
2. Server ← 402 Payment Required
   {
     "x402Version": 1,
     "accepts": [{
       "scheme": "exact",
       "network": "stellar-testnet",
       "maxAmountRequired": "10000",
       "asset": "CBIELTK6...",
       "payTo": "GXXXX..."
     }]
   }
3. Client builds + signs Stellar USDC payment tx
4. Client → GET /defi/yield/best
           x-payment: <base64-encoded-payload>
5. Facilitator verifies transaction
6. Facilitator settles on Stellar
7. Server → 200 OK with DeFi intelligence

---

MCP サーバー

MCP サーバーを使うと、AIエージェント（Claude、Cursorなど）が会話内でDeFi Copilotのツールを直接利用でき、支払いも自動的に処理されます。

Claude Codeからインストールする

claude mcp add defi-copilot -- npx -y defi-copilot-mcp

Claude Desktopの設定からインストールする

claude_desktop_config.jsonに追加します。

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows： %APPDATA%\Claude\claude_desktop_config.json

Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "defi-copilot": {
      "command": "npx",
      "args": ["-y", "defi-copilot-mcp"],
      "env": {
        "STELLAR_NETWORK": "testnet"
      }
    }
  }
}

注： DEFI_COPILOT_APIのデフォルト値はhttps://api.fxjrin.comです。独自のバックエンドを実行する場合を除き、設定する必要はありません。

利用可能なツール

ツール	料金	説明
get_best_yield	0.001 USDC	最適な利回り戦略 — Blend Finance のオンチェーン（Soroban）データをリアルタイムで取得
get_best_swap	0.001 USDC	最適なスワップルート — SDEX Orderbook、Stellar DEX、AMM を比較
execute_swap	無料	Stellar DEX で実際のスワップを実行
deposit_blend	無料	利回りを得るために Blend Finance に USDC を預け入れ（メインネット）
withdraw_blend	無料	Blend Finance から USDC と利息を引き出し（メインネット）
get_blend_position	無料	Blend Finance への預け入れ額と獲得利息を確認（メインネット）
transfer	無料	任意の Stellar アドレスに XLM または USDC を送信
get_market_data	無料	Stellar メインネット DEX の XLM 価格、取引量、スプレッドをリアルタイムで取得
get_agent_wallet	無料	エージェントのウォレットを確認または作成
fund_wallet	無料	資金調達用のウォレットアドレスと QR コード URL を表示
set_network	無料	テストネットとメインネットを切り替え
get_transaction_history	無料	最近のウォレット取引履歴を表示
get_api_info	無料	API 情報と料金

エージェントウォレットの動作

初回使用時、MCP サーバーは自動的に以下を実行します。

1. 新しい Stellar キーペアを生成
2. Friendbot 経由で XLM を入金（テストネットのみ）
3. USDC のトラストラインを設定
4. 支払いに利用できるよう、50 XLM を USDC にスワップ
5. ウォレットを ~/.defi-copilot/wallet-testnet.json に保存

各ユーザーのウォレットは、それぞれの端末にローカルで保存されます。秘密鍵がユーザーの端末から外部に送信されることはありません。

メインネットではウォレットは作成されますが、自動で入金されません。ユーザーが手動で XLM を入金する必要があります。これは意図的な仕様です。メインネットでは実際の資金を使用します。

ネットワークの切り替え

会話中にネットワークを切り替えます。

User: "Switch to mainnet"
Claude: calls set_network(network="mainnet")

User: "Deposit 10 USDC to Blend Finance"
Claude: calls deposit_blend(amount=10, confirmed=true)

または、環境変数で設定します（セッション間で保持されます）。

"env": {
  "STELLAR_NETWORK": "mainnet"
}

---

データソース

データ	ソース	ネットワーク
利回り APY	Blend Finance のスマートコントラクト（Soroban）	メインネット（オンチェーン）
スワップ見積もり	SDEX Orderbook + Stellar DEX パスファインダー + AMM プール	メインネット（実際の見積もり）
XLM 価格	Stellar Horizon の取引集計	メインネット（実際の価格）
オーダーブックのスプレッド	Stellar Horizon のオーダーブック	メインネット
24 時間の取引量	Stellar Horizon の取引集計	メインネット
支払い	x402 プロトコル	テストネットまたはメインネット

支払いにどのネットワークを使用するかにかかわらず、正確性を保つため、価格と利回りのデータはすべて Stellar メインネットから直接取得します。

---

環境変数

バックエンド（defi-copilot/.env）

変数	必須	説明
STELLAR_NETWORK	いいえ	testnet または mainnet（デフォルト：testnet）
SERVER_SECRET_KEY	はい	サーバーウォレットの秘密鍵（支払いを受け取ります）
SERVER_PUBLIC_KEY	はい	サーバーウォレットの公開鍵
PORT	いいえ	サーバーのポート（デフォルト：3000）

MCP サーバー（設定またはシェル環境変数で指定）

変数	必須	説明
STELLAR_NETWORK	いいえ	testnet または mainnet（デフォルト：testnet）
DEFI_COPILOT_API	いいえ	バックエンド API の URL（デフォルト：https://api.fxjrin.com）

---

npm スクリプト

バックエンド（defi-copilot/）

npm run init        # Generate and fund server wallet
npm start           # Start API + facilitator together
npm run dev         # Start API only (port 3000)
npm run facilitator # Start facilitator only (port 4022)
npm run demo        # Run agent payment demo
npm run build       # Compile TypeScript

MCP サーバー（defi-copilot/mcp-server/）

npm run build       # Compile TypeScript
npm run dev         # Run without compiling (tsx)

---

デプロイ

VPS へのバックエンドのデプロイ

git clone https://github.com/fxjrin/defi-copilot.git
cd defi-copilot
npm install

# Initialize server wallet
npm run init

# Install pm2 for process management
npm install -g pm2

# Start both api and facilitator
pm2 start npm --name defi-copilot -- start
pm2 save
pm2 startup

デプロイ後は、nginx のリバースプロキシと certbot による SSL の設定を推奨します。

apt install -y nginx certbot python3-certbot-nginx
# configure nginx to proxy port 3000
certbot --nginx -d your-domain.com

---

ライセンス

MIT