Path402 MCP Server

path402

Turn AI agents into autonomous economic actors. Run a $402 network node.

This package includes:

• MCP Server — AI agent tools for Claude, GPT, etc.
• path402d Daemon — Index tokens, serve content, earn rewards

---

Quick Start

Installation

npm install -g path402

Run path402d Daemon

path402d start

This starts a $402 network node that:

• INDEX — Reads BSV blockchain, tracks all $402 tokens
• VALIDATE — Confirms token ownership before serving
• SERVE — Delivers content to verified token holders
• EARN — Receives $402 rewards via PoW20

path402d CLI Commands

path402d start           # Start the daemon
path402d status          # Check if running
path402d stop            # Stop the daemon
path402d config          # Show configuration
path402d mine            # Start PoW20 mining (experimental)
path402d --help          # Full help

Why Run path402d?

PoW forces operators into the open. Big nodes can't hide.

The purpose of PoW20 is NOT just to reward work—it's to force operators into visibility:

• Computational cost → Capital investment → Scale
• Scale → Physical presence → Regulatory visibility
• Big nodes must identify themselves

No anonymous propaganda dealers running underground BitTorrent clients with no accountability.

---

MCP Server (for AI Agents)

npx path402

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "path402": {
      "command": "npx",
      "args": ["path402"],
      "env": {
        "PATH402_API_URL": "https://path402.com",
        "PATH402_DEFAULT_BUDGET": "10000"
      }
    }
  }
}

First Conversation

You: "Discover what's available at $example.com"

Claude: [Uses path402_discover to probe the $address]
        Found 3 nested tokens:
        - $example.com/$blog (500 sats, 0 supply)
        - $example.com/$api (1000 sats, 0 supply)
        - $example.com/$premium (2500 sats, 0 supply)

You: "Evaluate if $example.com/$blog is worth acquiring"

Claude: [Uses path402_evaluate and path402_economics]
        ROI Analysis:
        - Current price: 500 sats
        - Breakeven: 1 serve at current rates
        - Projected ROI: 340% over 30 days
        Recommendation: ACQUIRE (high confidence)

You: "Acquire 10 tokens"

Claude: [Uses path402_acquire]
        Acquired 10 $example.com/$blog tokens
        Total cost: 5,000 sats
        New balance: 10 tokens

---

The $402 Protocol

What is $402?

$402 turns URL paths into tokenized markets. Any path prefixed with $ becomes an economic object:

$example.com              → Site-level token
$example.com/$api         → API access token
$example.com/$api/$premium → Premium tier token

Each token has:

• Price curve (ascending bonding curve by default)
• Supply counter (increases with each acquisition)
• Holder registry (who owns what)
• Revenue distribution (issuer/facilitator split)

Ascending Bonding Curve

Price is determined by remaining treasury, not speculation:

price = base_price / √(treasury_remaining + 1)

Key insight: Early buyers always get better prices. This creates natural incentives for discovery and early adoption.

Self-Funding Agents

Agents can become economically self-sustaining:

1. Acquire tokens at current price
2. Serve content to other agents/users
3. Earn revenue from serving
4. Reinvest profits into more tokens

The ascending bonding curve mathematically guarantees that early acquirers can achieve positive ROI through serving.

---

Complete Tool Reference

Discovery & Evaluation

path402_discover

// Input
{
  address: "$example.com/$api"
}

// Output
{
  address: "$example.com/$api",
  exists: true,
  pricing: {
    model: "alice_bond",
    base_price_sats: 1000,
    current_price_sats: 45,
    treasury_remaining: 499500000
  },
  supply: {
    total: 500000,
    max: null
  },
  revenue_split: {
    issuer_bps: 8000,
    facilitator_bps: 2000
  },
  nested: [
    "$example.com/$api/$premium",
    "$example.com/$api/$enterprise"
  ],
  content_type: "application/json",
  description: "API access credits"
}

path402_evaluate

// Input
{
  address: "$example.com/$api",
  amount: 100,
  budget_sats: 10000
}

// Output
{
  recommendation: "ACQUIRE",
  confidence: 0.85,
  analysis: {
    total_cost_sats: 4500,
    within_budget: true,
    avg_price_per_token: 45,
    breakeven_serves: 5,
    projected_roi_30d: 0.34,
    risk_level: "low"
  },
  reasoning: "Early position in growing market. Favorable price curve."
}

Acquisition & Wallet

path402_acquire

// Input
{
  address: "$example.com/$api",
  amount: 100
}

// Output
{
  success: true,
  acquired: 100,
  total_cost_sats: 4500,
  avg_price: 45,
  new_balance: 100,
  content: {
    type: "api_key",
    value: "sk_live_xxx...",
    expires: null
  },
  txId: "bsv_abc123..."
}

path402_wallet

// Output
{
  balance_sats: 45000,
  holdings: [
    {
      address: "$example.com/$api",
      balance: 100,
      avg_cost: 45,
      current_value: 4800,
      unrealized_pnl: 300
    }
  ],
  total_value_sats: 49800,
  total_cost_sats: 49500,
  net_pnl_sats: 300,
  serving_revenue_sats: 1200
}

Serving & Revenue

path402_serve

// Input
{
  address: "$example.com/$api",
  requester: "agent_xyz",
  amount: 1
}

// Output
{
  served: true,
  tokens_consumed: 1,
  revenue_earned_sats: 40,
  remaining_balance: 99,
  content_delivered: true
}

path402_servable

// Output
{
  servable: [
    {
      address: "$example.com/$api",
      balance: 99,
      serves_remaining: 99,
      revenue_per_serve: 40,
      total_potential_revenue: 3960
    }
  ],
  total_serves_available: 99,
  total_potential_revenue_sats: 3960
}

x402 Facilitator Tools

x402_verify

// Input
{
  payment_proof: "0xabc123...",
  network: "base",
  expected_amount: 1000,
  expected_recipient: "0x..."
}

// Output
{
  valid: true,
  network: "base",
  amount_sats: 1000,
  recipient: "0x...",
  sender: "0x...",
  txId: "0x...",
  timestamp: "2026-02-02T10:00:00Z",
  facilitator: "path402.com"
}

---

Configuration

Environment Variables

Advanced Configuration

{
  "mcpServers": {
    "path402": {
      "command": "npx",
      "args": ["path402"],
      "env": {
        "PATH402_API_URL": "https://path402.com",
        "PATH402_DEFAULT_BUDGET": "50000",
        "PATH402_AUTO_ACQUIRE": "true",
        "PATH402_MAX_SINGLE_SPEND": "10000",
        "PATH402_WALLET_KEY": "your-wallet-key",
        "PATH402_LOG_LEVEL": "debug"
      }
    }
  }
}

---

Use Cases

1. Content Discovery Agent

Agent explores the $402 namespace, discovering valuable content:

1. path402_batch_discover(["$news.com", "$research.org", "$data.io"])
2. path402_evaluate() on promising finds
3. path402_acquire() undervalued tokens
4. path402_serve() to users who request content

2. API Gateway Agent

Agent manages API access for a team:

1. path402_acquire("$api.service.com", 1000)
2. path402_wallet() to track usage
3. path402_serve() when team members need API calls
4. path402_acquire() more when balance runs low

3. Research Agent

Agent gathers information from paywalled sources:

1. path402_discover() research databases
2. path402_economics() to evaluate cost/benefit
3. path402_acquire() access to valuable sources
4. Compile research using acquired content

4. Revenue-Generating Agent

Agent that pays for itself:

1. path402_acquire() tokens at low prices
2. path402_servable() to list inventory
3. path402_serve() to other agents
4. path402_wallet() to track profits
5. Reinvest profits into more tokens

---

Supported Networks

BSV is the settlement layer. Payments from other chains are verified and inscribed on BSV for permanent proof.

---

API Reference

PATH402.com Endpoints

$PATH402 Token (PATH402's own token)

Multi-Tenant Marketplace (any $address)

x402 Facilitator (payment verification)

---

Development

Running Locally

git clone https://github.com/b0ase/path402
cd path402
npm install
npm run dev

Testing

npm test
npm run test:integration

Building

npm run build

---

Roadmap

v1.0.0 (Current)

• ✅ 10 core tools
• ✅ ascending bonding curve pricing
• ✅ Budget management
• ✅ Simulated acquisition/serving

v1.1.0 (In Progress)

• 🔲 Live HTTP client for path402.com
• 🔲 x402 facilitator tools (verify, settle, inscription)
• 🔲 Real payment integration

v1.2.0 (Planned)

• 🔲 Transfer and history tools
• 🔲 Multi-agent coordination
• 🔲 Persistent storage

v1.3.0 (Planned)

• 🔲 Creator tools (register)
• 🔲 Advanced analytics
• 🔲 Agent marketplace integration

---

Contributing

Contributions welcome! Please read our Contributing Guide.

# Fork the repo
git checkout -b feature/your-feature
# Make changes
npm test
git commit -m "Add your feature"
git push origin feature/your-feature
# Open a PR

---

License

Open BSV License version 4

---

Links

• Website: path402.com
• Whitepaper: path402.com/whitepaper
• Exchange: path402.com/exchange
• Documentation: path402.com/docs
• GitHub: github.com/b0ase/path402

---

Support

• Issues: GitHub Issues
• Email: hello@b0ase.com
• Twitter: @b0ase