# X402 Client 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 exit with code 0 for success, 1 for failure
4. Must output JSON result as the last line of stdout

## Protocol Family Support
Clients must declare which protocol families they support 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
Clients must declare which x402 protocol versions they support using the `x402Versions` field:
- **x402Versions**: Array of supported x402 protocol versions (e.g., [1, 2])

## EVM asset transfer method support
Clients that support the EVM protocol family must declare which **asset authorization** paths they implement using **`evm.assetTransferMethods`**:
- **eip3009**: EIP-3009 `transferWithAuthorization`
- **permit2**: Uniswap Permit2

Payment **schemes** (exact / upto / batch-settlement) are chosen per server endpoint; the client is matched only on **`assetTransferMethod`**.

If the `evm` field is omitted, the client is assumed to only support `["eip3009"]`.
The test suite uses this to skip scenarios where a server endpoint requires an asset transfer method the client does not support.

Example configuration:
```json
{
  "name": "my-client",
  "type": "client",
  "language": "typescript",
  "protocolFamilies": ["evm"],
  "x402Versions": [1, 2],
  "evm": {
    "assetTransferMethods": ["eip3009", "permit2"]
  },
  "environment": {
    "required": ["EVM_PRIVATE_KEY", "RESOURCE_SERVER_URL", "ENDPOINT_PATH"],
    "optional": []
  }
}
```

Multi-protocol client example:
```json
{
  "name": "universal-client",
  "type": "client", 
  "language": "typescript",
  "protocolFamilies": ["evm", "svm"],
  "x402Versions": [1, 2],
  "evm": {
    "assetTransferMethods": ["eip3009", "permit2"]
  },
  "environment": {
    "required": ["EVM_PRIVATE_KEY", "SVM_PRIVATE_KEY", "RESOURCE_SERVER_URL", "ENDPOINT_PATH"],
    "optional": []
  }
}
```

Python client example (eip3009 only):
```json
{
  "name": "my-python-client",
  "type": "client",
  "language": "python",
  "protocolFamilies": ["evm"],
  "x402Versions": [1, 2],
  "evm": {
    "assetTransferMethods": ["eip3009"]
  },
  "environment": {
    "required": ["EVM_PRIVATE_KEY", "RESOURCE_SERVER_URL", "ENDPOINT_PATH"],
    "optional": []
  }
}
```

## Environment Variables / CLI Arguments
The following parameters must be configurable:
- `EVM_PRIVATE_KEY`: Private key for signing requests (EVM networks)
- `SVM_PRIVATE_KEY`: Private key for signing requests (Solana networks)
- `RESOURCE_SERVER_URL`: URL of the server to call
- `ENDPOINT_PATH`: Path to the protected endpoint (default: "/protected")

## Expected Behavior

### Success Case
- Make HTTP request to the protected endpoint
- Handle payment automatically (via x402 middleware)
- **Exit Code**: 0
- **Output**: JSON result as last line of stdout
  ```json
  {
    "success": true,
    "data": {
      "message": "Protected endpoint accessed successfully",
      "timestamp": "2024-01-01T00:00:00Z"
    },
    "status_code": 200,
    "payment_response": {
      "transaction": "0x...",
      "status": "settled"
    }
  }
  ```

### Failure Cases
- **Payment Failure (402)**: Exit code 1, error message
- **Network Error**: Exit code 1, error message
- **Invalid Configuration**: Exit code 1, error message

### Output Format
- **Success**: Must log "Client test completed successfully" before JSON output
- **Failure**: Must log error details before JSON output
- **JSON**: Must be the last line of stdout for parsing by proxy

## Startup Requirements
- Must validate required environment variables on startup
- Must handle graceful error reporting
- Must output structured JSON result for proxy parsing
- Must handle SIGTERM/SIGINT gracefully 