{
  "markdown": "# path402\n\n**Turn AI agents into autonomous economic actors. Run a $402 network node.**\n\nThis package includes:\n\n- **MCP Server** — AI agent tools for Claude, GPT, etc.\n- **path402d Daemon** — Index tokens, serve content, earn rewards\n\n[![npm version](https://badge.fury.io/js/path402.svg)](https://www.npmjs.com/package/path402)\n[![License: Open BSV](https://img.shields.io/badge/License-Open%20BSV-blue.svg)](LICENSE)\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install -g path402\n```\n\n### Run path402d Daemon\n\n```bash\npath402d start\n```\n\nThis starts a $402 network node that:\n\n- **INDEX** — Reads BSV blockchain, tracks all $402 tokens\n- **VALIDATE** — Confirms token ownership before serving\n- **SERVE** — Delivers content to verified token holders\n- **EARN** — Receives $402 rewards via PoW20\n\n### path402d CLI Commands\n\n```bash\npath402d start           # Start the daemon\npath402d status          # Check if running\npath402d stop            # Stop the daemon\npath402d config          # Show configuration\npath402d mine            # Start PoW20 mining (experimental)\npath402d --help          # Full help\n```\n\n### Why Run path402d?\n\n**PoW forces operators into the open. Big nodes can't hide.**\n\nThe purpose of PoW20 is NOT just to reward work—it's to force operators into visibility:\n\n- Computational cost → Capital investment → Scale\n- Scale → Physical presence → Regulatory visibility\n- Big nodes must identify themselves\n\nNo anonymous propaganda dealers running underground BitTorrent clients with no accountability.\n\n---\n\n## MCP Server (for AI Agents)\n\n```bash\nnpx path402\n```\n\n### Claude Desktop Integration\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"path402\": {\n      \"command\": \"npx\",\n      \"args\": [\"path402\"],\n      \"env\": {\n        \"PATH402_API_URL\": \"https://path402.com\",\n        \"PATH402_DEFAULT_BUDGET\": \"10000\"\n      }\n    }\n  }\n}\n```\n\n### First Conversation\n\n```\nYou: \"Discover what's available at $example.com\"\n\nClaude: [Uses path402_discover to probe the $address]\n        Found 3 nested tokens:\n        - $example.com/$blog (500 sats, 0 supply)\n        - $example.com/$api (1000 sats, 0 supply)\n        - $example.com/$premium (2500 sats, 0 supply)\n\nYou: \"Evaluate if $example.com/$blog is worth acquiring\"\n\nClaude: [Uses path402_evaluate and path402_economics]\n        ROI Analysis:\n        - Current price: 500 sats\n        - Breakeven: 1 serve at current rates\n        - Projected ROI: 340% over 30 days\n        Recommendation: ACQUIRE (high confidence)\n\nYou: \"Acquire 10 tokens\"\n\nClaude: [Uses path402_acquire]\n        Acquired 10 $example.com/$blog tokens\n        Total cost: 5,000 sats\n        New balance: 10 tokens\n```\n\n---\n\n## The $402 Protocol\n\n### What is $402?\n\n$402 turns URL paths into tokenized markets. Any path prefixed with `$` becomes an economic object:\n\n```\n$example.com              → Site-level token\n$example.com/$api         → API access token\n$example.com/$api/$premium → Premium tier token\n```\n\nEach token has:\n\n- **Price curve** (ascending bonding curve by default)\n- **Supply counter** (increases with each acquisition)\n- **Holder registry** (who owns what)\n- **Revenue distribution** (issuer/facilitator split)\n\n### Ascending Bonding Curve\n\nPrice is determined by remaining treasury, not speculation:\n\n```\nprice = base_price / √(treasury_remaining + 1)\n```\n\n| Treasury | Price | % Sold |\n|----------|-------|--------|\n| 500M | 10 sats | 0% |\n| 100M | 22 sats | 80% |\n| 10M | 71 sats | 98% |\n| 1M | 224 sats | 99.8% |\n| 1K | 7,072 sats | 99.9998% |\n\n**Key insight**: Early buyers always get better prices. This creates natural incentives for discovery and early adoption.\n\n### Self-Funding Agents\n\nAgents can become economically self-sustaining:\n\n1. Acquire tokens at current price\n2. Serve content to other agents/users\n3. Earn revenue from serving\n4. Reinvest profits into more tokens\n\nThe ascending bonding curve mathematically guarantees that early acquirers can achieve positive ROI through serving.\n\n---\n\n## Complete Tool Reference\n\n### Discovery & Evaluation\n\n| Tool | Description |\n|------|-------------|\n| `path402_discover` | Probe a $address for pricing, supply, revenue model, and nested paths |\n| `path402_batch_discover` | Discover multiple $addresses in a single call |\n| `path402_evaluate` | Assess ROI viability before purchasing |\n| `path402_economics` | Deep financial analysis: breakeven, projections, scenarios |\n| `path402_price_schedule` | View how price changes across supply levels |\n\n#### path402_discover\n\n```javascript\n// Input\n{\n  address: \"$example.com/$api\"\n}\n\n// Output\n{\n  address: \"$example.com/$api\",\n  exists: true,\n  pricing: {\n    model: \"alice_bond\",\n    base_price_sats: 1000,\n    current_price_sats: 45,\n    treasury_remaining: 499500000\n  },\n  supply: {\n    total: 500000,\n    max: null\n  },\n  revenue_split: {\n    issuer_bps: 8000,\n    facilitator_bps: 2000\n  },\n  nested: [\n    \"$example.com/$api/$premium\",\n    \"$example.com/$api/$enterprise\"\n  ],\n  content_type: \"application/json\",\n  description: \"API access credits\"\n}\n```\n\n#### path402_evaluate\n\n```javascript\n// Input\n{\n  address: \"$example.com/$api\",\n  amount: 100,\n  budget_sats: 10000\n}\n\n// Output\n{\n  recommendation: \"ACQUIRE\",\n  confidence: 0.85,\n  analysis: {\n    total_cost_sats: 4500,\n    within_budget: true,\n    avg_price_per_token: 45,\n    breakeven_serves: 5,\n    projected_roi_30d: 0.34,\n    risk_level: \"low\"\n  },\n  reasoning: \"Early position in growing market. Favorable price curve.\"\n}\n```\n\n### Acquisition & Wallet\n\n| Tool | Description |\n|------|-------------|\n| `path402_acquire` | Purchase tokens and receive gated content |\n| `path402_set_budget` | Configure agent spending parameters |\n| `path402_wallet` | View balance, holdings, and net financial position |\n| `path402_transfer` | Transfer tokens to another address |\n| `path402_history` | View transaction history |\n\n#### path402_acquire\n\n```javascript\n// Input\n{\n  address: \"$example.com/$api\",\n  amount: 100\n}\n\n// Output\n{\n  success: true,\n  acquired: 100,\n  total_cost_sats: 4500,\n  avg_price: 45,\n  new_balance: 100,\n  content: {\n    type: \"api_key\",\n    value: \"sk_live_xxx...\",\n    expires: null\n  },\n  txId: \"bsv_abc123...\"\n}\n```\n\n#### path402_wallet\n\n```javascript\n// Output\n{\n  balance_sats: 45000,\n  holdings: [\n    {\n      address: \"$example.com/$api\",\n      balance: 100,\n      avg_cost: 45,\n      current_value: 4800,\n      unrealized_pnl: 300\n    }\n  ],\n  total_value_sats: 49800,\n  total_cost_sats: 49500,\n  net_pnl_sats: 300,\n  serving_revenue_sats: 1200\n}\n```\n\n### Serving & Revenue\n\n| Tool | Description |\n|------|-------------|\n| `path402_serve` | Distribute content and earn revenue |\n| `path402_servable` | List all content the agent can serve |\n| `path402_register` | Register a new $address as issuer |\n\n#### path402_serve\n\n```javascript\n// Input\n{\n  address: \"$example.com/$api\",\n  requester: \"agent_xyz\",\n  amount: 1\n}\n\n// Output\n{\n  served: true,\n  tokens_consumed: 1,\n  revenue_earned_sats: 40,\n  remaining_balance: 99,\n  content_delivered: true\n}\n```\n\n#### path402_servable\n\n```javascript\n// Output\n{\n  servable: [\n    {\n      address: \"$example.com/$api\",\n      balance: 99,\n      serves_remaining: 99,\n      revenue_per_serve: 40,\n      total_potential_revenue: 3960\n    }\n  ],\n  total_serves_available: 99,\n  total_potential_revenue_sats: 3960\n}\n```\n\n### x402 Facilitator Tools\n\n| Tool | Description |\n|------|-------------|\n| `x402_verify` | Verify payment proof from any supported chain |\n| `x402_settle` | Settle cross-chain payment via facilitator |\n| `x402_inscription` | Get or create BSV inscription proof |\n\n#### x402_verify\n\n```javascript\n// Input\n{\n  payment_proof: \"0xabc123...\",\n  network: \"base\",\n  expected_amount: 1000,\n  expected_recipient: \"0x...\"\n}\n\n// Output\n{\n  valid: true,\n  network: \"base\",\n  amount_sats: 1000,\n  recipient: \"0x...\",\n  sender: \"0x...\",\n  txId: \"0x...\",\n  timestamp: \"2026-02-02T10:00:00Z\",\n  facilitator: \"path402.com\"\n}\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PATH402_API_URL` | `https://path402.com` | API endpoint |\n| `PATH402_DEFAULT_BUDGET` | `10000` | Default budget in sats |\n| `PATH402_WALLET_KEY` | - | Wallet signing key (for payments) |\n| `PATH402_AUTO_ACQUIRE` | `false` | Auto-acquire when recommended |\n| `PATH402_MAX_SINGLE_SPEND` | `5000` | Max sats per single acquisition |\n| `PATH402_LOG_LEVEL` | `info` | Logging verbosity |\n\n### Advanced Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"path402\": {\n      \"command\": \"npx\",\n      \"args\": [\"path402\"],\n      \"env\": {\n        \"PATH402_API_URL\": \"https://path402.com\",\n        \"PATH402_DEFAULT_BUDGET\": \"50000\",\n        \"PATH402_AUTO_ACQUIRE\": \"true\",\n        \"PATH402_MAX_SINGLE_SPEND\": \"10000\",\n        \"PATH402_WALLET_KEY\": \"your-wallet-key\",\n        \"PATH402_LOG_LEVEL\": \"debug\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Use Cases\n\n### 1. Content Discovery Agent\n\nAgent explores the $402 namespace, discovering valuable content:\n\n```\n1. path402_batch_discover([\"$news.com\", \"$research.org\", \"$data.io\"])\n2. path402_evaluate() on promising finds\n3. path402_acquire() undervalued tokens\n4. path402_serve() to users who request content\n```\n\n### 2. API Gateway Agent\n\nAgent manages API access for a team:\n\n```\n1. path402_acquire(\"$api.service.com\", 1000)\n2. path402_wallet() to track usage\n3. path402_serve() when team members need API calls\n4. path402_acquire() more when balance runs low\n```\n\n### 3. Research Agent\n\nAgent gathers information from paywalled sources:\n\n```\n1. path402_discover() research databases\n2. path402_economics() to evaluate cost/benefit\n3. path402_acquire() access to valuable sources\n4. Compile research using acquired content\n```\n\n### 4. Revenue-Generating Agent\n\nAgent that pays for itself:\n\n```\n1. path402_acquire() tokens at low prices\n2. path402_servable() to list inventory\n3. path402_serve() to other agents\n4. path402_wallet() to track profits\n5. Reinvest profits into more tokens\n```\n\n---\n\n## Supported Networks\n\n| Network | Status | Assets |\n|---------|--------|--------|\n| BSV | Primary | BSV, BSV-20 tokens |\n| Base | Supported | USDC, ETH |\n| Solana | Supported | USDC, SOL |\n| Ethereum | Supported | USDC, ETH, USDT |\n\nBSV is the settlement layer. Payments from other chains are verified and inscribed on BSV for permanent proof.\n\n---\n\n## API Reference\n\n### PATH402.com Endpoints\n\n**$PATH402 Token** (PATH402's own token)\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/token/stats` | GET | $PATH402 statistics & pricing |\n| `/api/token/buy` | POST | Acquire $PATH402 tokens |\n| `/api/token/holding` | GET | User's $PATH402 holdings |\n\n**Multi-Tenant Marketplace** (any $address)\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/tokens` | GET | List all registered tokens |\n| `/api/tokens` | POST | Register new $address |\n| `/api/tokens/[address]` | GET | Token details + price schedule |\n| `/api/tokens/[address]` | POST | Acquire tokens |\n| `/api/tokens/holdings` | GET | User's holdings (all tokens) |\n| `/api/tokens/transfer` | POST | Transfer tokens |\n| `/api/tokens/history` | GET | Transaction history |\n\n**x402 Facilitator** (payment verification)\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/.well-known/x402.json` | GET | Discovery document |\n| `/api/x402/verify` | POST | Verify payment |\n| `/api/x402/settle` | POST | Settle payment |\n| `/api/x402/inscription` | GET/POST | Inscription management |\n| `/api/x402/stats` | GET | Facilitator statistics |\n\n---\n\n## Development\n\n### Running Locally\n\n```bash\ngit clone https://github.com/b0ase/path402\ncd path402\nnpm install\nnpm run dev\n```\n\n### Testing\n\n```bash\nnpm test\nnpm run test:integration\n```\n\n### Building\n\n```bash\nnpm run build\n```\n\n---\n\n## Roadmap\n\n### v1.0.0 (Current)\n\n- ✅ 10 core tools\n- ✅ ascending bonding curve pricing\n- ✅ Budget management\n- ✅ Simulated acquisition/serving\n\n### v1.1.0 (In Progress)\n\n- 🔲 Live HTTP client for path402.com\n- 🔲 x402 facilitator tools (verify, settle, inscription)\n- 🔲 Real payment integration\n\n### v1.2.0 (Planned)\n\n- 🔲 Transfer and history tools\n- 🔲 Multi-agent coordination\n- 🔲 Persistent storage\n\n### v1.3.0 (Planned)\n\n- 🔲 Creator tools (register)\n- 🔲 Advanced analytics\n- 🔲 Agent marketplace integration\n\n---\n\n## Contributing\n\nContributions welcome! Please read our Contributing Guide.\n\n```bash\n# Fork the repo\ngit checkout -b feature/your-feature\n# Make changes\nnpm test\ngit commit -m \"Add your feature\"\ngit push origin feature/your-feature\n# Open a PR\n```\n\n---\n\n## License\n\n[Open BSV License version 4](LICENSE)\n\n---\n\n## Links\n\n- **Website**: [path402.com](https://path402.com)\n- **Whitepaper**: [path402.com/whitepaper](https://path402.com/whitepaper)\n- **Exchange**: [path402.com/exchange](https://path402.com/exchange)\n- **Documentation**: [path402.com/docs](https://path402.com/docs)\n- **GitHub**: [github.com/b0ase/path402](https://github.com/b0ase/path402)\n\n---\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/b0ase/path402/issues)\n- **Email**: hello@b0ase.com\n- **Twitter**: @b0ase\n",
  "bytes": 13150,
  "sha": "906b8c808ab8bad73035529cdfb341465afd5539c3a48e23d96b54608d22be62",
  "repo_slug": "b0ase/path402",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_b0ase_path402_0b5192b7/readme"
}