DeFi Copilot

Pay-per-decision DeFi intelligence for AI agents on Stellar. Built with x402 protocol — agents buy decisions, not subscriptions.

Overview

DeFi Copilot is a Stellar-native DeFi intelligence layer that allows AI agents to autonomously query DeFi data, execute swaps, and interact with DeFi protocols — paying per request using the x402 protocol. No API keys. No subscriptions. No human approval required.

Two ways to use:

• MCP Server — install in Claude Desktop or any MCP-compatible AI, agents query and pay automatically
• REST API — standard HTTP with x402 payment protocol, works with any HTTP client

Live backend: https://api.fxjrin.com

---

How It Works

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

---

Project Structure

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)

---

Prerequisites

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

---

Installation

1. Clone the repository

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

2. Install backend dependencies

npm install

3. Install MCP server dependencies

cd mcp-server
npm install
cd ..

---

Configuration

Backend .env

The .env file is generated automatically by npm run init. If you prefer to set it up manually, create .env in the defi-copilot/ root:

# 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

---

Quick Start

Step 1 — Initialize server wallet

Run the setup script to automatically generate and fund a server wallet:

npm run init

This will:

1. Generate a new Stellar keypair for the server
2. Fund with XLM via Friendbot (testnet only)
3. Set up USDC trustline
4. Save credentials to .env

Expected output:

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

Step 2 — Start the server

npm start

This starts both the API server (port 3000) and the x402 facilitator (port 4022) simultaneously.

Expected output:

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

Step 3 — Run the demo

Make sure npm start is running in another terminal, then:

npm run demo

The demo agent will auto-create its own wallet, fund it with USDC, and make payments automatically.

Expected output:

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 Reference

GET /health

Free. Returns server status.

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

GET /defi/yield/best

Cost: 0.001 USDC via x402

Query params:

• asset — USDC or XLM (default: USDC)
• amount — number (default: 1000)

Response:

{
  "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

Cost: 0.001 USDC via x402

Query params:

• from — source asset (default: XLM)
• to — target asset (default: USDC)
• amount — number (default: 100)

Response:

{
  "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 Payment Flow

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 Server

The MCP server allows AI agents (Claude, Cursor, etc.) to use DeFi Copilot tools directly in conversation, with automatic payment handling.

Install via Claude Code

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

Install via Claude Desktop config

Add to your 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"
      }
    }
  }
}

Note: DEFI_COPILOT_API defaults to https://api.fxjrin.com — no need to set it unless you run your own backend.

Available Tools

Tool	Cost	Description
get_best_yield	0.001 USDC	Best yield strategy — live from Blend Finance on-chain (Soroban)
get_best_swap	0.001 USDC	Optimal swap route — compares SDEX Orderbook, Stellar DEX, AMM
execute_swap	FREE	Execute real swap on Stellar DEX
deposit_blend	FREE	Deposit USDC to Blend Finance to earn yield (mainnet)
withdraw_blend	FREE	Withdraw USDC + interest from Blend Finance (mainnet)
get_blend_position	FREE	Check your Blend Finance deposit + interest earned (mainnet)
transfer	FREE	Send XLM or USDC to any Stellar address
get_market_data	FREE	Live XLM price, volume, spread from Stellar mainnet DEX
get_agent_wallet	FREE	Check or create agent wallet
fund_wallet	FREE	Show wallet address + QR code URL for funding
set_network	FREE	Switch between testnet and mainnet
get_transaction_history	FREE	View recent wallet transaction history
get_api_info	FREE	API info and pricing

Agent Wallet Behavior

On first use, the MCP server automatically:

1. Generates a new Stellar keypair
2. Funds with XLM via Friendbot (testnet only)
3. Sets up USDC trustline
4. Swaps 50 XLM to USDC for payment capability
5. Saves wallet to ~/.defi-copilot/wallet-testnet.json

Each user's wallet is stored locally on their own machine. Private keys never leave the user's device.

On mainnet, the wallet is created but not auto-funded — users must deposit XLM manually. This is intentional: mainnet uses real funds.

Network Switching

Switch networks within a conversation:

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)

Or set via environment variable (persists across sessions):

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

---

Data Sources

Data	Source	Network
Yield APY	Blend Finance smart contracts (Soroban)	Mainnet (on-chain)
Swap quotes	SDEX Orderbook + Stellar DEX pathfinder + AMM pool	Mainnet (real quotes)
XLM price	Stellar Horizon trade aggregations	Mainnet (real prices)
Orderbook spread	Stellar Horizon order book	Mainnet
24h volume	Stellar Horizon trade aggregations	Mainnet
Payments	x402 protocol	Testnet or Mainnet

All price and yield data comes directly from Stellar mainnet for accuracy, regardless of which network is used for payments.

---

Environment Variables

Backend (defi-copilot/.env)

Variable	Required	Description
STELLAR_NETWORK	No	testnet or mainnet (default: testnet)
SERVER_SECRET_KEY	Yes	Secret key for server wallet (receives payments)
SERVER_PUBLIC_KEY	Yes	Public key for server wallet
PORT	No	Server port (default: 3000)

MCP Server (via config or shell env)

Variable	Required	Description
STELLAR_NETWORK	No	testnet or mainnet (default: testnet)
DEFI_COPILOT_API	No	Backend API URL (default: https://api.fxjrin.com)

---

npm Scripts

Backend (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 Server (defi-copilot/mcp-server/)

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

---

Deployment

Backend on 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

After deploying, nginx reverse proxy + SSL via certbot is recommended:

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

---

License

MIT