# X402 Server Protocol

## CLI Interface
1. Must be runnable through a CLI command, which can be parsed from 'run.sh'
2. Must output specific logs
3. Must error code 0 or 1, with a JSON response payload

## Protocol Family Support
Servers must declare which protocol family each payment endpoint requires in their test.config.json:
- **EVM**: Ethereum Virtual Machine compatible networks (Base, Ethereum, etc.)
- **SVM**: Solana Virtual Machine compatible networks (Solana, etc.)

## X402 Version Support
Servers must declare which x402 protocol version they implement using the `x402Version` field:
- **x402Version**: The x402 protocol version implemented by the server (e.g., 1 or 2)

## Extensions Support
Servers may declare which protocol extensions they support using the `extensions` field:
- **extensions**: Array of supported extension names (e.g., ["bazaar"])

## Coldstart Tests
Some endpoints require special pre-test state setup before they can be exercised (e.g., revoking a Permit2 approval so that the gas-sponsoring extension path is triggered). This setup is expensive: it involves funding the client wallet, submitting on-chain transactions, and draining ETH back.

Endpoints that require this setup set **`"coldstart": true`** inside **`schemeOptions`** on that endpoint. The test runner treats the **first** test for a given endpoint path within a combo as the "coldstart" test — it performs the full setup. Subsequent tests for the same endpoint path within the same combo skip the setup and run directly, exercising the "warm" (already-approved) code path.

All explicit gas sponsorship extension endpoints (EIP-2612 and ERC-20 approval) should have **`coldstart`** enabled under **`schemeOptions`**, as they must succeed without the user having gas or approval ahead of time.

## EVM scheme and asset transfer method
For EVM paid endpoints, servers must declare:
- **`scheme`**: Payment scheme — **`exact`** (single settle), **`upto`** (usage-based settle), or **`batch-settlement`** (deposit + vouchers + refund). If omitted, the harness defaults to **`exact`**.
- **`assetTransferMethod`**: **`eip3009`** vs **`permit2`**. If omitted: **`upto`** endpoints default to **`permit2`** (no EIP-3009 path); **`exact`** and **`batch-settlement`** default to **`eip3009`**.
- **`schemeOptions`** (optional): Harness knobs as **`SchemeOptions`** — **`Permit2SchemeOptions`** (`permit2Direct`, `coldstart`) for exact/upto and the same optional Permit2 knobs for batch-settlement.
- **`BATCH_SETTLEMENT_RECOVERY`** (optional env): Defaults to enabled. Set to `false`, `0`, `no`, or `off` to run batch-settlement as deposit + voucher + refund without a fresh client process recovery step.

These fields apply only when `"protocolFamily": "evm"`. Discovery matches **`assetTransferMethod`** against each client/facilitator’s `evm.assetTransferMethods`; **`scheme`** is used for filters such as `--schemes=`.

Example configuration:
```json
{
  "name": "my-server",
  "type": "server",
  "language": "typescript",
  "x402Version": 2,
  "extensions": ["bazaar"],
  "endpoints": [
    {
      "path": "/protected",
      "method": "GET",
      "description": "Protected endpoint requiring EIP-3009 payment",
      "requiresPayment": true,
      "protocolFamily": "evm",
      "scheme": "exact",
      "assetTransferMethod": "eip3009"
    },
    {
      "path": "/protected-permit2",
      "method": "GET",
      "description": "Protected endpoint requiring Permit2 payment",
      "requiresPayment": true,
      "protocolFamily": "evm",
      "scheme": "exact",
      "assetTransferMethod": "permit2",
      "schemeOptions": {
        "permit2Direct": true
      }
    },
    {
      "path": "/health",
      "method": "GET",
      "description": "Health check endpoint",
      "health": true
    }
  ]
}
```

Multi-protocol server example:
```json
{
  "name": "universal-server",
  "type": "server",
  "language": "typescript",
  "x402Version": 2, 
  "endpoints": [
    {
      "path": "/evm-protected",
      "method": "GET",
      "description": "Protected endpoint requiring EVM payment",
      "requiresPayment": true,
      "protocolFamily": "evm",
      "scheme": "exact",
      "assetTransferMethod": "eip3009"
    },
    {
      "path": "/svm-protected", 
      "method": "GET",
      "description": "Protected endpoint requiring SVM payment",
      "requiresPayment": true,
      "protocolFamily": "svm"
    }
  ]
}
```

## Environment Variables / CLI Arguments
The following parameters must be configurable:
- `USE_CDP_FACILITATOR`: Flag to switch facilitators from default
- `NETWORK`: Network to use (e.g., "base-sepolia", "base")
- `ADDRESS`: Address to receive payments
- `PORT`: Port to listen on (default: 4021)

## Required Endpoints

### GET /protected
- **Purpose**: Protected endpoint that requires payment
- **Price**: $0.001
- **Success Response (200)**:
  ```json
  {
    "message": "Protected endpoint accessed successfully",
    "timestamp": "2024-01-01T00:00:00Z"
  }
  ```
- **Payment Failure Response (402)**:
  ```json
  {
    "error": "Payment required",
    "message": "Failed to process payment"
  }
  ```

### POST /close
- **Purpose**: Gracefully shut down the server
- **Response**: Should terminate the process with exit code 0
- **Usage**: Called by proxy to clean up resources

### GET /health (Optional)
- **Purpose**: Health check endpoint
- **Response (200)**:
  ```json
  {
    "status": "ok"
  }
  ```

## Startup Requirements
- Must log "Server listening" when ready to accept requests
- Must handle graceful shutdown on SIGTERM/SIGINT
- Must validate required environment variables on startup
