mcpaid(1) — Comprehensive Documentation

import { McpaidServer } from '@mcpaid/sdk';
import express from 'express';

const app = express();
app.use(express.json());

// Initialize MCPaid Server Engine
const mcpaid = new McpaidServer({
  serverId: 'custom-analytics-mcp',
  payoutWallet: '0xYourBaseL2WalletAddress',
  network: 'base',
  tools: {
    'fast_ping': { type: 'free' },
    'deep_audit': { priceUsd: '0.05' }
  }
});

// Intercept MCP JSON-RPC Endpoint
app.post('/mcp', async (req, res) => {
  const result = await mcpaid.handleRequest(req.body, {
    headers: req.headers
  });
  res.status(result.statusCode).json(result.body);
});

app.listen(3000, () => console.log('Server listening on port 3000'));

HTTP/1.1 402 Payment Required
Content-Type: application/json
X-ToolPay-Status: 402_CHALLENGE_ISSUED
X-Payment-Amount: 0.0100
X-Payment-Currency: USDC
X-Payment-Network: base
X-Payment-Nonce: nonce_8a12f6...

{
  "jsonrpc": "2.0",
  "id": 100,
  "error": {
    "code": 402,
    "message": "Payment Required: Tool "analyze_sentiment" costs 0.0100 USDC on Base.",
    "data": {
      "priceUsd": "0.0100",
      "currency": "USDC",
      "network": "base",
      "challengeNonce": "nonce_8a12f6...",
      "developerCut": "$0.0097 (97%)",
      "instructions": {
        "summary": "Tool is monetized. Set AGENT_PRIVATE_KEY to authorize gasless payments.",
        "steps": [
          "Fund agent EVM address with USDC on Base.",
          "Run via npx @mcpaid/sdk bridge or pass private key in harness."
        ]
      }
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "MCPaidConfig",
  "type": "object",
  "required": ["serverId", "payoutWallet", "tools"],
  "properties": {
    "serverId": {
      "type": "string",
      "description": "Unique URL-safe identifier for your MCP server (e.g. 'stock-intel')"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for dashboard and discovery listings"
    },
    "upstreamUrl": {
      "type": "string",
      "format": "uri",
      "description": "Internal HTTP or SSE URL where your raw MCP server is listening"
    },
    "payoutWallet": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{40}$",
      "description": "Base EVM address receiving 97% USDC payouts (e.g. 0xYourWallet)"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["toolName", "type"],
        "properties": {
          "toolName": { "type": "string" },
          "type": { "type": "string", "enum": ["free", "paid"] },
          "priceUsd": { "type": "string", "pattern": "^[0-9]+(\.[0-9]{1,4})?$" },
          "description": { "type": "string" }
        }
      }
    },
    "platformFee": {
      "type": "object",
      "properties": {
        "platformFeeBasisPoints": { "type": "number", "default": 300 },
        "platformTreasuryWallet": { "type": "string" }
      }
    }
  }
}

{
  "status": 402,
  "headers": {
    "X-ToolPay-Status": "402_CHALLENGE_ISSUED",
    "X-Payment-Amount": "0.0100",
    "X-Payment-Currency": "USDC",
    "X-Payment-Network": "base",
    "X-Payment-Nonce": "0x7f19b2c8..."
  },
  "body": {
    "jsonrpc": "2.0",
    "id": 100,
    "error": {
      "code": 402,
      "message": "Payment Required: Tool "analyze_sentiment" costs 0.0100 USDC on Base.",
      "data": {
        "priceUsd": "0.0100",
        "currency": "USDC",
        "network": "base",
        "chainId": 8453,
        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "challengeNonce": "0x7f19b2c8...",
        "developerCut": "$0.0097 (97%)",
        "instructions": {
          "summary": "Tool is monetized. Sign EIP-712 permit voucher with agent key.",
          "steps": [
            "Sign permit off-chain for amount 0.0100 USDC and nonce 0x7f19b2c8...",
            "Attach voucher in Authorization: Bearer <voucher> or X-Payment-Proof header",
            "Re-issue tools/call POST request"
          ]
        }
      }
    }
  }
}

// Request: the txHash must be a CONFIRMED on-chain USDC transfer
// to the treasury (0x49E9…bad on Base) from agentWallet, ≥ $1.00.
// Permit signatures are rejected here — only funded transfers credit.
POST https://mcpaid.dev/v1/sessions/deposit
{
  "agentWallet": "0xAgent...",
  "amountMicro": "2000000",
  "txHash": "0xDepositTx...",
  "sessionId": "sess_... (optional: top up instead of opening)",
  "ttlSeconds": 86400
}
// → 200 { success, sessionId, agentWallet, balanceMicro,
//         totalDepositedMicro, totalSpentMicro, expiresAt }
// → 400 below-minimum / already-claimed / permit-scheme
// → 402 transfer verification failed (wrong recipient, token, or amount)
// Policy env: MIN_SESSION_DEPOSIT_MICRO (default 1000000 = $1.00)

// Auth: developer session cookie. Gross is locked from your balance;
// the ticket settles the NET (gross − ~$0.02 network fee) on Base L2.
POST https://mcpaid.dev/v1/developer/withdraw
{ "developerWallet": "0xPayout...", "amountMicro": 5000000 }  // amount optional = full balance
// → 200 { success, withdrawal: { id, amountMicro (net), gasFeeMicro,
//         status: 'processing', ... },
//         message: "… You receive $X net after a $Y network fee …" }
// → 400 balance or request below the $1.00 minimum
// Ticket lifecycle: processing → settling (relayer lease) → completed (+txHash)
//                   or failed. The 1-minute cron only settles tickets you create.
// Policy env: MIN_WITHDRAWAL_MICRO (default 1000000 = $1.00),
//             WITHDRAWAL_GAS_FEE_MICRO (default 20000 = ~$0.02)