# x402-mcp-payment

This is an example project combining MCP (Model Context Protocol) and the x402 payment protocol. It demonstrates how to enable LLMs (such as ChatGPT, Claude) to access paid resources via the MCP protocol. After a user completes payment in the chat using a universal crypto wallet (supporting x402), the LLM can automatically retrieve and process the paid content.

Core Functionality: Empowering AI Agents with the ability to "pay for information".

## User Interaction Flow

1.  **Service Request**: The user requests a paid service in ChatGPT (e.g., "Give me a riddle").
2.  **Order Generation**: The MCP Server generates a dynamic x402 payment link containing a unique `payid` and returns it to the user.
3.  **User Payment**: The user clicks the link and pays the specified amount using a universal crypto wallet.
4.  **Status Recording**: The x402 Server confirms the payment success and records the `payid` as "paid".
5.  **Service Delivery**: The user continues the conversation in ChatGPT (e.g., "I have paid"), and the AI automatically verifies the payment status and retrieves the service content.

### Interaction Diagram

```mermaid
sequenceDiagram
    participant User as User
    participant AI as ChatGPT (LLM)
    participant MCP as MCP Server
    participant x402 as x402 Payment Server
    participant Wallet as Crypto Wallet

    User->>AI: Request paid service
    AI->>MCP: Call get_riddle
    MCP->>MCP: Generate payid
    MCP-->>AI: Return payment link (with payid)
    AI-->>User: Show payment link
    User->>x402: Click link to payment page
    x402->>Wallet: Initiate payment request
    Wallet->>x402: Confirm payment
    x402->>x402: Record payid as [Paid]
    x402-->>User: Show payment success
    User->>AI: I have finished payment
    AI->>MCP: Call get_answer (payid)
    MCP->>x402: Verify payid status
    x402-->>MCP: Verification passed (and clear status)
    MCP-->>AI: Return paid content (answer)
    AI-->>User: Provide service/answer
```

## Prerequisites

*   Node.js (v18+)
*   Coinbase Developer Platform (CDP) API Key (for x402 payment verification)

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment Variables

Create a `.env` file in the project root directory and fill in your Coinbase API keys:

```env
CDP_API_KEY_ID="your_cdp_key_id"
CDP_API_KEY_SECRET="your_cdp_key_secret"
```

### 3. Configuration File (Optional)

Modify `config.yaml` to customize server ports, payment address, price, and riddle content.

```yaml
# x402 Payment Address (Your EVM wallet address)
payToAddress: "0x..."

# Payment Configuration
payment:
  price: "$0.01" # Price
  network: "base" # Network (base, polygon, ethereum, etc.)
```

### 4. Start Service

This project requires running **two separate processes**:

1. **MCP Server** - Deployed at `mcp.mydomain.com` (port 3000)
2. **x402 Payment Server** - Deployed at `x402.mydomain.com` (port 3001)

Development Mode (Supports hot reload):

```bash
# Terminal 1: Start MCP Server
npm run dev:mcp

# Terminal 2: Start x402 Payment Server
npm run dev:x402
```

Production Mode:

```bash
npm run build
npm run start:mcp
npm run start:x402
```

### 5. Configure ChatGPT

To use this service in ChatGPT:

1. Open **ChatGPT** (web or app)
2. Go to **Settings** → **App & Connectors** (or similar MCP configuration section)
3. Add a new MCP server: `https://mcp.mydomain.com`
4. Now you can interact with paid riddles directly in ChatGPT!

> **Note**: Currently requires a ChatGPT Pro, Plus, Team, or Education account to access MCP integration features.