diff --git a/admin/class-baskerville-admin.php b/admin/class-baskerville-admin.php
index a5d3db7..b53a93f 100644
--- a/admin/class-baskerville-admin.php
+++ b/admin/class-baskerville-admin.php
@@ -285,6 +285,15 @@ public function add_admin_menu() {
 			array($this, 'admin_page_turnstile')
 		);
 
+		add_submenu_page(
+			'baskerville-settings',
+			esc_html__('Pay-Per-Crawl', 'baskerville-ai-security'),
+			esc_html__('Pay-Per-Crawl', 'baskerville-ai-security'),
+			'manage_options',
+			'baskerville-pay-per-crawl',
+			array($this, 'admin_page_pay_per_crawl')
+		);
+
 		add_submenu_page(
 			'baskerville-settings',
 			esc_html__('Analytics', 'baskerville-ai-security'),
@@ -335,6 +344,11 @@ public function admin_page_turnstile() {
 		$this->admin_page();
 	}
 
+	public function admin_page_pay_per_crawl() {
+		$_GET['tab'] = 'pay-per-crawl';
+		$this->admin_page();
+	}
+
 	public function admin_page_analytics() {
 		$_GET['tab'] = 'analytics';
 		$this->admin_page();
@@ -769,6 +783,120 @@ public function sanitize_settings($input) {
 			$sanitized['turnstile_borderline_max'] = isset($existing['turnstile_borderline_max']) ? $existing['turnstile_borderline_max'] : 70;
 		}
 
+		// Pay-per-crawl settings
+		$is_pay_tab = isset($input['pay_per_crawl_tab']);
+		$sanitized['pay_enabled'] = isset($input['pay_enabled'])
+			? (bool) $input['pay_enabled']
+			: ($is_pay_tab ? false : (isset($existing['pay_enabled']) ? $existing['pay_enabled'] : false));
+
+		if (isset($input['pay_mode'])) {
+			$mode = sanitize_text_field($input['pay_mode']);
+			$sanitized['pay_mode'] = in_array($mode, ['off', 'test', 'observe', 'enforce'], true) ? $mode : 'off';
+		} elseif (isset($existing['pay_mode'])) {
+			$sanitized['pay_mode'] = $existing['pay_mode'];
+		}
+
+		if (isset($input['pay_ai_threshold'])) {
+			$sanitized['pay_ai_threshold'] = max(0, min(100, (int) $input['pay_ai_threshold']));
+		} elseif (isset($existing['pay_ai_threshold'])) {
+			$sanitized['pay_ai_threshold'] = $existing['pay_ai_threshold'];
+		}
+
+		if (isset($input['pay_protected_paths'])) {
+			$sanitized['pay_protected_paths'] = sanitize_textarea_field($input['pay_protected_paths']);
+		} elseif (isset($existing['pay_protected_paths'])) {
+			$sanitized['pay_protected_paths'] = $existing['pay_protected_paths'];
+		}
+
+		if (isset($input['pay_wallet_address'])) {
+			$wallet = sanitize_text_field($input['pay_wallet_address']);
+			// Basic 0x address validation
+			if ($wallet && !preg_match('/^0x[0-9a-fA-F]{40}$/', $wallet)) {
+				$wallet = '';
+			}
+			$sanitized['pay_wallet_address'] = $wallet;
+		} elseif (isset($existing['pay_wallet_address'])) {
+			$sanitized['pay_wallet_address'] = $existing['pay_wallet_address'];
+		}
+
+		if (isset($input['pay_price'])) {
+			$price = sanitize_text_field($input['pay_price']);
+			if (!is_numeric($price) || (float) $price < 0) {
+				$price = '0.10';
+			}
+			$sanitized['pay_price'] = $price;
+		} elseif (isset($existing['pay_price'])) {
+			$sanitized['pay_price'] = $existing['pay_price'];
+		}
+
+		if (isset($input['pay_currency'])) {
+			$sanitized['pay_currency'] = sanitize_text_field($input['pay_currency']);
+		} elseif (isset($existing['pay_currency'])) {
+			$sanitized['pay_currency'] = $existing['pay_currency'];
+		}
+
+		if (isset($input['pay_network'])) {
+			$sanitized['pay_network'] = sanitize_text_field($input['pay_network']);
+		} elseif (isset($existing['pay_network'])) {
+			$sanitized['pay_network'] = $existing['pay_network'];
+		}
+
+		if (isset($input['pay_asset_type'])) {
+			$type = sanitize_text_field($input['pay_asset_type']);
+			$sanitized['pay_asset_type'] = in_array($type, ['native', 'erc20'], true) ? $type : 'erc20';
+		} elseif (isset($existing['pay_asset_type'])) {
+			$sanitized['pay_asset_type'] = $existing['pay_asset_type'];
+		}
+
+		if (isset($input['pay_token_contract'])) {
+			$sanitized['pay_token_contract'] = sanitize_text_field($input['pay_token_contract']);
+		} elseif (isset($existing['pay_token_contract'])) {
+			$sanitized['pay_token_contract'] = $existing['pay_token_contract'];
+		}
+
+		if (isset($input['pay_token_decimals'])) {
+			$sanitized['pay_token_decimals'] = max(0, min(18, (int) $input['pay_token_decimals']));
+		} elseif (isset($existing['pay_token_decimals'])) {
+			$sanitized['pay_token_decimals'] = $existing['pay_token_decimals'];
+		}
+
+		if (isset($input['pay_verifier_type'])) {
+			$vtype = sanitize_text_field($input['pay_verifier_type']);
+			$sanitized['pay_verifier_type'] = in_array($vtype, ['stub', 'polling'], true) ? $vtype : 'stub';
+		} elseif (isset($existing['pay_verifier_type'])) {
+			$sanitized['pay_verifier_type'] = $existing['pay_verifier_type'];
+		}
+
+		if (isset($input['pay_provider'])) {
+			$sanitized['pay_provider'] = sanitize_text_field($input['pay_provider']);
+		} elseif (isset($existing['pay_provider'])) {
+			$sanitized['pay_provider'] = $existing['pay_provider'];
+		}
+
+		if (isset($input['pay_api_key'])) {
+			$sanitized['pay_api_key'] = sanitize_text_field($input['pay_api_key']);
+		} elseif (isset($existing['pay_api_key'])) {
+			$sanitized['pay_api_key'] = $existing['pay_api_key'];
+		}
+
+		if (isset($input['pay_min_confirmations'])) {
+			$sanitized['pay_min_confirmations'] = max(1, min(100, (int) $input['pay_min_confirmations']));
+		} elseif (isset($existing['pay_min_confirmations'])) {
+			$sanitized['pay_min_confirmations'] = $existing['pay_min_confirmations'];
+		}
+
+		if (isset($input['pay_challenge_ttl'])) {
+			$sanitized['pay_challenge_ttl'] = max(300, min(86400, (int) $input['pay_challenge_ttl']));
+		} elseif (isset($existing['pay_challenge_ttl'])) {
+			$sanitized['pay_challenge_ttl'] = $existing['pay_challenge_ttl'];
+		}
+
+		if (isset($input['pay_grant_ttl'])) {
+			$sanitized['pay_grant_ttl'] = max(60, min(86400, (int) $input['pay_grant_ttl']));
+		} elseif (isset($existing['pay_grant_ttl'])) {
+			$sanitized['pay_grant_ttl'] = $existing['pay_grant_ttl'];
+		}
+
 		// Flush rewrite rules when settings are saved (for honeypot route)
 		flush_rewrite_rules();
 
@@ -3133,6 +3261,7 @@ public function admin_page() {
 			$burst_protection_enabled = isset($options['burst_protection_enabled']) ? $options['burst_protection_enabled'] : true;
 			$api_rate_limit_enabled = isset($options['api_rate_limit_enabled']) ? $options['api_rate_limit_enabled'] : true;
 			$turnstile_enabled = isset($options['turnstile_enabled']) ? $options['turnstile_enabled'] : false;
+			$pay_enabled = !empty($options['pay_enabled']);
 			?>
 			<h2 class="nav-tab-wrapper">
 				<a href="<?php echo esc_url(admin_url('admin.php?page=baskerville-settings')); ?>"
@@ -3163,6 +3292,10 @@ class="nav-tab <?php echo $api_rate_limit_enabled ? 'tab-enabled' : ''; ?> <?php
 				   class="nav-tab <?php echo $turnstile_enabled ? 'tab-enabled' : ''; ?> <?php echo $current_tab === 'turnstile' ? 'nav-tab-active' : ''; ?>">
 					<?php esc_html_e('Turnstile', 'baskerville-ai-security'); ?>
 				</a>
+				<a href="<?php echo esc_url(admin_url('admin.php?page=baskerville-pay-per-crawl')); ?>"
+				   class="nav-tab <?php echo $pay_enabled ? 'tab-enabled' : ''; ?> <?php echo $current_tab === 'pay-per-crawl' ? 'nav-tab-active' : ''; ?>">
+					<?php esc_html_e('Pay-Per-Crawl', 'baskerville-ai-security'); ?>
+				</a>
 				<a href="<?php echo esc_url(admin_url('admin.php?page=baskerville-analytics')); ?>"
 				   class="nav-tab <?php echo $current_tab === 'analytics' ? 'nav-tab-active' : ''; ?>">
 					<?php esc_html_e('Analytics', 'baskerville-ai-security'); ?>
@@ -3571,6 +3704,16 @@ class="small-text" />
 						<?php
 						break;
 
+					case 'pay-per-crawl':
+						?>
+						</form>
+						<?php
+						$this->render_pay_per_crawl_tab();
+						?>
+						<form method="post" action="options.php">
+						<?php
+						break;
+
 					case 'analytics':
 						?>
 						</form>
@@ -4906,6 +5049,212 @@ public function render_honeypot_ban_field() {
 		<?php
 	}
 
+	private function render_pay_per_crawl_tab(): void {
+		$options = get_option('baskerville_settings', []);
+		$pay_enabled       = !empty($options['pay_enabled']);
+		$pay_mode          = $options['pay_mode'] ?? 'off';
+		$pay_ai_threshold  = (int) ($options['pay_ai_threshold'] ?? 70);
+		$pay_paths         = $options['pay_protected_paths'] ?? '/*';
+		$pay_wallet        = $options['pay_wallet_address'] ?? '';
+		$pay_price         = $options['pay_price'] ?? '0.10';
+		$pay_currency      = $options['pay_currency'] ?? 'USDC';
+		$pay_network       = $options['pay_network'] ?? 'polygon';
+		$pay_asset_type    = $options['pay_asset_type'] ?? 'erc20';
+		$pay_token_contract = $options['pay_token_contract'] ?? '';
+		$pay_token_decimals = (int) ($options['pay_token_decimals'] ?? 6);
+		$pay_verifier_type = $options['pay_verifier_type'] ?? 'stub';
+		$pay_provider      = $options['pay_provider'] ?? '';
+		$pay_api_key       = $options['pay_api_key'] ?? '';
+		$pay_min_conf      = (int) ($options['pay_min_confirmations'] ?? 5);
+		$pay_challenge_ttl = (int) ($options['pay_challenge_ttl'] ?? 3600);
+		$pay_grant_ttl     = (int) ($options['pay_grant_ttl'] ?? 900);
+		$master_enabled    = !isset($options['master_protection_enabled']) || $options['master_protection_enabled'];
+		?>
+		<form method="post" action="options.php">
+		<?php settings_fields('baskerville_settings_group'); ?>
+		<input type="hidden" name="baskerville_settings[master_protection_enabled]" value="<?php echo $master_enabled ? '1' : '0'; ?>">
+		<input type="hidden" name="baskerville_settings[pay_per_crawl_tab]" value="1">
+
+		<table class="form-table" role="presentation">
+			<tr>
+				<td colspan="2">
+					<div class="baskerville-toggle-label">
+						<span class="baskerville-toggle-text">
+							<?php esc_html_e('Pay-Per-Crawl', 'baskerville-ai-security'); ?>
+						</span>
+						<input type="hidden" name="baskerville_settings[pay_enabled]" value="0">
+						<label class="baskerville-toggle-switch">
+							<input type="checkbox" name="baskerville_settings[pay_enabled]" value="1" <?php checked($pay_enabled, true); ?> />
+							<span class="baskerville-toggle-slider-regular"></span>
+						</label>
+						<span class="baskerville-toggle-text">
+							<?php echo $pay_enabled ? esc_html__('ON', 'baskerville-ai-security') : esc_html__('OFF', 'baskerville-ai-security'); ?>
+						</span>
+					</div>
+				</td>
+			</tr>
+		</table>
+
+		<h3><?php esc_html_e('Policy', 'baskerville-ai-security'); ?></h3>
+		<table class="form-table" role="presentation">
+			<tr>
+				<th scope="row"><?php esc_html_e('Mode', 'baskerville-ai-security'); ?></th>
+				<td>
+					<fieldset>
+						<label class="baskerville-label-block">
+							<input type="radio" name="baskerville_settings[pay_mode]" value="off" <?php checked($pay_mode, 'off'); ?>>
+							<?php esc_html_e('Off', 'baskerville-ai-security'); ?>
+						</label>
+						<label class="baskerville-label-block">
+							<input type="radio" name="baskerville_settings[pay_mode]" value="test" <?php checked($pay_mode, 'test'); ?>>
+							<?php esc_html_e('Test (/eq402 only, no production impact)', 'baskerville-ai-security'); ?>
+						</label>
+						<label class="baskerville-label-block">
+							<input type="radio" name="baskerville_settings[pay_mode]" value="observe" <?php checked($pay_mode, 'observe'); ?>>
+							<?php esc_html_e('Observe (log only, add header)', 'baskerville-ai-security'); ?>
+						</label>
+						<label class="baskerville-label-block">
+							<input type="radio" name="baskerville_settings[pay_mode]" value="enforce" <?php checked($pay_mode, 'enforce'); ?>>
+							<?php esc_html_e('Enforce (return 402)', 'baskerville-ai-security'); ?>
+						</label>
+					</fieldset>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('AI Score Threshold', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="number" name="baskerville_settings[pay_ai_threshold]" value="<?php echo esc_attr($pay_ai_threshold); ?>" min="0" max="100" class="baskerville-input-md">
+					<p class="description"><?php esc_html_e('Requests with ai_score >= this value will require payment (0-100).', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Protected Paths', 'baskerville-ai-security'); ?></th>
+				<td>
+					<textarea name="baskerville_settings[pay_protected_paths]" rows="4" cols="50" class="large-text code"><?php echo esc_textarea($pay_paths); ?></textarea>
+					<p class="description"><?php esc_html_e('One glob pattern per line (e.g. /* or /articles/*). fnmatch() syntax.', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+		</table>
+
+		<h3><?php esc_html_e('Payment', 'baskerville-ai-security'); ?></h3>
+		<table class="form-table" role="presentation">
+			<tr>
+				<th scope="row"><?php esc_html_e('Wallet Address', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="text" name="baskerville_settings[pay_wallet_address]" value="<?php echo esc_attr($pay_wallet); ?>" class="regular-text code" placeholder="0x...">
+					<p class="description"><?php esc_html_e('Publisher wallet that receives payments (0x-prefixed, 40 hex chars).', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Price', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="text" name="baskerville_settings[pay_price]" value="<?php echo esc_attr($pay_price); ?>" class="baskerville-input-md" placeholder="0.10">
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Currency', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="text" name="baskerville_settings[pay_currency]" value="<?php echo esc_attr($pay_currency); ?>" class="baskerville-input-md" placeholder="USDC">
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Network', 'baskerville-ai-security'); ?></th>
+				<td>
+					<select name="baskerville_settings[pay_network]">
+						<option value="polygon" <?php selected($pay_network, 'polygon'); ?>>Polygon</option>
+						<option value="polygon-amoy" <?php selected($pay_network, 'polygon-amoy'); ?>>Polygon Amoy (Testnet)</option>
+						<option value="ethereum" <?php selected($pay_network, 'ethereum'); ?>>Ethereum</option>
+					</select>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Asset Type', 'baskerville-ai-security'); ?></th>
+				<td>
+					<select name="baskerville_settings[pay_asset_type]">
+						<option value="erc20" <?php selected($pay_asset_type, 'erc20'); ?>>ERC-20 Token</option>
+						<option value="native" <?php selected($pay_asset_type, 'native'); ?>>Native (MATIC/ETH)</option>
+					</select>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Token Contract', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="text" name="baskerville_settings[pay_token_contract]" value="<?php echo esc_attr($pay_token_contract); ?>" class="regular-text code" placeholder="0x...">
+					<p class="description"><?php esc_html_e('ERC-20 token contract address (only for erc20 asset type).', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Token Decimals', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="number" name="baskerville_settings[pay_token_decimals]" value="<?php echo esc_attr($pay_token_decimals); ?>" min="0" max="18" class="baskerville-input-md">
+					<p class="description"><?php esc_html_e('Token decimal places (e.g. 6 for USDC, 18 for most ERC-20).', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+		</table>
+
+		<h3><?php esc_html_e('Verifier', 'baskerville-ai-security'); ?></h3>
+		<table class="form-table" role="presentation">
+			<tr>
+				<th scope="row"><?php esc_html_e('Verifier Type', 'baskerville-ai-security'); ?></th>
+				<td>
+					<select name="baskerville_settings[pay_verifier_type]">
+						<option value="stub" <?php selected($pay_verifier_type, 'stub'); ?>><?php esc_html_e('Stub (demo, accepts demo_ tx hashes)', 'baskerville-ai-security'); ?></option>
+						<option value="polling" <?php selected($pay_verifier_type, 'polling'); ?>><?php esc_html_e('Polling (real RPC verification)', 'baskerville-ai-security'); ?></option>
+					</select>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('RPC Provider', 'baskerville-ai-security'); ?></th>
+				<td>
+					<select name="baskerville_settings[pay_provider]">
+						<option value="" <?php selected($pay_provider, ''); ?>><?php esc_html_e('Default (public RPC)', 'baskerville-ai-security'); ?></option>
+						<option value="alchemy" <?php selected($pay_provider, 'alchemy'); ?>>Alchemy</option>
+						<option value="infura" <?php selected($pay_provider, 'infura'); ?>>Infura</option>
+						<option value="ankr" <?php selected($pay_provider, 'ankr'); ?>>Ankr</option>
+					</select>
+					<p class="description"><?php esc_html_e('Only used when verifier type is "polling".', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('API Key', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="text" name="baskerville_settings[pay_api_key]" value="<?php echo esc_attr($pay_api_key); ?>" class="regular-text code">
+					<p class="description"><?php esc_html_e('API key for the selected RPC provider (optional for public RPCs).', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Min Confirmations', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="number" name="baskerville_settings[pay_min_confirmations]" value="<?php echo esc_attr($pay_min_conf); ?>" min="1" max="100" class="baskerville-input-md">
+				</td>
+			</tr>
+		</table>
+
+		<h3><?php esc_html_e('Timing', 'baskerville-ai-security'); ?></h3>
+		<table class="form-table" role="presentation">
+			<tr>
+				<th scope="row"><?php esc_html_e('Challenge TTL', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="number" name="baskerville_settings[pay_challenge_ttl]" value="<?php echo esc_attr($pay_challenge_ttl); ?>" min="300" max="86400" class="baskerville-input-md">
+					<span><?php esc_html_e('seconds', 'baskerville-ai-security'); ?></span>
+					<p class="description"><?php esc_html_e('How long a payment challenge remains valid (300-86400).', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+			<tr>
+				<th scope="row"><?php esc_html_e('Grant TTL', 'baskerville-ai-security'); ?></th>
+				<td>
+					<input type="number" name="baskerville_settings[pay_grant_ttl]" value="<?php echo esc_attr($pay_grant_ttl); ?>" min="60" max="86400" class="baskerville-input-md">
+					<span><?php esc_html_e('seconds', 'baskerville-ai-security'); ?></span>
+					<p class="description"><?php esc_html_e('How long an access grant is valid after payment (60-86400).', 'baskerville-ai-security'); ?></p>
+				</td>
+			</tr>
+		</table>
+
+		<?php submit_button(); ?>
+		</form>
+		<?php
+	}
+
 	public function render_burst_protection_content() {
 		// Get current thresholds
 		$nocookie_threshold = (int) get_option('baskerville_nocookie_threshold', 10);
diff --git a/baskerville-ai-security.php b/baskerville-ai-security.php
index 0649c7c..79ca0a5 100644
--- a/baskerville-ai-security.php
+++ b/baskerville-ai-security.php
@@ -31,6 +31,11 @@
 require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-installer.php';
 require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-maxmind-installer.php';
 require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-turnstile.php';
+require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-pay-storage.php';
+require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-pay-grant.php';
+require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-pay-verifier.php';
+require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-paywall.php';
+require_once BASKERVILLE_PLUGIN_PATH . 'includes/class-baskerville-pay-rest.php';
 require_once BASKERVILLE_PLUGIN_PATH . 'admin/class-baskerville-admin.php';
 
 // Add custom cron intervals
@@ -75,6 +80,23 @@
 	$rest = new Baskerville_REST($core, $stats, $aiua);
 	add_action('rest_api_init', [$rest, 'register_routes']);
 
+	// Pay-per-crawl (x402)
+	$pay_storage = new Baskerville_Pay_Storage($core);
+	$pay_grant   = new Baskerville_Pay_Grant($core);
+	$paywall     = new Baskerville_Paywall($core, $pay_storage, $pay_grant, $stats, $aiua);
+	add_action('template_redirect', [$paywall, 'check_paywall'], 1);
+	$paywall->init_eq402();
+
+	$pay_rest = new Baskerville_Pay_REST($core, $pay_storage, $pay_grant);
+	add_action('rest_api_init', [$pay_rest, 'register_routes']);
+
+	// Cleanup expired pay challenges (daily cron)
+	add_action('baskerville_cleanup_pay_challenges', function () use ($pay_storage) {
+		$options = get_option('baskerville_settings', []);
+		$ttl = (int) ($options['pay_challenge_ttl'] ?? 3600);
+		$pay_storage->cleanup_expired($ttl);
+	});
+
 	// Honeypot for AI bot detection
 	$honeypot = new Baskerville_Honeypot($core, $stats, $aiua);
 	$honeypot->init();
diff --git a/demo/pay_crawler.py b/demo/pay_crawler.py
new file mode 100755
index 0000000..17cad44
--- /dev/null
+++ b/demo/pay_crawler.py
@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""
+Baskerville Pay-Per-Crawl demo client.
+
+Demonstrates the full 402 -> pay -> verify -> access cycle.
+
+Usage:
+    # Stub mode (no real transaction, uses demo_ tx_hash):
+    python pay_crawler.py --stub --site http://localhost:8080 --path /sample-page/
+
+    # Live mode on Polygon Amoy testnet:
+    PRIVATE_KEY=0x... python pay_crawler.py --live --site http://localhost:8080 --path /sample-page/
+
+    # Verbose output:
+    python pay_crawler.py --stub --site http://localhost:8080 --path /sample-page/ --verbose
+"""
+
+import argparse
+import json
+import sys
+import time
+from decimal import Decimal
+
+import requests
+
+# Minimal ERC-20 ABI (only transfer + decimals)
+ERC20_ABI = [
+    {
+        "constant": False,
+        "inputs": [
+            {"name": "_to", "type": "address"},
+            {"name": "_value", "type": "uint256"},
+        ],
+        "name": "transfer",
+        "outputs": [{"name": "", "type": "bool"}],
+        "type": "function",
+    },
+    {
+        "constant": True,
+        "inputs": [],
+        "name": "decimals",
+        "outputs": [{"name": "", "type": "uint8"}],
+        "type": "function",
+    },
+]
+
+# Polygon Amoy testnet USDC (Circle test token)
+AMOY_USDC = "0x41E94Eb71898E8A20f83f5e9A23dA396be8E5F93"
+AMOY_RPC = "https://rpc-amoy.polygon.technology"
+
+AI_BOT_UA = "GPTBot/1.0 (+https://openai.com/gptbot)"
+
+
+def log(msg, verbose=True):
+    if verbose:
+        print(f"  -> {msg}")
+
+
+def step(n, msg):
+    print(f"\n[Step {n}] {msg}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Baskerville Pay-Per-Crawl demo client")
+    parser.add_argument("--site", required=True, help="WordPress site URL (e.g. http://localhost:8080)")
+    parser.add_argument("--path", default="/sample-page/", help="Path to request (default: /sample-page/)")
+    parser.add_argument("--stub", action="store_true", help="Use stub verifier (demo_ tx_hash, no real tx)")
+    parser.add_argument("--live", action="store_true", help="Send real tx on Amoy testnet")
+    parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output")
+    parser.add_argument("--rpc-url", default=AMOY_RPC, help="RPC URL for live mode")
+    parser.add_argument("--private-key", default=None, help="Private key (or use PRIVATE_KEY env var)")
+    args = parser.parse_args()
+
+    if not args.stub and not args.live:
+        args.stub = True  # Default to stub
+
+    site = args.site.rstrip("/")
+    url = f"{site}{args.path}"
+    verbose = args.verbose
+
+    # ── Step 1: GET page with AI bot User-Agent → expect 402 ──
+    step(1, f"GET {url} with AI bot User-Agent")
+    resp = requests.get(url, headers={"User-Agent": AI_BOT_UA}, allow_redirects=True)
+    log(f"Status: {resp.status_code}", verbose)
+
+    if resp.status_code != 402:
+        print(f"\nExpected 402, got {resp.status_code}.")
+        if resp.status_code == 200:
+            print("Page served without paywall. Check that pay_enabled=true, pay_mode=enforce,")
+            print("and ai_score threshold is met for this User-Agent.")
+        if verbose:
+            print(f"Headers: {dict(resp.headers)}")
+            print(f"Body (first 500 chars): {resp.text[:500]}")
+        sys.exit(1)
+
+    try:
+        challenge = resp.json()
+    except json.JSONDecodeError:
+        print("Error: 402 response is not valid JSON")
+        print(f"Body: {resp.text[:500]}")
+        sys.exit(1)
+
+    req_id = challenge.get("req_id", "")
+    amount = challenge.get("amount", "0")
+    wallet = challenge.get("wallet", "")
+    currency = challenge.get("currency", "")
+    network = challenge.get("network", "")
+    asset_type = challenge.get("asset_type", "")
+    token_contract = challenge.get("token_contract", "")
+    proof_endpoint = challenge.get("proof_endpoint", "")
+
+    print(f"  Challenge received:")
+    print(f"    req_id:         {req_id}")
+    print(f"    amount:         {amount} {currency}")
+    print(f"    network:        {network}")
+    print(f"    wallet:         {wallet}")
+    print(f"    asset_type:     {asset_type}")
+    if token_contract:
+        print(f"    token_contract: {token_contract}")
+    print(f"    proof_endpoint: {proof_endpoint}")
+
+    # ── Step 2: Pay ──
+    tx_hash = None
+
+    if args.stub:
+        step(2, "Using stub verifier (demo_ tx_hash)")
+        tx_hash = f"demo_{int(time.time())}_{req_id[:8]}"
+        log(f"tx_hash: {tx_hash}", verbose)
+
+    elif args.live:
+        step(2, "Sending real transaction on testnet")
+        tx_hash = send_real_payment(
+            args=args,
+            wallet=wallet,
+            amount=amount,
+            asset_type=asset_type,
+            token_contract=token_contract,
+            token_decimals=challenge.get("token_decimals", 6),
+            verbose=verbose,
+        )
+        if not tx_hash:
+            print("Error: Transaction failed")
+            sys.exit(1)
+
+    # ── Step 3: Verify payment ──
+    verify_url = proof_endpoint
+    if not verify_url.startswith("http"):
+        verify_url = f"{site}{verify_url}"
+
+    step(3, f"POST {verify_url}")
+    verify_resp = requests.post(
+        verify_url,
+        json={"req_id": req_id, "tx_hash": tx_hash},
+        headers={"Content-Type": "application/json"},
+    )
+    log(f"Status: {verify_resp.status_code}", verbose)
+
+    if verify_resp.status_code == 202:
+        print("  Payment pending (unconfirmed). Retrying in 5 seconds...")
+        for attempt in range(1, 13):
+            time.sleep(5)
+            verify_resp = requests.post(
+                verify_url,
+                json={"req_id": req_id, "tx_hash": tx_hash},
+                headers={"Content-Type": "application/json"},
+            )
+            log(f"Retry {attempt}: status {verify_resp.status_code}", verbose)
+            if verify_resp.status_code != 202:
+                break
+
+    if verify_resp.status_code != 200:
+        print(f"\nVerification failed: {verify_resp.status_code}")
+        print(f"Response: {verify_resp.text[:500]}")
+        sys.exit(1)
+
+    verify_data = verify_resp.json()
+    grant = verify_data.get("grant", "")
+    grant_url = verify_data.get("grant_url", "")
+    expires_at = verify_data.get("expires_at", "")
+
+    print(f"  Grant received:")
+    print(f"    grant:      {grant[:40]}...")
+    print(f"    expires_at: {expires_at}")
+    if grant_url:
+        print(f"    grant_url:  {grant_url[:80]}...")
+
+    # ── Step 4: GET page with grant → expect 200 ──
+    # Prefer grant_url (query param) for CDN compatibility, fall back to Bearer header
+    if grant_url:
+        step(4, f"GET grant_url (CDN-friendly)")
+        content_resp = requests.get(
+            grant_url,
+            headers={"User-Agent": AI_BOT_UA},
+            allow_redirects=True,
+        )
+        log(f"Status: {content_resp.status_code}", verbose)
+
+        if content_resp.status_code != 200:
+            log("grant_url failed, falling back to Bearer header...", verbose)
+            content_resp = requests.get(
+                url,
+                headers={
+                    "User-Agent": AI_BOT_UA,
+                    "Authorization": f"Bearer {grant}",
+                },
+                allow_redirects=True,
+            )
+            log(f"Status (Bearer): {content_resp.status_code}", verbose)
+    else:
+        step(4, f"GET {url} with Bearer grant")
+        content_resp = requests.get(
+            url,
+            headers={
+                "User-Agent": AI_BOT_UA,
+                "Authorization": f"Bearer {grant}",
+            },
+            allow_redirects=True,
+        )
+        log(f"Status: {content_resp.status_code}", verbose)
+
+    if content_resp.status_code == 200:
+        print("\n  SUCCESS! Content served with valid grant.")
+        if verbose:
+            body = content_resp.text
+            print(f"\n  Content (first 300 chars):\n  {body[:300]}")
+    else:
+        print(f"\n  FAILED: Expected 200, got {content_resp.status_code}")
+        if verbose:
+            print(f"  Headers: {dict(content_resp.headers)}")
+            print(f"  Body: {content_resp.text[:500]}")
+        sys.exit(1)
+
+
+def send_real_payment(args, wallet, amount, asset_type, token_contract, token_decimals, verbose):
+    """Send a real payment on testnet via web3.py."""
+    try:
+        from web3 import Web3
+    except ImportError:
+        print("Error: web3 package required for live mode. Run: pip install web3")
+        sys.exit(1)
+
+    import os
+
+    private_key = args.private_key or os.environ.get("PRIVATE_KEY", "")
+    if not private_key:
+        print("Error: --private-key or PRIVATE_KEY env var required for live mode")
+        sys.exit(1)
+
+    rpc_url = args.rpc_url
+    w3 = Web3(Web3.HTTPProvider(rpc_url))
+
+    if not w3.is_connected():
+        print(f"Error: Cannot connect to RPC at {rpc_url}")
+        sys.exit(1)
+
+    account = w3.eth.account.from_key(private_key)
+    sender = account.address
+    log(f"Sender address: {sender}", verbose)
+    log(f"Balance: {w3.from_wei(w3.eth.get_balance(sender), 'ether')} native", verbose)
+
+    if asset_type == "native":
+        # Send native currency
+        value_wei = w3.to_wei(Decimal(amount), "ether")
+        tx = {
+            "to": wallet,
+            "value": value_wei,
+            "gas": 21000,
+            "gasPrice": w3.eth.gas_price,
+            "nonce": w3.eth.get_transaction_count(sender),
+            "chainId": w3.eth.chain_id,
+        }
+    else:
+        # Send ERC-20 token
+        contract_addr = Web3.to_checksum_address(token_contract)
+        usdc = w3.eth.contract(address=contract_addr, abi=ERC20_ABI)
+        amount_smallest = int(Decimal(amount) * (10 ** token_decimals))
+
+        tx = usdc.functions.transfer(
+            Web3.to_checksum_address(wallet),
+            amount_smallest,
+        ).build_transaction(
+            {
+                "from": sender,
+                "gas": 100000,
+                "gasPrice": w3.eth.gas_price,
+                "nonce": w3.eth.get_transaction_count(sender),
+                "chainId": w3.eth.chain_id,
+            }
+        )
+
+    log("Signing and sending transaction...", verbose)
+    signed = w3.eth.account.sign_transaction(tx, private_key)
+    tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
+    tx_hash_hex = tx_hash.hex()
+    log(f"tx_hash: {tx_hash_hex}", verbose)
+
+    log("Waiting for transaction receipt...", verbose)
+    receipt = w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120)
+    log(f"Block: {receipt['blockNumber']}, Status: {receipt['status']}", verbose)
+
+    if receipt["status"] != 1:
+        print("Error: Transaction reverted on-chain")
+        return None
+
+    return tx_hash_hex
+
+
+if __name__ == "__main__":
+    main()
diff --git a/demo/requirements.txt b/demo/requirements.txt
new file mode 100644
index 0000000..345631c
--- /dev/null
+++ b/demo/requirements.txt
@@ -0,0 +1,2 @@
+web3>=6.0.0
+requests>=2.28.0
diff --git a/demo/test_pay.py b/demo/test_pay.py
new file mode 100755
index 0000000..af10ffa
--- /dev/null
+++ b/demo/test_pay.py
@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""
+Baskerville /eq402 end-to-end payment test.
+
+Visits the dedicated /eq402 test page (always behind the paywall),
+pays, verifies, and displays the congratulations page.
+
+Usage:
+    # Manual mode — pay in MetaMask yourself, paste tx_hash:
+    python test_pay.py --manual --site http://localhost:8080
+
+    # Stub mode (demo_ tx_hash, no real blockchain tx):
+    python test_pay.py --stub --site http://localhost:8080
+
+    # Automatic payment via private key:
+    PRIVATE_KEY=0x... python test_pay.py --site http://localhost:8080
+
+    # Explicit private key + custom RPC:
+    python test_pay.py --site http://localhost:8080 --private-key 0x... --rpc-url https://...
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+from decimal import Decimal
+
+import requests
+
+# Minimal ERC-20 ABI (only transfer)
+ERC20_ABI = [
+    {
+        "constant": False,
+        "inputs": [
+            {"name": "_to", "type": "address"},
+            {"name": "_value", "type": "uint256"},
+        ],
+        "name": "transfer",
+        "outputs": [{"name": "", "type": "bool"}],
+        "type": "function",
+    },
+]
+
+AMOY_RPC = "https://rpc-amoy.polygon.technology"
+
+
+def info(msg):
+    print(f"  {msg}")
+
+
+def header(msg):
+    print(f"\n{'=' * 60}")
+    print(f"  {msg}")
+    print(f"{'=' * 60}")
+
+
+def step(n, msg):
+    print(f"\n[{n}] {msg}")
+
+
+def send_real_payment(private_key, rpc_url, wallet, amount, asset_type, token_contract, token_decimals):
+    """Send a real payment on-chain via web3.py. Returns tx_hash hex string."""
+    try:
+        from web3 import Web3
+    except ImportError:
+        print("Error: web3 package required. Run: pip install web3")
+        sys.exit(1)
+
+    w3 = Web3(Web3.HTTPProvider(rpc_url))
+    if not w3.is_connected():
+        print(f"Error: Cannot connect to RPC at {rpc_url}")
+        sys.exit(1)
+
+    account = w3.eth.account.from_key(private_key)
+    sender = account.address
+    info(f"Wallet address: {sender}")
+    info(f"Native balance: {w3.from_wei(w3.eth.get_balance(sender), 'ether')}")
+
+    if asset_type == "native":
+        value_wei = w3.to_wei(Decimal(amount), "ether")
+        tx = {
+            "to": wallet,
+            "value": value_wei,
+            "gas": 21000,
+            "gasPrice": w3.eth.gas_price,
+            "nonce": w3.eth.get_transaction_count(sender),
+            "chainId": w3.eth.chain_id,
+        }
+    else:
+        contract_addr = Web3.to_checksum_address(token_contract)
+        usdc = w3.eth.contract(address=contract_addr, abi=ERC20_ABI)
+        amount_smallest = int(Decimal(amount) * (10 ** token_decimals))
+        tx = usdc.functions.transfer(
+            Web3.to_checksum_address(wallet),
+            amount_smallest,
+        ).build_transaction({
+            "from": sender,
+            "gas": 100000,
+            "gasPrice": w3.eth.gas_price,
+            "nonce": w3.eth.get_transaction_count(sender),
+            "chainId": w3.eth.chain_id,
+        })
+
+    info(f"Sending {amount} {asset_type} to {wallet}...")
+    signed = w3.eth.account.sign_transaction(tx, private_key)
+    tx_hash = w3.eth.send_raw_transaction(signed.raw_transaction)
+    tx_hash_hex = tx_hash.hex()
+    info(f"tx_hash: {tx_hash_hex}")
+
+    info("Waiting for transaction receipt...")
+    receipt = w3.eth.wait_for_transaction_receipt(tx_hash, timeout=120)
+    info(f"Block: {receipt['blockNumber']}, Status: {receipt['status']}")
+
+    if receipt["status"] != 1:
+        print("Error: Transaction reverted on-chain")
+        return None
+
+    return tx_hash_hex
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Baskerville /eq402 end-to-end payment test")
+    parser.add_argument("--site", required=True, help="WordPress site URL (e.g. http://localhost:8080)")
+    parser.add_argument("--manual", action="store_true", help="Manual mode: pay in MetaMask, paste tx_hash")
+    parser.add_argument("--private-key", default=None, help="Wallet private key (or PRIVATE_KEY env var)")
+    parser.add_argument("--rpc-url", default=AMOY_RPC, help=f"RPC endpoint (default: Amoy testnet)")
+    parser.add_argument("--stub", action="store_true", help="Use demo_ tx_hash (no real blockchain payment)")
+    args = parser.parse_args()
+
+    private_key = args.private_key or os.environ.get("PRIVATE_KEY", "")
+
+    # Determine mode
+    if args.manual:
+        mode = "manual"
+    elif args.stub:
+        mode = "stub"
+    elif private_key:
+        mode = "live"
+    else:
+        print("Error: Use --manual, --stub, or provide --private-key / PRIVATE_KEY env var.")
+        sys.exit(1)
+
+    site = args.site.rstrip("/")
+    eq402_url = f"{site}/eq402"
+
+    header("Baskerville Pay-Per-Crawl Test")
+    info(f"Target: {eq402_url}")
+    info(f"Mode:   {mode}")
+
+    # ── Step 1: GET /eq402 → expect 402 ──────────────────────
+    step(1, f"GET {eq402_url}")
+    resp = requests.get(eq402_url, allow_redirects=True)
+    info(f"Status: {resp.status_code}")
+
+    # Use the final URL after redirects (http→https, www, trailing slash, etc.)
+    # This ensures Bearer header isn't stripped on redirect in step 4.
+    if resp.url != eq402_url:
+        eq402_url = resp.url
+        info(f"Redirected to: {eq402_url}")
+
+    if resp.status_code != 402:
+        print(f"\nExpected 402, got {resp.status_code}.")
+        if resp.status_code == 503:
+            print("The /eq402 page says paywall is not enabled/enforced.")
+            print("Ensure pay_enabled=true and pay_mode=enforce in Baskerville settings.")
+        print(f"Body: {resp.text[:500]}")
+        sys.exit(1)
+
+    try:
+        challenge = resp.json()
+    except json.JSONDecodeError:
+        print("Error: 402 response is not valid JSON")
+        print(f"Body: {resp.text[:500]}")
+        sys.exit(1)
+
+    req_id         = challenge.get("req_id", "")
+    amount         = challenge.get("amount", "0")
+    wallet         = challenge.get("wallet", "")
+    currency       = challenge.get("currency", "")
+    network        = challenge.get("network", "")
+    asset_type     = challenge.get("asset_type", "")
+    token_contract = challenge.get("token_contract", "")
+    token_decimals = challenge.get("token_decimals", 6)
+    proof_endpoint = challenge.get("proof_endpoint", "")
+
+    info(f"Challenge received:")
+    info(f"  req_id:   {req_id}")
+    info(f"  amount:   {amount} {currency}")
+    info(f"  network:  {network}")
+    info(f"  wallet:   {wallet}")
+    info(f"  asset:    {asset_type}")
+    if token_contract:
+        info(f"  token:    {token_contract}")
+    info(f"  verify:   {proof_endpoint}")
+
+    # ── Step 2: Pay ───────────────────────────────────────────
+    tx_hash = None
+
+    if mode == "manual":
+        step(2, "Manual payment")
+        print()
+        print("  Send the following payment in MetaMask:")
+        print(f"    To:       {wallet}")
+        print(f"    Amount:   {amount} {currency}")
+        print(f"    Network:  {network}")
+        if asset_type == "erc20" and token_contract:
+            print(f"    Token:    {token_contract}")
+        print()
+        print("  After the transaction confirms, paste the tx hash below.")
+        print()
+        tx_hash = input("  tx_hash: ").strip()
+        if not tx_hash:
+            print("Error: No tx_hash provided.")
+            sys.exit(1)
+        info(f"Using tx_hash: {tx_hash}")
+
+    elif mode == "stub":
+        step(2, "Generating demo tx_hash (stub mode)")
+        tx_hash = f"demo_{int(time.time())}_{req_id[:8]}"
+        info(f"tx_hash: {tx_hash}")
+
+    elif mode == "live":
+        step(2, f"Sending {amount} {currency} on {network}")
+        tx_hash = send_real_payment(
+            private_key=private_key,
+            rpc_url=args.rpc_url,
+            wallet=wallet,
+            amount=amount,
+            asset_type=asset_type,
+            token_contract=token_contract,
+            token_decimals=token_decimals,
+        )
+        if not tx_hash:
+            print("Error: Transaction failed")
+            sys.exit(1)
+
+    # ── Step 3: Verify payment ────────────────────────────────
+    verify_url = proof_endpoint
+    if not verify_url.startswith("http"):
+        verify_url = f"{site}{verify_url}"
+
+    while True:
+        step(3, "Verifying payment...")
+        info(f"POST {verify_url}")
+        verify_resp = requests.post(
+            verify_url,
+            json={"req_id": req_id, "tx_hash": tx_hash},
+            headers={"Content-Type": "application/json"},
+        )
+        info(f"Status: {verify_resp.status_code}")
+
+        # Handle pending (unconfirmed) — auto-retry up to 60s
+        if verify_resp.status_code == 202:
+            info("Payment pending (unconfirmed). Waiting for confirmations...")
+            for attempt in range(1, 13):
+                time.sleep(5)
+                verify_resp = requests.post(
+                    verify_url,
+                    json={"req_id": req_id, "tx_hash": tx_hash},
+                    headers={"Content-Type": "application/json"},
+                )
+                info(f"Retry {attempt}: status {verify_resp.status_code}")
+                if verify_resp.status_code != 202:
+                    break
+
+        if verify_resp.status_code == 200:
+            break
+
+        # Verification failed — show error
+        try:
+            err = verify_resp.json()
+            err_code = err.get("code", "unknown")
+        except Exception:
+            err_code = "unknown"
+
+        err_detail = err.get("detail", "") if isinstance(err, dict) else ""
+        print(f"\n  Verification failed: {verify_resp.status_code} ({err_code})")
+        if err_detail:
+            print(f"  Detail: {err_detail}")
+
+        if err_code == "invalid_tx":
+            print("  The tx_hash was rejected. Possible causes:")
+            print("    - pay_verifier_type is 'stub' (only accepts demo_ hashes)")
+            print("    - Transaction not found on-chain or reverted")
+            print("    - Wrong tx_hash format")
+        elif err_code == "provider_error":
+            print("  The server could not reach the blockchain RPC.")
+            print("  Check pay_provider / pay_api_key in Baskerville settings,")
+            print("  or the server may not have outbound HTTPS access.")
+
+        if mode == "manual":
+            print()
+            retry = input("  Try another tx_hash? [Y/n]: ").strip().lower()
+            if retry in ("n", "no"):
+                sys.exit(1)
+            tx_hash = input("  tx_hash: ").strip()
+            if not tx_hash:
+                print("Error: No tx_hash provided.")
+                sys.exit(1)
+            info(f"Using tx_hash: {tx_hash}")
+            continue
+        else:
+            print(f"  Response: {verify_resp.text[:500]}")
+            sys.exit(1)
+
+    verify_data = verify_resp.json()
+    grant      = verify_data.get("grant", "")
+    grant_url  = verify_data.get("grant_url", "")
+    expires_at = verify_data.get("expires_at", "")
+
+    info(f"Grant received: {grant[:40]}...")
+    info(f"Expires at:     {expires_at}")
+    if grant_url:
+        info(f"Grant URL:      {grant_url[:80]}...")
+
+    # ── Step 4: GET /eq402 with grant → expect 200 ───────────
+    # Try grant_url first (CDN-friendly: grant in query param bypasses edge cache),
+    # fall back to Authorization: Bearer header.
+    if grant_url:
+        step(4, f"GET grant_url (CDN-friendly query param)")
+        info(f"URL: {grant_url[:100]}...")
+        content_resp = requests.get(grant_url, allow_redirects=True)
+        info(f"Status: {content_resp.status_code}")
+
+        if content_resp.status_code != 200:
+            info("grant_url failed, falling back to Authorization: Bearer header...")
+            content_resp = requests.get(
+                eq402_url,
+                headers={"Authorization": f"Bearer {grant}"},
+                allow_redirects=True,
+            )
+            info(f"Status (Bearer): {content_resp.status_code}")
+    else:
+        step(4, f"GET {eq402_url} with Bearer grant")
+        content_resp = requests.get(
+            eq402_url,
+            headers={"Authorization": f"Bearer {grant}"},
+            allow_redirects=True,
+        )
+        info(f"Status: {content_resp.status_code}")
+
+    if content_resp.status_code == 200:
+        print(f"\n{content_resp.text}")
+        header("SUCCESS")
+    else:
+        print(f"\nFAILED: Expected 200, got {content_resp.status_code}")
+        # Show debug headers from server
+        for h in ("X-Eq402-Debug-Canonical", "X-Eq402-Debug-Has-Auth", "X-Eq402-Debug-Token-Prefix"):
+            if h in content_resp.headers:
+                info(f"{h}: {content_resp.headers[h]}")
+        info(f"Final URL: {content_resp.url}")
+        print(f"Body: {content_resp.text[:500]}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/eq402.md b/eq402.md
new file mode 100644
index 0000000..3d865aa
--- /dev/null
+++ b/eq402.md
@@ -0,0 +1,353 @@
+# Baskerville WordPress Plugin — Pay-Per-Crawl (eq402) Spec v0.2
+
+**Goal:** Ship a working WordPress plugin where Baskerville detects AI/automated agents and enforces pay-per-crawl using HTTP 402 + a machine-readable payment challenge, then issues a short-lived access grant after verifying payment to a publisher wallet.
+
+**Non-goals (MVP):**
+- Browser UI / checkout pages / subscriptions
+- Perfect bot-proofing (this is economic gating + rate control)
+
+---
+
+## CDN Cache vs Origin
+
+If a CDN (e.g. Deflect) sits in front of WordPress, the paywall must still work. The plugin supports three grant delivery methods to handle CDN caching and header stripping (see Section 7.1).
+
+### Demo path: `/eq402`
+- The `/eq402` test page is always behind the paywall (no `ai_score` check).
+- Plugin sets `DONOTCACHEPAGE`, `Cache-Control: no-store`, and `Vary: Authorization, Cookie` on 402 responses.
+- For Deflect: add a bypass rule for `/eq402` to always pass to origin.
+
+### Production paywall: CDN considerations
+
+#### Option A: Deflect enforces at the edge
+- Edge estimates `ai_score` from `User-Agent`
+- If request looks like an AI bot: edge returns `402` directly, or proxies to origin with cache bypass
+- If grant is present (Bearer header, query param, or cookie): edge proxies to origin for validation
+
+#### Option B: Bypass cache for AI bots
+- Deflect rule: if `User-Agent` matches AI bot patterns, bypass cache and pass to origin
+- Origin plugin decides whether to return `402` or content
+- Normal users continue to receive cached content
+
+#### Option C: Query parameter grant (CDN-agnostic)
+- Client appends `?grant=BV1.xxx` to the URL after payment
+- CDN treats it as a unique URL and passes to origin
+- Plugin reads grant from query param; canonical URL strips query string so validation still works
+- This works with any CDN without configuration changes
+
+---
+
+## 1) Concepts
+
+- **Publisher**: site owner (WP admin), receives payments to a wallet.
+- **Client**: crawler/agent fetching content.
+- **Paywall policy**: rule deciding when a request requires payment.
+- **Challenge**: HTTP 402 response describing how to pay.
+- **Verifier**: module that confirms a payment happened (tx lookup, webhook, or stub for demo).
+- **Grant**: short-lived HMAC token minted by the plugin once payment is confirmed; used for subsequent requests.
+
+---
+
+## 2) Admin Configuration (WP)
+
+### 2.1 Global
+- `pay_enabled` (bool)
+- `pay_mode` = `off | observe | test | enforce`
+  - `off`: paywall disabled
+  - `observe`: never blocks; adds `Baskerville-Paywall: would-402` header
+  - `test`: only `/eq402` is paywalled (no `ai_score` check on other pages)
+  - `enforce`: returns 402 when policy triggers on all protected paths
+- `pay_ai_threshold` (0..100), default 70
+- `pay_protected_paths` (newline-separated globs), default `/*`
+- `pay_price` (decimal string), e.g. `"0.10"`
+- `pay_currency` (string), e.g. `"USDC"`
+- `pay_network` (string), e.g. `"polygon"`
+- `pay_wallet_address` (string), publisher recipient
+- `pay_challenge_ttl` (int seconds), default 3600
+- `pay_grant_ttl` (int seconds), default 900
+
+### 2.2 Asset constraints
+- `pay_asset_type` = `native | erc20`
+- If `erc20`: `pay_token_contract` (string) and `pay_token_decimals` (int)
+
+### 2.3 Verifier
+- `pay_verifier_type` = `stub | polling`
+  - `stub`: accepts tx hashes starting with `demo_` (development/demo)
+  - `polling`: looks up `tx_hash` via blockchain RPC
+- If `polling`: `pay_provider` (alchemy/infura/ankr/direct), `pay_api_key`, `pay_min_confirmations` (int, default 5)
+
+---
+
+## 3) Paywall Policy
+
+A request is **paywalled** when ALL are true:
+1. `pay_enabled=true` and `pay_mode=enforce`
+2. Request method is `GET` or `HEAD`
+3. User is not logged in
+4. Request is not to wp-admin, REST API, or AJAX
+5. Request path matches `pay_protected_paths` (fnmatch glob)
+6. Baskerville `ai_score >= pay_ai_threshold`
+7. Request does NOT contain a valid **Grant** (Section 7)
+
+The `/eq402` test page skips rules 1 (accepts `test` mode too), 4, 5, and 6 — it is always paywalled when `pay_enabled=true` and `pay_mode` is `enforce` or `test`.
+
+Allowlists:
+- WP logged-in users bypass paywall
+- The firewall (`plugins_loaded`) skips all checks for `/eq402` requests
+
+---
+
+## 4) Canonical URL and Challenge ID
+
+### 4.1 Canonical URL
+`scheme://host/path` — query string is always stripped. This is important: grant tokens are validated against the canonical URL, so `?grant=BV1.xxx` does not affect matching.
+
+### 4.2 Challenge ID (`req_id`)
+On paywall trigger:
+- `nonce = random_bytes(16)` (b64url)
+- `day_bucket = YYYY-MM-DD` in site timezone
+- `req_id = b64url( SHA256( site_origin + "|" + canonical_url + "|" + day_bucket + "|" + nonce ) )`
+
+Persisted in `wp_baskerville_pay_challenges`.
+
+---
+
+## 5) 402 Challenge
+
+### 5.1 Response status and headers
+
+- Status: `402 Payment Required`
+- Headers:
+  - `Content-Type: application/json`
+  - `Cache-Control: no-store, no-cache, must-revalidate, max-age=0`
+  - `Vary: Authorization, Cookie`
+  - `Baskerville-Pay: required`
+  - `Baskerville-Req-Id: <req_id>`
+  - `Baskerville-Price: <price>`
+  - `Baskerville-Currency: <currency>`
+  - `Baskerville-Network: <network>`
+  - `Baskerville-Wallet: <wallet_address>`
+  - `Baskerville-Asset-Type: <native|erc20>`
+  - `Baskerville-Token-Contract: <token_contract>` (only if erc20)
+  - `Baskerville-Proof-Endpoint: <proof_endpoint_url>`
+  - `Baskerville-Grant-TTL: <grant_ttl_seconds>`
+  - `Baskerville-Reason: ai_score=<n>;policy=paywall`
+
+### 5.2 JSON body
+```json
+{
+  "error": "payment_required",
+  "req_id": "…",
+  "amount": "0.10",
+  "currency": "USDC",
+  "network": "polygon",
+  "wallet": "0x…",
+  "asset_type": "erc20",
+  "token_contract": "0x…",
+  "proof_endpoint": "https://example.com/wp-json/baskerville/v1/payments/verify",
+  "grant_ttl_seconds": 900
+}
+```
+
+---
+
+## 6) Payment Proof Submission
+
+### 6.1 Verify endpoint
+
+`POST /wp-json/baskerville/v1/payments/verify`
+
+Rate limited: max 5 requests per minute per IP + `req_id`.
+
+**Request JSON:**
+```json
+{
+  "req_id": "…",
+  "tx_hash": "…"
+}
+```
+
+**Response on success (200):**
+```json
+{
+  "status": "ok",
+  "req_id": "…",
+  "grant": "BV1.…",
+  "grant_url": "https://example.com/article/123?grant=BV1.…",
+  "expires_at": "2026-03-13T10:25:35+00:00"
+}
+```
+
+The response also sets a `baskerville_grant` cookie scoped to the canonical URL path, with `httponly`, `secure`, and `samesite=Lax` flags. TTL matches the grant.
+
+**`grant_url`**: The canonical URL with `?grant=<token>` appended. Clients behind a CDN should use this URL instead of `Authorization: Bearer` to bypass edge cache (see Section 7.1).
+
+**Response on pending (202):**
+```json
+{
+  "status": "pending",
+  "code": "unconfirmed"
+}
+```
+
+**Response on failure (400/404/429):**
+```json
+{
+  "status": "error",
+  "code": "not_found|expired|already_used|wrong_recipient|wrong_asset|underpaid|invalid_tx|provider_error",
+  "detail": "optional error message"
+}
+```
+
+---
+
+## 7) Grant Token (HMAC)
+
+### 7.1 Grant delivery methods
+
+The plugin accepts grant tokens from three sources, checked in priority order:
+
+1. **`Authorization: Bearer BV1.xxx`** header — standard method, works when CDN passes the header through to origin.
+2. **`?grant=BV1.xxx`** query parameter — CDN-friendly: the unique URL bypasses edge cache. Canonical URL strips query string, so grant validation is unaffected. The verify endpoint returns a ready-to-use `grant_url` with this parameter.
+3. **`baskerville_grant` cookie** — set automatically by the verify endpoint. Works for browser-based clients and CDNs that bypass cache on cookie presence.
+
+### 7.2 Token format
+
+```
+BV1.<b64url(payload_json)>.<b64url(sig_bytes)>
+```
+
+Where:
+```
+sig_bytes = HMAC_SHA256(secret, "BV1." + payload_b64url)
+```
+
+### 7.3 Secret
+
+A 32+ byte random secret. Prefer `BASKERVILLE_GRANT_SECRET` constant in `wp-config.php`, fallback to auto-generated WP option `baskerville_grant_secret`.
+
+### 7.4 Payload JSON
+```json
+{
+  "v": 1,
+  "iss": "https://example.com",
+  "req_id": "…",
+  "url": "https://example.com/articles/123",
+  "m": ["GET", "HEAD"],
+  "iat": 1730000000,
+  "exp": 1730000900
+}
+```
+
+### 7.5 Validation rules
+
+A grant is valid if ALL are true:
+1. HMAC signature matches (timing-safe comparison)
+2. `exp >= now` (not expired)
+3. Request method is in `m` array
+4. `url` exactly equals the canonical URL of the current request
+
+If valid, the paywall is bypassed.
+
+---
+
+## 8) Storage (minimal tables)
+
+### 8.1 `wp_baskerville_pay_challenges`
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `req_id` | varchar(64) | PK |
+| `canonical_url` | text | |
+| `price` | varchar(32) | |
+| `currency` | varchar(16) | |
+| `network` | varchar(32) | |
+| `wallet_address` | varchar(64) | |
+| `asset_type` | varchar(16) | |
+| `token_contract` | varchar(64) | |
+| `token_decimals` | int | |
+| `ai_score` | int | |
+| `ip` | varchar(45) | |
+| `nonce` | varchar(32) | |
+| `created_at` | datetime | indexed |
+| `status` | enum | `new`, `paid`, `expired` |
+
+Cleanup cron marks challenges older than `pay_challenge_ttl` as `expired`, then hard-deletes records older than 7 days.
+
+### 8.2 `wp_baskerville_pay_receipts`
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `tx_hash` | varchar(128) | PK (prevents double-spend) |
+| `req_id` | varchar(64) | indexed |
+| `confirmed_at` | datetime | |
+| `raw_json` | text | full provider response |
+
+Grants are stateless (no grants table) — validity is purely cryptographic.
+
+---
+
+## 9) Verifier Requirements
+
+The verifier confirms payment for `{req_id, tx_hash}` by checking:
+
+1. Transaction exists on the configured network
+2. Transaction is confirmed (`>= min_confirmations`, default 5)
+3. Recipient matches `wallet_address`
+4. Asset matches config:
+   - `native`: tx value >= price
+   - `erc20`: tx logs contain `Transfer(to=wallet, value>=price_in_smallest_units)` for `token_contract`
+5. Transaction timestamp is within `challenge_ttl` of challenge `created_at`
+
+Verifier outputs: `confirmed(receipt)` | `pending(code)` | `rejected(code)`
+
+Supported networks: `polygon`, `polygon-amoy`, `ethereum`.
+Supported providers: `alchemy`, `infura`, `ankr`, or direct RPC URL.
+
+The stub verifier accepts any `tx_hash` starting with `demo_` and returns confirmed.
+
+---
+
+## 10) Request Flow (happy path)
+
+```
+1. Client  →  GET /article/123
+2. Plugin  ←  402 { req_id, wallet, price, asset, proof_endpoint }
+3. Client  →  Pays on-chain to wallet
+4. Client  →  POST /payments/verify { req_id, tx_hash }
+5. Plugin  ←  200 { grant: "BV1.…", grant_url: "https://…?grant=BV1.…" }
+6. Client  →  GET grant_url (or GET /article/123 with Bearer header)
+7. Plugin  ←  200 (content served)
+```
+
+Step 6: The client should prefer `grant_url` (query parameter) when behind a CDN, as it bypasses edge cache. The `Authorization: Bearer` header works when there is no CDN or when the CDN passes headers through.
+
+---
+
+## 11) Security Notes
+
+- `Cache-Control: no-store` + `Vary: Authorization, Cookie` on all 402 responses.
+- Rate limit `/payments/verify` by IP + `req_id` (max 5/min).
+- Keep `pay_grant_ttl` short (10–30 min).
+- Fix `network` + `asset_type` + `token_contract` to prevent "junk token" bypass.
+- Grant tokens in query params are visible in server logs — acceptable because grants are short-lived and URL-scoped.
+- The `baskerville_grant` cookie is `httponly` + `secure` + `samesite=Lax`.
+- If misclassification risk is high, start with `pay_mode=observe`, collect logs, then enable `enforce`.
+
+---
+
+## 12) Test tools
+
+### `/eq402` test page
+Always paywalled (no `ai_score` check). Available when `pay_enabled=true` and `pay_mode` is `enforce` or `test`. Shows a congratulations page on successful grant validation.
+
+### `demo/test_pay.py`
+End-to-end test script. Modes:
+- `--stub`: uses `demo_` tx hashes (no blockchain)
+- `--manual`: pay in MetaMask, paste tx_hash
+- `PRIVATE_KEY=0x…`: automatic on-chain payment
+
+Uses `grant_url` (query param) by default for CDN compatibility, with Bearer header fallback.
+
+### `demo/pay_crawler.py`
+Multi-page crawler that pays for access. Same CDN-friendly grant delivery.
diff --git a/includes/class-baskerville-core.php b/includes/class-baskerville-core.php
index db9996b..b3187b1 100644
--- a/includes/class-baskerville-core.php
+++ b/includes/class-baskerville-core.php
@@ -73,6 +73,19 @@ public function cookie_secret(): string {
         return $secret;
     }
 
+    /** Secret for signing grant tokens (pay-per-crawl) */
+    public function grant_secret(): string {
+        if (defined('BASKERVILLE_GRANT_SECRET') && BASKERVILLE_GRANT_SECRET) {
+            return BASKERVILLE_GRANT_SECRET;
+        }
+        $secret = (string) get_option('baskerville_grant_secret', '');
+        if (!$secret) {
+            $secret = bin2hex(random_bytes(32));
+            update_option('baskerville_grant_secret', $secret, true);
+        }
+        return $secret;
+    }
+
     /** Sign the main cookie: include ip_key in HMAC */
     private function sign_cookie(string $token, int $ts, string $ipk): string {
         return hash_hmac('sha256', $token . '.' . $ts . '.' . $ipk, $this->cookie_secret());
diff --git a/includes/class-baskerville-deflect-geoip.php b/includes/class-baskerville-deflect-geoip.php
new file mode 100644
index 0000000..73484b5
--- /dev/null
+++ b/includes/class-baskerville-deflect-geoip.php
@@ -0,0 +1,568 @@
+<?php
+
+if (!defined('ABSPATH')) {
+	exit;
+}
+
+/**
+ * Deflect GeoIP database handler
+ * Uses deflect-ca/deflect-geoip database for IP to country lookups
+ *
+ * Database format:
+ * - latest.json contains metadata about current release
+ * - countrydb.csv.gz contains CIDR prefixes mapped to country codes
+ */
+class Baskerville_Deflect_GeoIP {
+
+	/** Base URL for deflect-geoip releases */
+	private const BASE_URL = 'https://deflect-ca.github.io/deflect-geoip';
+
+	/** Option key for storing database version */
+	private const VERSION_OPTION = 'baskerville_deflect_geoip_version';
+
+	/** Option key for storing last update check time */
+	private const LAST_CHECK_OPTION = 'baskerville_deflect_geoip_last_check';
+
+	/** Database file path relative to wp-content/uploads */
+	private const DB_FILE = 'baskerville-geoip/countrydb.php';
+
+	/** Cached database in memory */
+	private static ?array $db_cache = null;
+
+	/** Optimized lookup structures */
+	private static ?array $ipv4_index = null;
+	private static ?array $ipv6_index = null;
+
+	/**
+	 * Check if deflect-geoip database is installed
+	 * @return bool
+	 */
+	public function is_installed(): bool {
+		$db_path = $this->get_db_path();
+		return file_exists($db_path) && filesize($db_path) > 0;
+	}
+
+	/**
+	 * Get database file path
+	 * @return string
+	 */
+	public function get_db_path(): string {
+		return WP_CONTENT_DIR . '/uploads/' . self::DB_FILE;
+	}
+
+	/**
+	 * Get current installed version
+	 * @return string|null
+	 */
+	public function get_version(): ?string {
+		return get_option(self::VERSION_OPTION, null);
+	}
+
+	/**
+	 * Check for updates and download if needed
+	 * @param bool $force Force update check even if recently checked
+	 * @return array{success: bool, message: string, updated?: bool}
+	 */
+	public function update(bool $force = false): array {
+		// Check if we recently checked for updates (within 1 hour)
+		$last_check = (int) get_option(self::LAST_CHECK_OPTION, 0);
+		if (!$force && (time() - $last_check) < 3600) {
+			return array(
+				'success' => true,
+				'message' => __('Update check skipped (recently checked)', 'baskerville'),
+				'updated' => false,
+			);
+		}
+
+		// Fetch latest.json
+		$latest_url = self::BASE_URL . '/releases/latest.json';
+		$response = wp_remote_get($latest_url, array('timeout' => 30));
+
+		if (is_wp_error($response)) {
+			return array(
+				'success' => false,
+				'message' => sprintf(
+					/* translators: %s: error message */
+					__('Failed to check for updates: %s', 'baskerville'),
+					$response->get_error_message()
+				),
+			);
+		}
+
+		$body = wp_remote_retrieve_body($response);
+		$latest = json_decode($body, true);
+
+		if (!$latest || empty($latest['version']) || empty($latest['artifacts'][0])) {
+			return array(
+				'success' => false,
+				'message' => __('Invalid response from update server', 'baskerville'),
+			);
+		}
+
+		$version = $latest['version'];
+		$artifact = $latest['artifacts'][0];
+		$sha256 = $artifact['sha256'] ?? '';
+
+		// Update last check time
+		update_option(self::LAST_CHECK_OPTION, time());
+
+		// Check if we already have this version
+		$current_version = $this->get_version();
+		if ($current_version === $version && $this->is_installed()) {
+			return array(
+				'success' => true,
+				'message' => sprintf(
+					/* translators: %s: version string */
+					__('Already up to date (version %s)', 'baskerville'),
+					$version
+				),
+				'updated' => false,
+			);
+		}
+
+		// Download database
+		$db_url = self::BASE_URL . '/' . $artifact['path'];
+		$response = wp_remote_get($db_url, array('timeout' => 120));
+
+		if (is_wp_error($response)) {
+			return array(
+				'success' => false,
+				'message' => sprintf(
+					/* translators: %s: error message */
+					__('Failed to download database: %s', 'baskerville'),
+					$response->get_error_message()
+				),
+			);
+		}
+
+		$gz_data = wp_remote_retrieve_body($response);
+
+		// Verify SHA256
+		if ($sha256 && hash('sha256', $gz_data) !== $sha256) {
+			return array(
+				'success' => false,
+				'message' => __('SHA256 checksum mismatch - download may be corrupted', 'baskerville'),
+			);
+		}
+
+		// Decompress
+		$csv_data = @gzdecode($gz_data);
+		if ($csv_data === false) {
+			return array(
+				'success' => false,
+				'message' => __('Failed to decompress database', 'baskerville'),
+			);
+		}
+
+		// Parse CSV and build optimized lookup structure
+		$result = $this->parse_and_save_db($csv_data, $version);
+		if (!$result['success']) {
+			return $result;
+		}
+
+		// Update version
+		update_option(self::VERSION_OPTION, $version);
+
+		// Clear memory cache
+		self::$db_cache = null;
+		self::$ipv4_index = null;
+		self::$ipv6_index = null;
+
+		return array(
+			'success' => true,
+			'message' => sprintf(
+				/* translators: %s: version string */
+				__('Database updated to version %s', 'baskerville'),
+				$version
+			),
+			'updated' => true,
+		);
+	}
+
+	/**
+	 * Parse CSV data and save as optimized PHP array
+	 * @param string $csv_data Raw CSV content
+	 * @param string $version Version string
+	 * @return array{success: bool, message: string}
+	 */
+	private function parse_and_save_db(string $csv_data, string $version): array {
+		$lines = explode("\n", $csv_data);
+
+		// Remove header
+		if (!empty($lines) && strpos($lines[0], 'prefix') !== false) {
+			array_shift($lines);
+		}
+
+		$ipv4_prefixes = array();
+		$ipv6_prefixes = array();
+
+		foreach ($lines as $line) {
+			$line = trim($line);
+			if (empty($line)) continue;
+
+			$parts = explode(',', $line, 2);
+			if (count($parts) !== 2) continue;
+
+			$prefix = trim($parts[0]);
+			$country = strtoupper(trim($parts[1]));
+
+			if (strlen($country) !== 2) continue;
+
+			// Separate IPv4 and IPv6
+			if (strpos($prefix, ':') !== false) {
+				$ipv6_prefixes[$prefix] = $country;
+			} else {
+				$ipv4_prefixes[$prefix] = $country;
+			}
+		}
+
+		// Sort by prefix length (longer prefixes first for most specific match)
+		$ipv4_sorted = $this->sort_by_prefix_length($ipv4_prefixes);
+		$ipv6_sorted = $this->sort_by_prefix_length($ipv6_prefixes);
+
+		// Build indexed structure for faster lookup
+		$ipv4_index = $this->build_ipv4_index($ipv4_sorted);
+
+		// Save as PHP file for fast loading
+		$db_path = $this->get_db_path();
+		$db_dir = dirname($db_path);
+
+		// Create directory if it doesn't exist
+		if (!is_dir($db_dir)) {
+			if (!wp_mkdir_p($db_dir)) {
+				return array(
+					'success' => false,
+					'message' => sprintf(
+						/* translators: %s: directory path */
+						__('Failed to create directory: %s', 'baskerville'),
+						$db_dir
+					),
+				);
+			}
+		}
+
+		// Check if directory is writable
+		if (!wp_is_writable($db_dir)) {
+			return array(
+				'success' => false,
+				'message' => sprintf(
+					/* translators: %s: directory path */
+					__('Directory not writable: %s. Please check permissions (chmod 755).', 'baskerville'),
+					$db_dir
+				),
+			);
+		}
+
+		$data = array(
+			'version' => $version,
+			'generated' => time(),
+			'ipv4_index' => $ipv4_index,
+			'ipv4' => $ipv4_sorted,
+			'ipv6' => $ipv6_sorted,
+			'stats' => array(
+				'ipv4_count' => count($ipv4_sorted),
+				'ipv6_count' => count($ipv6_sorted),
+			),
+		);
+
+		$php_content = "<?php\n// Deflect GeoIP Database - Auto-generated\n// Version: {$version}\n// DO NOT EDIT\nreturn " . var_export($data, true) . ";\n";
+
+		// Try to write using WordPress filesystem
+		global $wp_filesystem;
+		if (!function_exists('WP_Filesystem')) {
+			require_once ABSPATH . 'wp-admin/includes/file.php';
+		}
+
+		// Initialize filesystem
+		if (!WP_Filesystem()) {
+			// Fallback to direct file write
+			$result = @file_put_contents($db_path, $php_content, LOCK_EX);
+			if ($result === false) {
+				$error_info = error_get_last();
+				return array(
+					'success' => false,
+					'message' => sprintf(
+						/* translators: %s: file path */
+						__('Failed to save database to: %s. Error: %s', 'baskerville'),
+						$db_path,
+						$error_info['message'] ?? 'Unknown error'
+					),
+				);
+			}
+		} else {
+			// Use WordPress filesystem
+			$result = $wp_filesystem->put_contents($db_path, $php_content, FS_CHMOD_FILE);
+			if (!$result) {
+				// Fallback to direct write
+				$result = @file_put_contents($db_path, $php_content, LOCK_EX);
+				if ($result === false) {
+					return array(
+						'success' => false,
+						'message' => sprintf(
+							/* translators: %s: file path */
+							__('Failed to save database to: %s. Check file permissions.', 'baskerville'),
+							$db_path
+						),
+					);
+				}
+			}
+		}
+
+		return array(
+			'success' => true,
+			'message' => sprintf(
+				/* translators: 1: IPv4 count, 2: IPv6 count */
+				__('Parsed %1$d IPv4 and %2$d IPv6 prefixes', 'baskerville'),
+				count($ipv4_sorted),
+				count($ipv6_sorted)
+			),
+		);
+	}
+
+	/**
+	 * Sort prefixes by prefix length (longer first)
+	 * @param array $prefixes
+	 * @return array
+	 */
+	private function sort_by_prefix_length(array $prefixes): array {
+		uksort($prefixes, function($a, $b) {
+			$bits_a = (int) explode('/', $a)[1];
+			$bits_b = (int) explode('/', $b)[1];
+			return $bits_b - $bits_a; // Longer prefix first
+		});
+		return $prefixes;
+	}
+
+	/**
+	 * Build index by first octet for fast IPv4 lookup
+	 * @param array $prefixes
+	 * @return array
+	 */
+	private function build_ipv4_index(array $prefixes): array {
+		$index = array();
+		foreach ($prefixes as $prefix => $country) {
+			$first_octet = (int) explode('.', $prefix)[0];
+			if (!isset($index[$first_octet])) {
+				$index[$first_octet] = array();
+			}
+			$index[$first_octet][$prefix] = $country;
+		}
+		return $index;
+	}
+
+	/**
+	 * Load database into memory
+	 * @return bool
+	 */
+	private function load_db(): bool {
+		if (self::$db_cache !== null) {
+			return true;
+		}
+
+		$db_path = $this->get_db_path();
+		if (!file_exists($db_path)) {
+			return false;
+		}
+
+		$data = include $db_path;
+		if (!is_array($data)) {
+			return false;
+		}
+
+		self::$db_cache = $data;
+		self::$ipv4_index = $data['ipv4_index'] ?? array();
+		self::$ipv6_index = $data['ipv6'] ?? array();
+
+		return true;
+	}
+
+	/**
+	 * Lookup country by IP address
+	 * @param string $ip IPv4 or IPv6 address
+	 * @return string|null Two-letter country code or null if not found
+	 */
+	public function lookup(string $ip): ?string {
+		if (!$this->load_db()) {
+			return null;
+		}
+
+		// IPv4
+		if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
+			return $this->lookup_ipv4($ip);
+		}
+
+		// IPv6
+		if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
+			return $this->lookup_ipv6($ip);
+		}
+
+		return null;
+	}
+
+	/**
+	 * Lookup IPv4 address using indexed structure
+	 * @param string $ip
+	 * @return string|null
+	 */
+	private function lookup_ipv4(string $ip): ?string {
+		$ip_long = ip2long($ip);
+		if ($ip_long === false) {
+			return null;
+		}
+
+		$first_octet = (int) explode('.', $ip)[0];
+
+		// Check indexed prefixes for this first octet
+		if (isset(self::$ipv4_index[$first_octet])) {
+			foreach (self::$ipv4_index[$first_octet] as $prefix => $country) {
+				if ($this->ip_in_cidr_v4($ip_long, $prefix)) {
+					return $country;
+				}
+			}
+		}
+
+		// Fallback: check 0.0.0.0/0 type prefixes if any
+		if (isset(self::$ipv4_index[0])) {
+			foreach (self::$ipv4_index[0] as $prefix => $country) {
+				if ($this->ip_in_cidr_v4($ip_long, $prefix)) {
+					return $country;
+				}
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Check if IPv4 long matches CIDR
+	 * @param int $ip_long
+	 * @param string $cidr
+	 * @return bool
+	 */
+	private function ip_in_cidr_v4(int $ip_long, string $cidr): bool {
+		$parts = explode('/', $cidr);
+		$subnet = ip2long($parts[0]);
+		$bits = (int) ($parts[1] ?? 32);
+
+		if ($subnet === false || $bits < 0 || $bits > 32) {
+			return false;
+		}
+
+		$mask = $bits === 0 ? 0 : (~0 << (32 - $bits));
+		return ($ip_long & $mask) === ($subnet & $mask);
+	}
+
+	/**
+	 * Lookup IPv6 address
+	 * @param string $ip
+	 * @return string|null
+	 */
+	private function lookup_ipv6(string $ip): ?string {
+		$ip_bin = @inet_pton($ip);
+		if ($ip_bin === false) {
+			return null;
+		}
+
+		foreach (self::$ipv6_index as $prefix => $country) {
+			if ($this->ip_in_cidr_v6($ip_bin, $prefix)) {
+				return $country;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Check if IPv6 binary matches CIDR
+	 * @param string $ip_bin Binary representation of IP
+	 * @param string $cidr
+	 * @return bool
+	 */
+	private function ip_in_cidr_v6(string $ip_bin, string $cidr): bool {
+		$parts = explode('/', $cidr);
+		$subnet_bin = @inet_pton($parts[0]);
+		$bits = (int) ($parts[1] ?? 128);
+
+		if ($subnet_bin === false || $bits < 0 || $bits > 128) {
+			return false;
+		}
+
+		// Build mask
+		$mask = str_repeat("\xff", intdiv($bits, 8));
+		$remaining_bits = $bits % 8;
+		if ($remaining_bits > 0) {
+			$mask .= chr(0xff << (8 - $remaining_bits));
+		}
+		$mask = str_pad($mask, 16, "\x00");
+
+		return ($ip_bin & $mask) === ($subnet_bin & $mask);
+	}
+
+	/**
+	 * Get database statistics
+	 * @return array
+	 */
+	public function get_stats(): array {
+		if (!$this->load_db()) {
+			return array(
+				'installed' => false,
+				'version' => null,
+				'ipv4_count' => 0,
+				'ipv6_count' => 0,
+			);
+		}
+
+		return array(
+			'installed' => true,
+			'version' => self::$db_cache['version'] ?? null,
+			'generated' => self::$db_cache['generated'] ?? null,
+			'ipv4_count' => self::$db_cache['stats']['ipv4_count'] ?? 0,
+			'ipv6_count' => self::$db_cache['stats']['ipv6_count'] ?? 0,
+		);
+	}
+
+	/**
+	 * Test database with sample IPs
+	 * @return array
+	 */
+	public function test(): array {
+		$test_ips = array(
+			'8.8.8.8' => 'US',       // Google DNS
+			'1.1.1.1' => 'AU',       // Cloudflare (APNIC)
+			'185.60.216.35' => null, // Variable
+			'2001:4860:4860::8888' => 'US', // Google IPv6 DNS
+		);
+
+		$results = array();
+		foreach ($test_ips as $ip => $expected) {
+			$actual = $this->lookup($ip);
+			$results[$ip] = array(
+				'expected' => $expected,
+				'actual' => $actual,
+				'match' => $expected === null || $actual === $expected,
+			);
+		}
+
+		return $results;
+	}
+
+	/**
+	 * Delete database and reset
+	 * @return bool
+	 */
+	public function delete(): bool {
+		$db_path = $this->get_db_path();
+		if (file_exists($db_path)) {
+			wp_delete_file($db_path);
+		}
+
+		delete_option(self::VERSION_OPTION);
+		delete_option(self::LAST_CHECK_OPTION);
+
+		self::$db_cache = null;
+		self::$ipv4_index = null;
+		self::$ipv6_index = null;
+
+		return true;
+	}
+}
diff --git a/includes/class-baskerville-firewall.php b/includes/class-baskerville-firewall.php
index 4d33634..e475cde 100644
--- a/includes/class-baskerville-firewall.php
+++ b/includes/class-baskerville-firewall.php
@@ -204,6 +204,11 @@ public function pre_db_firewall(): void {
 			return;
 		}
 
+		// Skip firewall for /eq402 test page — it has its own access control (paywall 402)
+		if (strpos($request_uri, '/eq402') === 0 || strpos($request_uri, 'baskerville_eq402') !== false) {
+			return;
+		}
+
 		// Check if this is an API request (REST, GraphQL, webhooks, etc.)
 		$is_api = $this->core->is_api_request();
 		if ($is_api) {
diff --git a/includes/class-baskerville-installer.php b/includes/class-baskerville-installer.php
index a619189..2436549 100644
--- a/includes/class-baskerville-installer.php
+++ b/includes/class-baskerville-installer.php
@@ -18,6 +18,10 @@ public static function activate() {
 			$stats->maybe_upgrade_schema();
 		}
 
+		// Pay-per-crawl tables
+		$pay_storage = new Baskerville_Pay_Storage($core);
+		$pay_storage->create_tables();
+
 		// Default options (don't overwrite if already exist)
 		if (get_option('baskerville_retention_days') === false) {
 			add_option('baskerville_retention_days', BASKERVILLE_DEFAULT_RETENTION_DAYS);
@@ -25,6 +29,9 @@ public static function activate() {
 		if (get_option('baskerville_cookie_secret') === false) {
 			add_option('baskerville_cookie_secret', bin2hex(random_bytes(32)));
 		}
+		if (get_option('baskerville_grant_secret') === false) {
+			add_option('baskerville_grant_secret', bin2hex(random_bytes(32)));
+		}
 
 		if (get_option('baskerville_nocookie_window_sec') === false)  add_option('baskerville_nocookie_window_sec', 60);
 		if (get_option('baskerville_nocookie_threshold') === false)   add_option('baskerville_nocookie_threshold', 10);
@@ -54,6 +61,20 @@ public static function activate() {
 			$settings['log_mode'] = 'database'; // Database logging by default
 			$needs_update = true;
 		}
+		// Pay-per-crawl defaults
+		if (!isset($settings['pay_enabled'])) {
+			$settings['pay_enabled'] = false;
+			$needs_update = true;
+		}
+		if (!isset($settings['pay_mode'])) {
+			$settings['pay_mode'] = 'off';
+			$needs_update = true;
+		}
+		if (!isset($settings['pay_ai_threshold'])) {
+			$settings['pay_ai_threshold'] = 70;
+			$needs_update = true;
+		}
+
 		if ($needs_update) {
 			update_option('baskerville_settings', $settings);
 		}
@@ -78,6 +99,11 @@ public static function activate() {
 			wp_schedule_event(time(), 'daily', 'baskerville_cleanup_log_files');
 		}
 
+		// Cron for pay challenge cleanup (daily)
+		if (!wp_next_scheduled('baskerville_cleanup_pay_challenges')) {
+			wp_schedule_event(time(), 'daily', 'baskerville_cleanup_pay_challenges');
+		}
+
 		// Cron for weekly Deflect GeoIP database update
 		if (!wp_next_scheduled('baskerville_update_deflect_geoip')) {
 			wp_schedule_event(time(), 'baskerville_weekly', 'baskerville_update_deflect_geoip');
@@ -157,6 +183,7 @@ public static function deactivate() {
 		wp_clear_scheduled_hook('baskerville_process_log_files');
 		wp_clear_scheduled_hook('baskerville_cleanup_log_files');
 		wp_clear_scheduled_hook('baskerville_update_deflect_geoip');
+		wp_clear_scheduled_hook('baskerville_cleanup_pay_challenges');
 
 		// Clean up rewrite rules
 		flush_rewrite_rules();
diff --git a/includes/class-baskerville-pay-grant.php b/includes/class-baskerville-pay-grant.php
new file mode 100644
index 0000000..94341f3
--- /dev/null
+++ b/includes/class-baskerville-pay-grant.php
@@ -0,0 +1,108 @@
+<?php
+
+if (!defined('ABSPATH')) {
+	exit;
+}
+
+/**
+ * BV1 grant tokens: mint and validate HMAC-signed access grants.
+ *
+ * Format: BV1.<b64url(payload_json)>.<b64url(hmac_sha256)>
+ */
+class Baskerville_Pay_Grant {
+
+	private Baskerville_Core $core;
+
+	public function __construct(Baskerville_Core $core) {
+		$this->core = $core;
+	}
+
+	/**
+	 * Mint a new BV1 grant token.
+	 *
+	 * @param string $req_id       Challenge request ID.
+	 * @param string $canonical_url The canonical URL this grant covers.
+	 * @param int    $ttl          Token lifetime in seconds.
+	 * @return array{grant: string, expires_at: string}
+	 */
+	public function mint(string $req_id, string $canonical_url, int $ttl = 900): array {
+		$now = time();
+		$exp = $now + $ttl;
+
+		$payload = [
+			'v'      => 1,
+			'iss'    => home_url(),
+			'req_id' => $req_id,
+			'url'    => $canonical_url,
+			'm'      => ['GET', 'HEAD'],
+			'iat'    => $now,
+			'exp'    => $exp,
+		];
+
+		$payload_b64 = $this->core->b64u_enc(wp_json_encode($payload));
+		$sig_input   = 'BV1.' . $payload_b64;
+		$sig_bytes   = hash_hmac('sha256', $sig_input, $this->core->grant_secret(), true);
+		$sig_b64     = $this->core->b64u_enc($sig_bytes);
+
+		$grant = 'BV1.' . $payload_b64 . '.' . $sig_b64;
+
+		return [
+			'grant'      => $grant,
+			'expires_at' => gmdate('c', $exp),
+		];
+	}
+
+	/**
+	 * Validate a BV1 grant token.
+	 *
+	 * @param string $token         The full BV1.xxx.sig token.
+	 * @param string $canonical_url The canonical URL of the current request.
+	 * @param string $method        The HTTP method (GET, HEAD, etc.).
+	 * @return array|null Payload array on success, null on failure.
+	 */
+	public function validate(string $token, string $canonical_url, string $method = 'GET'): ?array {
+		$parts = explode('.', $token, 3);
+		if (count($parts) !== 3 || $parts[0] !== 'BV1') {
+			return null;
+		}
+
+		$payload_b64 = $parts[1];
+		$sig_b64     = $parts[2];
+
+		// Verify signature
+		$sig_input    = 'BV1.' . $payload_b64;
+		$expected_sig = hash_hmac('sha256', $sig_input, $this->core->grant_secret(), true);
+		$actual_sig   = $this->core->b64u_dec($sig_b64);
+
+		if (!hash_equals($expected_sig, $actual_sig)) {
+			return null;
+		}
+
+		// Decode payload
+		$json = $this->core->b64u_dec($payload_b64);
+		$payload = json_decode($json, true);
+		if (!is_array($payload)) {
+			return null;
+		}
+
+		// Check expiry
+		$exp = (int) ($payload['exp'] ?? 0);
+		if ($exp < time()) {
+			return null;
+		}
+
+		// Check method
+		$allowed_methods = $payload['m'] ?? [];
+		if (!in_array(strtoupper($method), $allowed_methods, true)) {
+			return null;
+		}
+
+		// Check URL
+		$grant_url = $payload['url'] ?? '';
+		if ($grant_url !== $canonical_url) {
+			return null;
+		}
+
+		return $payload;
+	}
+}
diff --git a/includes/class-baskerville-pay-rest.php b/includes/class-baskerville-pay-rest.php
new file mode 100644
index 0000000..5160a7c
--- /dev/null
+++ b/includes/class-baskerville-pay-rest.php
@@ -0,0 +1,169 @@
+<?php
+
+if (!defined('ABSPATH')) {
+	exit;
+}
+
+/**
+ * REST endpoint: POST /baskerville/v1/payments/verify
+ */
+class Baskerville_Pay_REST {
+
+	private Baskerville_Core $core;
+	private Baskerville_Pay_Storage $storage;
+	private Baskerville_Pay_Grant $grant;
+
+	public function __construct(
+		Baskerville_Core $core,
+		Baskerville_Pay_Storage $storage,
+		Baskerville_Pay_Grant $grant
+	) {
+		$this->core    = $core;
+		$this->storage = $storage;
+		$this->grant   = $grant;
+	}
+
+	/**
+	 * Register REST routes.
+	 */
+	public function register_routes(): void {
+		register_rest_route('baskerville/v1', '/payments/verify', [
+			'methods'             => WP_REST_Server::CREATABLE,
+			'callback'            => [$this, 'handle_verify'],
+			'permission_callback' => function () { return true; }, // public endpoint, rate-limited below
+		]);
+	}
+
+	/**
+	 * Handle POST /baskerville/v1/payments/verify
+	 *
+	 * @param WP_REST_Request $request
+	 * @return WP_REST_Response
+	 */
+	public function handle_verify(WP_REST_Request $request): WP_REST_Response {
+		$ip     = sanitize_text_field(wp_unslash($_SERVER['REMOTE_ADDR'] ?? ''));
+		$params = $request->get_json_params();
+
+		$req_id  = sanitize_text_field($params['req_id'] ?? '');
+		$tx_hash = sanitize_text_field($params['tx_hash'] ?? '');
+
+		if (!$req_id || !$tx_hash) {
+			return new WP_REST_Response([
+				'status' => 'error',
+				'code'   => 'missing_params',
+			], 400);
+		}
+
+		// 1. Rate limit: max 5 per minute per IP+req_id
+		$rl_key = "pay_verify:{$ip}:{$req_id}";
+		$count  = $this->core->fc_inc_in_window($rl_key, 60);
+		if ($count > 5) {
+			return new WP_REST_Response([
+				'status' => 'error',
+				'code'   => 'rate_limited',
+			], 429);
+		}
+
+		// 2. Look up challenge
+		$challenge = $this->storage->get_challenge($req_id);
+		if (!$challenge) {
+			return new WP_REST_Response([
+				'status' => 'error',
+				'code'   => 'not_found',
+			], 404);
+		}
+
+		// 3. Check challenge not expired
+		$options       = get_option('baskerville_settings', []);
+		$challenge_ttl = (int) ($options['pay_challenge_ttl'] ?? 3600);
+		$created_ts    = strtotime($challenge->created_at . ' UTC');
+
+		if ($challenge->status === 'expired' || (time() - $created_ts) > $challenge_ttl) {
+			$this->storage->update_challenge_status($req_id, 'expired');
+			return new WP_REST_Response([
+				'status' => 'error',
+				'code'   => 'expired',
+			], 400);
+		}
+
+		// 4. Check tx_hash not already used
+		if ($this->storage->receipt_exists($tx_hash)) {
+			return new WP_REST_Response([
+				'status' => 'error',
+				'code'   => 'already_used',
+			], 400);
+		}
+
+		// 5. Run verifier
+		$verifier = Baskerville_Pay_Verifier_Factory::create($options);
+		try {
+			$result = $verifier->verify($tx_hash, $challenge);
+		} catch (\Throwable $e) {
+			return new WP_REST_Response([
+				'status' => 'error',
+				'code'   => 'internal_server_error',
+				'detail' => $e->getMessage(),
+			], 500);
+		}
+
+		// 6. Handle result
+		if ($result->status === 'confirmed') {
+			// Store receipt
+			$receipt_data = $result->receipt ?? [];
+			$receipt_data['tx_hash'] = $tx_hash;
+			$receipt_data['req_id']  = $req_id;
+			$this->storage->insert_receipt($receipt_data);
+
+			// Mark challenge paid
+			$this->storage->update_challenge_status($req_id, 'paid');
+
+			// Mint grant
+			$grant_ttl = (int) ($options['pay_grant_ttl'] ?? 900);
+			$grant_data = $this->grant->mint($req_id, $challenge->canonical_url, $grant_ttl);
+
+			// Set grant cookie (browser/CDN-friendly fallback for Authorization header)
+			$grant_token = $grant_data['grant'];
+			$cookie_path = wp_parse_url($challenge->canonical_url, PHP_URL_PATH) ?: '/';
+			setcookie('baskerville_grant', $grant_token, [
+				'expires'  => time() + $grant_ttl,
+				'path'     => $cookie_path,
+				'secure'   => is_ssl(),
+				'httponly' => true,
+				'samesite' => 'Lax',
+			]);
+
+			// Build grant_url: canonical URL + ?grant= for CDN cache-bust
+			$grant_url = $challenge->canonical_url
+				. (strpos($challenge->canonical_url, '?') !== false ? '&' : '?')
+				. 'grant=' . urlencode($grant_token);
+
+			return new WP_REST_Response([
+				'status'     => 'ok',
+				'req_id'     => $req_id,
+				'grant'      => $grant_token,
+				'grant_url'  => $grant_url,
+				'expires_at' => $grant_data['expires_at'],
+			], 200);
+		}
+
+		if ($result->status === 'pending') {
+			return new WP_REST_Response([
+				'status' => 'pending',
+				'code'   => $result->code,
+			], 202);
+		}
+
+		// rejected
+		$error_response = [
+			'status' => 'error',
+			'code'   => $result->code,
+		];
+
+		// Include error detail when available (helps debugging)
+		if (!empty($verifier->last_error)) {
+			$error_response['detail'] = $verifier->last_error;
+		}
+
+		return new WP_REST_Response($error_response, 400);
+	}
+}
diff --git a/includes/class-baskerville-pay-storage.php b/includes/class-baskerville-pay-storage.php
new file mode 100644
index 0000000..fdbffe5
--- /dev/null
+++ b/includes/class-baskerville-pay-storage.php
@@ -0,0 +1,206 @@
+<?php
+
+if (!defined('ABSPATH')) {
+	exit;
+}
+
+/**
+ * Pay-per-crawl storage: challenges + receipts tables via dbDelta().
+ */
+class Baskerville_Pay_Storage {
+
+	private Baskerville_Core $core;
+
+	public function __construct(Baskerville_Core $core) {
+		$this->core = $core;
+	}
+
+	/* ===== Table names ===== */
+
+	private function challenges_table(): string {
+		global $wpdb;
+		return $wpdb->prefix . 'baskerville_pay_challenges';
+	}
+
+	private function receipts_table(): string {
+		global $wpdb;
+		return $wpdb->prefix . 'baskerville_pay_receipts';
+	}
+
+	/* ===== Schema ===== */
+
+	/**
+	 * Create or upgrade pay tables. Called on plugin activation.
+	 *
+	 * @phpcs:disable WordPress.DB.DirectDatabaseQuery
+	 */
+	public function create_tables(): void {
+		global $wpdb;
+		$charset = $wpdb->get_charset_collate();
+
+		$challenges = $this->challenges_table();
+		$receipts   = $this->receipts_table();
+
+		$sql_challenges = "CREATE TABLE $challenges (
+			req_id varchar(64) NOT NULL,
+			canonical_url text NOT NULL,
+			price varchar(32) NOT NULL,
+			currency varchar(16) NOT NULL,
+			network varchar(32) NOT NULL,
+			wallet_address varchar(64) NOT NULL,
+			asset_type varchar(16) NOT NULL DEFAULT 'native',
+			token_contract varchar(64) NOT NULL DEFAULT '',
+			token_decimals smallint NOT NULL DEFAULT 18,
+			ai_score smallint NOT NULL DEFAULT 0,
+			ip varchar(45) NOT NULL DEFAULT '',
+			nonce varchar(44) NOT NULL DEFAULT '',
+			created_at datetime NOT NULL,
+			status varchar(16) NOT NULL DEFAULT 'new',
+			PRIMARY KEY  (req_id),
+			KEY status (status),
+			KEY created_at (created_at),
+			KEY ip (ip)
+		) $charset;";
+
+		$sql_receipts = "CREATE TABLE $receipts (
+			tx_hash varchar(128) NOT NULL,
+			req_id varchar(64) NOT NULL,
+			amount varchar(32) NOT NULL DEFAULT '0',
+			currency varchar(16) NOT NULL DEFAULT '',
+			network varchar(32) NOT NULL DEFAULT '',
+			wallet_address varchar(64) NOT NULL DEFAULT '',
+			asset_type varchar(16) NOT NULL DEFAULT 'native',
+			token_contract varchar(64) NOT NULL DEFAULT '',
+			confirmed_at datetime NOT NULL,
+			raw_json longtext NOT NULL,
+			PRIMARY KEY  (tx_hash),
+			KEY req_id (req_id)
+		) $charset;";
+
+		require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+		dbDelta($sql_challenges);
+		dbDelta($sql_receipts);
+	}
+
+	/* ===== Challenge CRUD ===== */
+
+	/**
+	 * Insert a new challenge record.
+	 *
+	 * @phpcs:disable WordPress.DB.DirectDatabaseQuery
+	 */
+	public function insert_challenge(array $data): bool {
+		global $wpdb;
+		return (bool) $wpdb->insert($this->challenges_table(), [
+			'req_id'          => $data['req_id'],
+			'canonical_url'   => $data['canonical_url'],
+			'price'           => $data['price'],
+			'currency'        => $data['currency'],
+			'network'         => $data['network'],
+			'wallet_address'  => $data['wallet_address'],
+			'asset_type'      => $data['asset_type'] ?? 'native',
+			'token_contract'  => $data['token_contract'] ?? '',
+			'token_decimals'  => $data['token_decimals'] ?? 18,
+			'ai_score'        => $data['ai_score'] ?? 0,
+			'ip'              => $data['ip'] ?? '',
+			'nonce'           => $data['nonce'] ?? '',
+			'created_at'      => gmdate('Y-m-d H:i:s'),
+			'status'          => 'new',
+		]);
+	}
+
+	/**
+	 * Fetch a challenge by req_id.
+	 *
+	 * @phpcs:disable WordPress.DB.DirectDatabaseQuery
+	 */
+	public function get_challenge(string $req_id): ?object {
+		global $wpdb;
+		$table = $this->challenges_table();
+		// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		$row = $wpdb->get_row($wpdb->prepare("SELECT * FROM $table WHERE req_id = %s", $req_id));
+		return $row ?: null;
+	}
+
+	/**
+	 * Update challenge status (new -> paid | expired).
+	 *
+	 * @phpcs:disable WordPress.DB.DirectDatabaseQuery
+	 */
+	public function update_challenge_status(string $req_id, string $status): bool {
+		global $wpdb;
+		return (bool) $wpdb->update(
+			$this->challenges_table(),
+			['status' => $status],
+			['req_id' => $req_id],
+			['%s'],
+			['%s']
+		);
+	}
+
+	/* ===== Receipt CRUD ===== */
+
+	/**
+	 * Insert a receipt record.
+	 *
+	 * @phpcs:disable WordPress.DB.DirectDatabaseQuery
+	 */
+	public function insert_receipt(array $data): bool {
+		global $wpdb;
+		return (bool) $wpdb->insert($this->receipts_table(), [
+			'tx_hash'        => $data['tx_hash'],
+			'req_id'         => $data['req_id'],
+			'amount'         => $data['amount'] ?? '0',
+			'currency'       => $data['currency'] ?? '',
+			'network'        => $data['network'] ?? '',
+			'wallet_address' => $data['wallet_address'] ?? '',
+			'asset_type'     => $data['asset_type'] ?? 'native',
+			'token_contract' => $data['token_contract'] ?? '',
+			'confirmed_at'   => gmdate('Y-m-d H:i:s'),
+			'raw_json'       => $data['raw_json'] ?? '{}',
+		]);
+	}
+
+	/**
+	 * Check if a tx_hash has already been used.
+	 *
+	 * @phpcs:disable WordPress.DB.DirectDatabaseQuery
+	 */
+	public function receipt_exists(string $tx_hash): bool {
+		global $wpdb;
+		$table = $this->receipts_table();
+		// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		$count = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM $table WHERE tx_hash = %s", $tx_hash));
+		return $count > 0;
+	}
+
+	/* ===== Maintenance ===== */
+
+	/**
+	 * Expire old challenges and delete them.
+	 *
+	 * @phpcs:disable WordPress.DB.DirectDatabaseQuery
+	 */
+	public function cleanup_expired(int $ttl_seconds = 3600): int {
+		global $wpdb;
+		$table = $this->challenges_table();
+		$cutoff = gmdate('Y-m-d H:i:s', time() - $ttl_seconds);
+
+		// Mark as expired
+		// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		$wpdb->query($wpdb->prepare(
+			"UPDATE $table SET status = 'expired' WHERE status = 'new' AND created_at < %s",
+			$cutoff
+		));
+
+		// Delete very old records (> 7 days)
+		$old_cutoff = gmdate('Y-m-d H:i:s', time() - 7 * 86400);
+		// phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared
+		$deleted = (int) $wpdb->query($wpdb->prepare(
+			"DELETE FROM $table WHERE created_at < %s",
+			$old_cutoff
+		));
+
+		return $deleted;
+	}
+}
diff --git a/includes/class-baskerville-pay-verifier.php b/includes/class-baskerville-pay-verifier.php
new file mode 100644
index 0000000..df5cf47
--- /dev/null
+++ b/includes/class-baskerville-pay-verifier.php
@@ -0,0 +1,485 @@
+<?php
+
+if (!defined('ABSPATH')) {
+	exit;
+}
+
+/**
+ * Value object returned by verifiers.
+ */
+class Baskerville_Pay_Verify_Result {
+
+	/** @var string confirmed|pending|rejected */
+	public string $status;
+
+	/** @var string Machine-readable code (e.g. 'ok', 'unconfirmed', 'wrong_recipient') */
+	public string $code;
+
+	/** @var array|null Receipt data on confirmation */
+	public ?array $receipt;
+
+	public function __construct(string $status, string $code, ?array $receipt = null) {
+		$this->status  = $status;
+		$this->code    = $code;
+		$this->receipt = $receipt;
+	}
+
+	public static function confirmed(array $receipt): self {
+		return new self('confirmed', 'ok', $receipt);
+	}
+
+	public static function pending(string $code = 'unconfirmed'): self {
+		return new self('pending', $code);
+	}
+
+	public static function rejected(string $code): self {
+		return new self('rejected', $code);
+	}
+}
+
+/**
+ * Stub verifier: accepts tx_hash starting with "demo_" and returns confirmed.
+ */
+class Baskerville_Pay_Verifier_Stub {
+
+	/**
+	 * Verify a transaction (stub mode).
+	 *
+	 * @param string $tx_hash  The transaction hash.
+	 * @param object $challenge The challenge record from DB.
+	 * @return Baskerville_Pay_Verify_Result
+	 */
+	public function verify(string $tx_hash, object $challenge): Baskerville_Pay_Verify_Result {
+		if (strpos($tx_hash, 'demo_') !== 0) {
+			return Baskerville_Pay_Verify_Result::rejected('invalid_tx');
+		}
+
+		return Baskerville_Pay_Verify_Result::confirmed([
+			'tx_hash'        => $tx_hash,
+			'amount'         => $challenge->price,
+			'currency'       => $challenge->currency,
+			'network'        => $challenge->network,
+			'wallet_address' => $challenge->wallet_address,
+			'asset_type'     => $challenge->asset_type,
+			'token_contract' => $challenge->token_contract,
+			'raw_json'       => wp_json_encode(['stub' => true, 'tx_hash' => $tx_hash]),
+		]);
+	}
+}
+
+/**
+ * Polling verifier: verifies transactions via Polygon/EVM JSON-RPC.
+ */
+class Baskerville_Pay_Verifier_Polling {
+
+	private string $rpc_url;
+	private int $min_confirmations;
+	private int $challenge_ttl;
+
+	/** ERC-20 Transfer event topic0 */
+	const TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+
+	public function __construct(string $rpc_url, int $min_confirmations = 5, int $challenge_ttl = 3600) {
+		$this->rpc_url           = $rpc_url;
+		$this->min_confirmations = $min_confirmations;
+		$this->challenge_ttl     = $challenge_ttl;
+	}
+
+	/** @var string|null Last RPC error message for debugging */
+	public ?string $last_error = null;
+
+	/**
+	 * Verify a transaction via JSON-RPC.
+	 *
+	 * @param string $tx_hash  The transaction hash (0x-prefixed).
+	 * @param object $challenge The challenge record from DB.
+	 * @return Baskerville_Pay_Verify_Result
+	 */
+	public function verify(string $tx_hash, object $challenge): Baskerville_Pay_Verify_Result {
+		// Validate tx_hash format
+		if (!preg_match('/^0x[0-9a-fA-F]{64}$/', $tx_hash)) {
+			return Baskerville_Pay_Verify_Result::rejected('invalid_tx');
+		}
+
+		// 1. Get transaction receipt
+		$receipt = $this->rpc_call('eth_getTransactionReceipt', [$tx_hash]);
+		if ($receipt === null) {
+			return Baskerville_Pay_Verify_Result::pending('unconfirmed');
+		}
+		if (is_wp_error($receipt)) {
+			$this->last_error = $receipt->get_error_message();
+			return Baskerville_Pay_Verify_Result::rejected('provider_error');
+		}
+
+		// Check tx was successful (status 0x1)
+		$tx_status = $receipt['status'] ?? '0x0';
+		if ($tx_status !== '0x1') {
+			return Baskerville_Pay_Verify_Result::rejected('invalid_tx');
+		}
+
+		// 2. Check confirmations
+		$tx_block = hexdec($receipt['blockNumber'] ?? '0x0');
+		$current_block_hex = $this->rpc_call('eth_blockNumber', []);
+		if (is_wp_error($current_block_hex) || $current_block_hex === null) {
+			return Baskerville_Pay_Verify_Result::rejected('provider_error');
+		}
+		$current_block = hexdec($current_block_hex);
+		$confirmations = $current_block - $tx_block;
+
+		if ($confirmations < $this->min_confirmations) {
+			return Baskerville_Pay_Verify_Result::pending('unconfirmed');
+		}
+
+		// 3. Verify payment details based on asset type
+		$wallet = strtolower($challenge->wallet_address);
+
+		if ($challenge->asset_type === 'native') {
+			return $this->verify_native($tx_hash, $challenge, $wallet);
+		}
+
+		return $this->verify_erc20($receipt, $challenge, $wallet);
+	}
+
+	/**
+	 * Verify native currency transfer (e.g. MATIC/POL).
+	 */
+	private function verify_native(string $tx_hash, object $challenge, string $wallet): Baskerville_Pay_Verify_Result {
+		$tx = $this->rpc_call('eth_getTransactionByHash', [$tx_hash]);
+		if ($tx === null || is_wp_error($tx)) {
+			return Baskerville_Pay_Verify_Result::rejected('provider_error');
+		}
+
+		// Check recipient
+		$to = strtolower($tx['to'] ?? '');
+		if ($to !== $wallet) {
+			return Baskerville_Pay_Verify_Result::rejected('wrong_recipient');
+		}
+
+		// Check value (in wei)
+		$value_wei = self::hex_to_decimal($tx['value'] ?? '0x0');
+		$price_wei = self::mul_by_pow10($challenge->price, 18);
+		if (self::str_cmp($value_wei, $price_wei) < 0) {
+			return Baskerville_Pay_Verify_Result::rejected('underpaid');
+		}
+
+		// Check timestamp within challenge TTL
+		if (!$this->check_tx_timestamp($tx, $challenge)) {
+			return Baskerville_Pay_Verify_Result::rejected('expired');
+		}
+
+		return Baskerville_Pay_Verify_Result::confirmed([
+			'tx_hash'        => $tx_hash,
+			'amount'         => $challenge->price,
+			'currency'       => $challenge->currency,
+			'network'        => $challenge->network,
+			'wallet_address' => $challenge->wallet_address,
+			'asset_type'     => 'native',
+			'token_contract' => '',
+			'raw_json'       => wp_json_encode($tx),
+		]);
+	}
+
+	/**
+	 * Verify ERC-20 token transfer via Transfer event log.
+	 */
+	private function verify_erc20(array $receipt, object $challenge, string $wallet): Baskerville_Pay_Verify_Result {
+		$token_contract = strtolower($challenge->token_contract);
+		$decimals       = (int) $challenge->token_decimals;
+		$price_smallest = self::mul_by_pow10($challenge->price, $decimals);
+
+		$logs = $receipt['logs'] ?? [];
+		foreach ($logs as $log) {
+			$address = strtolower($log['address'] ?? '');
+			$topics  = $log['topics'] ?? [];
+
+			// Must be Transfer event from the correct token contract
+			if ($address !== $token_contract) {
+				continue;
+			}
+			if (count($topics) < 3 || $topics[0] !== self::TRANSFER_TOPIC) {
+				continue;
+			}
+
+			// topics[2] = "to" address (32-byte zero-padded)
+			$to = '0x' . substr($topics[2], -40);
+			if (strtolower($to) !== $wallet) {
+				continue;
+			}
+
+			// data = transfer amount (uint256)
+			$amount_hex = $log['data'] ?? '0x0';
+			$amount = self::hex_to_decimal($amount_hex);
+
+			if (self::str_cmp($amount, $price_smallest) >= 0) {
+				return Baskerville_Pay_Verify_Result::confirmed([
+					'tx_hash'        => $receipt['transactionHash'] ?? '',
+					'amount'         => $challenge->price,
+					'currency'       => $challenge->currency,
+					'network'        => $challenge->network,
+					'wallet_address' => $challenge->wallet_address,
+					'asset_type'     => 'erc20',
+					'token_contract' => $challenge->token_contract,
+					'raw_json'       => wp_json_encode($receipt),
+				]);
+			}
+
+			$this->last_error = 'paid=' . $amount . ' expected=' . $price_smallest . ' hex=' . $amount_hex;
+			return Baskerville_Pay_Verify_Result::rejected('underpaid');
+		}
+
+		return Baskerville_Pay_Verify_Result::rejected('wrong_asset');
+	}
+
+	/**
+	 * Check that the transaction's block timestamp is within challenge TTL.
+	 */
+	private function check_tx_timestamp(array $tx, object $challenge): bool {
+		$block_hex = $tx['blockNumber'] ?? null;
+		if (!$block_hex) {
+			return true; // Can't verify, allow it
+		}
+
+		$block = $this->rpc_call('eth_getBlockByNumber', [$block_hex, false]);
+		if ($block === null || is_wp_error($block)) {
+			return true; // Can't verify, allow it
+		}
+
+		$block_ts   = hexdec($block['timestamp'] ?? '0x0');
+		$created_at = strtotime($challenge->created_at . ' UTC');
+		$diff       = abs($block_ts - $created_at);
+
+		return $diff <= $this->challenge_ttl;
+	}
+
+	/**
+	 * Make a JSON-RPC call to the configured node.
+	 *
+	 * @param string $method RPC method name.
+	 * @param array  $params RPC params.
+	 * @return mixed Result value, null if not found, or WP_Error on failure.
+	 */
+	private function rpc_call(string $method, array $params) {
+		static $id = 0;
+
+		// Try primary RPC, then fallbacks
+		$urls = [$this->rpc_url];
+		$fallbacks = Baskerville_Pay_Verifier_Factory::FALLBACK_RPC_URLS[$this->network_key()] ?? [];
+		foreach ($fallbacks as $fb) {
+			if ($fb !== $this->rpc_url) {
+				$urls[] = $fb;
+			}
+		}
+
+		$last_error = null;
+		foreach ($urls as $url) {
+			$id++;
+			$body = wp_json_encode([
+				'jsonrpc' => '2.0',
+				'method'  => $method,
+				'params'  => $params,
+				'id'      => $id,
+			]);
+
+			$response = wp_remote_post($url, [
+				'headers' => ['Content-Type' => 'application/json'],
+				'body'    => $body,
+				'timeout' => 15,
+			]);
+
+			if (is_wp_error($response)) {
+				$last_error = $response;
+				continue;
+			}
+
+			$code = wp_remote_retrieve_response_code($response);
+			if ($code !== 200) {
+				$last_error = new WP_Error('rpc_http_error', 'RPC HTTP ' . $code . ' from ' . $url);
+				continue;
+			}
+
+			$decoded = json_decode(wp_remote_retrieve_body($response), true);
+			if (!is_array($decoded)) {
+				$last_error = new WP_Error('rpc_decode_error', 'Bad JSON from ' . $url);
+				continue;
+			}
+
+			if (isset($decoded['error'])) {
+				$last_error = new WP_Error('rpc_error', ($decoded['error']['message'] ?? 'RPC error') . ' from ' . $url);
+				continue;
+			}
+
+			return $decoded['result'] ?? null;
+		}
+
+		return $last_error ?? new WP_Error('rpc_all_failed', 'All RPC endpoints failed');
+	}
+
+	/**
+	 * Derive network key from the RPC URL for fallback lookup.
+	 */
+	private function network_key(): string {
+		if (strpos($this->rpc_url, 'amoy') !== false) {
+			return 'polygon-amoy';
+		}
+		if (strpos($this->rpc_url, 'polygon') !== false || strpos($this->rpc_url, 'matic') !== false) {
+			return 'polygon';
+		}
+		if (strpos($this->rpc_url, 'eth') !== false || strpos($this->rpc_url, 'llama') !== false) {
+			return 'ethereum';
+		}
+		return 'polygon'; // default
+	}
+
+	/**
+	 * Convert a hex string to decimal string (for large numbers).
+	 * Works with bcmath, gmp, or pure PHP.
+	 */
+	private static function hex_to_decimal(string $hex): string {
+		$hex = ltrim($hex, '0x');
+		$hex = ltrim($hex, '0');
+		if ($hex === '') {
+			return '0';
+		}
+
+		if (function_exists('gmp_init')) {
+			return gmp_strval(gmp_init($hex, 16));
+		}
+
+		if (function_exists('bcmul')) {
+			$dec = '0';
+			for ($i = 0; $i < strlen($hex); $i++) {
+				$dec = bcadd(bcmul($dec, '16'), (string) hexdec($hex[$i]));
+			}
+			return $dec;
+		}
+
+		// Fallback: only safe for values that fit in PHP int (up to ~9.2e18)
+		return (string) hexdec($hex);
+	}
+
+	/**
+	 * Multiply a decimal string (e.g. "0.10") by 10^exp to get smallest-unit integer string.
+	 */
+	private static function mul_by_pow10(string $value, int $exp): string {
+		// Remove leading/trailing whitespace
+		$value = trim($value);
+
+		// Split on decimal point
+		$parts = explode('.', $value, 2);
+		$integer_part = $parts[0];
+		$frac_part    = $parts[1] ?? '';
+
+		// Pad or trim fractional part to exactly $exp digits
+		if (strlen($frac_part) <= $exp) {
+			$frac_part = str_pad($frac_part, $exp, '0');
+		} else {
+			// More decimals than exp — truncate (shouldn't happen with normal prices)
+			$frac_part = substr($frac_part, 0, $exp);
+		}
+
+		$result = $integer_part . $frac_part;
+		// Remove leading zeros but keep at least '0'
+		$result = ltrim($result, '0') ?: '0';
+
+		return $result;
+	}
+
+	/**
+	 * Compare two numeric strings. Returns -1, 0, or 1.
+	 */
+	private static function str_cmp(string $a, string $b): int {
+		// Remove leading zeros for fair comparison
+		$a = ltrim($a, '0') ?: '0';
+		$b = ltrim($b, '0') ?: '0';
+
+		if (strlen($a) !== strlen($b)) {
+			return strlen($a) <=> strlen($b);
+		}
+
+		return strcmp($a, $b);
+	}
+}
+
+/**
+ * Factory to create the appropriate verifier based on settings.
+ */
+class Baskerville_Pay_Verifier_Factory {
+
+	/** Default RPC URLs by network */
+	const DEFAULT_RPC_URLS = [
+		'polygon'       => 'https://polygon-rpc.com',
+		'polygon-amoy'  => 'https://rpc-amoy.polygon.technology',
+		'ethereum'      => 'https://eth.llamarpc.com',
+	];
+
+	/** Fallback RPC URLs tried when the primary fails */
+	const FALLBACK_RPC_URLS = [
+		'polygon'       => [
+			'https://polygon-rpc.com',
+			'https://rpc.ankr.com/polygon',
+			'https://polygon.llamarpc.com',
+		],
+		'polygon-amoy'  => [
+			'https://rpc-amoy.polygon.technology',
+			'https://rpc.ankr.com/polygon_amoy',
+		],
+		'ethereum'      => [
+			'https://eth.llamarpc.com',
+			'https://rpc.ankr.com/eth',
+		],
+	];
+
+	/**
+	 * Create a verifier instance based on plugin settings.
+	 *
+	 * @param array $options Plugin settings (baskerville_settings).
+	 * @return Baskerville_Pay_Verifier_Stub|Baskerville_Pay_Verifier_Polling
+	 */
+	public static function create(array $options) {
+		$type = $options['pay_verifier_type'] ?? 'stub';
+
+		if ($type === 'polling') {
+			$network  = $options['pay_network'] ?? 'polygon';
+			$provider = $options['pay_provider'] ?? '';
+			$api_key  = $options['pay_api_key'] ?? '';
+
+			// Build RPC URL
+			if ($provider && $api_key) {
+				$rpc_url = self::provider_rpc_url($provider, $network, $api_key);
+			} else {
+				$rpc_url = self::DEFAULT_RPC_URLS[$network] ?? self::DEFAULT_RPC_URLS['polygon'];
+			}
+
+			$min_conf     = (int) ($options['pay_min_confirmations'] ?? 5);
+			$challenge_ttl = (int) ($options['pay_challenge_ttl'] ?? 3600);
+
+			return new Baskerville_Pay_Verifier_Polling($rpc_url, $min_conf, $challenge_ttl);
+		}
+
+		return new Baskerville_Pay_Verifier_Stub();
+	}
+
+	/**
+	 * Build an RPC URL for a named provider.
+	 */
+	private static function provider_rpc_url(string $provider, string $network, string $api_key): string {
+		$network_slug = ($network === 'polygon-amoy') ? 'polygon-amoy' : $network;
+
+		switch ($provider) {
+			case 'alchemy':
+				$chain = ($network_slug === 'polygon-amoy') ? 'polygon-amoy' : 'polygon-mainnet';
+				return "https://{$chain}.g.alchemy.com/v2/{$api_key}";
+
+			case 'infura':
+				$chain = ($network_slug === 'polygon-amoy') ? 'polygon-amoy' : 'polygon-mainnet';
+				return "https://{$chain}.infura.io/v3/{$api_key}";
+
+			case 'ankr':
+				$chain = ($network_slug === 'polygon-amoy') ? 'polygon_amoy' : 'polygon';
+				return "https://rpc.ankr.com/{$chain}/{$api_key}";
+
+			default:
+				return self::DEFAULT_RPC_URLS[$network] ?? self::DEFAULT_RPC_URLS['polygon'];
+		}
+	}
+}
diff --git a/includes/class-baskerville-paywall.php b/includes/class-baskerville-paywall.php
new file mode 100644
index 0000000..b14aba3
--- /dev/null
+++ b/includes/class-baskerville-paywall.php
@@ -0,0 +1,436 @@
+<?php
+
+if (!defined('ABSPATH')) {
+	exit;
+}
+
+/**
+ * Pay-per-crawl policy engine.
+ *
+ * Hooked at template_redirect priority 1 (after log_page_visit at 0).
+ * Checks grant -> checks ai_score -> returns 402 or allows.
+ */
+class Baskerville_Paywall {
+
+	private Baskerville_Core $core;
+	private Baskerville_Pay_Storage $storage;
+	private Baskerville_Pay_Grant $grant;
+	private Baskerville_Stats $stats;
+	private Baskerville_AI_UA $aiua;
+
+	public function __construct(
+		Baskerville_Core $core,
+		Baskerville_Pay_Storage $storage,
+		Baskerville_Pay_Grant $grant,
+		Baskerville_Stats $stats,
+		Baskerville_AI_UA $aiua
+	) {
+		$this->core    = $core;
+		$this->storage = $storage;
+		$this->grant   = $grant;
+		$this->stats   = $stats;
+		$this->aiua    = $aiua;
+	}
+
+	/**
+	 * Register the /eq402 test route (rewrite rule + query var + handler).
+	 */
+	public function init_eq402(): void {
+		add_action('init', [$this, 'register_eq402_route']);
+		add_filter('query_vars', [$this, 'add_eq402_query_var']);
+		add_action('template_redirect', [$this, 'handle_eq402'], -1);
+	}
+
+	/**
+	 * Add baskerville_eq402 to allowed query vars.
+	 */
+	public function add_eq402_query_var(array $vars): array {
+		$vars[] = 'baskerville_eq402';
+		return $vars;
+	}
+
+	/**
+	 * Register rewrite rule: /eq402 → index.php?baskerville_eq402=1
+	 */
+	public function register_eq402_route(): void {
+		add_rewrite_rule(
+			'^eq402/?$',
+			'index.php?baskerville_eq402=1',
+			'top'
+		);
+	}
+
+	/**
+	 * Handle /eq402 requests — always behind paywall (no ai_score check).
+	 * Runs at template_redirect priority -1 (before check_paywall at 1).
+	 */
+	public function handle_eq402(): void {
+		if (!get_query_var('baskerville_eq402')) {
+			return;
+		}
+
+		// Prevent caching plugins (WP-Super-Cache, etc.) from caching this page
+		if (!defined('DONOTCACHEPAGE')) {
+			define('DONOTCACHEPAGE', true);
+		}
+
+		$options = get_option('baskerville_settings', []);
+
+		// Quick exits — pay must be enabled and in test or enforce mode
+		$pay_enabled = !empty($options['pay_enabled']);
+		$pay_mode    = $options['pay_mode'] ?? 'off';
+		if (!$pay_enabled || !in_array($pay_mode, ['enforce', 'test'], true)) {
+			status_header(503);
+			nocache_headers();
+			header('Content-Type: text/plain');
+			echo 'eq402 test page requires pay_enabled=true and pay_mode=enforce or test';
+			exit;
+		}
+
+		$canonical_url = $this->canonical_url();
+		$method        = strtoupper(sanitize_text_field(wp_unslash($_SERVER['REQUEST_METHOD'] ?? 'GET')));
+
+		// Check grant token (Authorization header, ?grant= query param, or cookie)
+		$grant_token = $this->get_grant_token();
+		if ($grant_token) {
+			$payload = $this->grant->validate($grant_token, $canonical_url, $method);
+			if ($payload !== null) {
+				$this->render_eq402_success($payload, $options);
+				exit;
+			}
+			// Debug: grant was present but invalid
+			if (!headers_sent()) {
+				header('X-Eq402-Debug-Canonical: ' . $canonical_url);
+				header('X-Eq402-Debug-Has-Auth: true');
+				header('X-Eq402-Debug-Token-Prefix: ' . substr($grant_token, 0, 30));
+			}
+		} else {
+			if (!headers_sent()) {
+				header('X-Eq402-Debug-Canonical: ' . $canonical_url);
+				header('X-Eq402-Debug-Has-Auth: false');
+			}
+		}
+
+		// Always send 402 — no ai_score check
+		$this->send_402($canonical_url, 100, $options);
+		exit;
+	}
+
+	/**
+	 * Render the /eq402 congratulations page after successful payment.
+	 */
+	private function render_eq402_success(array $grant_payload, array $options): void {
+		$amount   = $options['pay_price'] ?? '0.10';
+		$currency = $options['pay_currency'] ?? 'USDC';
+		$ttl      = (int) ($options['pay_grant_ttl'] ?? 900);
+		$exp      = (int) ($grant_payload['exp'] ?? 0);
+		$url      = $grant_payload['url'] ?? '';
+
+		// Reconstruct token prefix for display (truncated)
+		$req_id = $grant_payload['req_id'] ?? '';
+
+		status_header(200);
+		nocache_headers();
+		header('Content-Type: text/html; charset=utf-8');
+
+		$expires_at = gmdate('c', $exp);
+		?>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>eq402 — Payment Verified</title>
+	<style>
+		body { font-family: monospace; max-width: 600px; margin: 40px auto; padding: 0 20px; color: #222; }
+		h1 { color: #2e7d32; }
+		dl { line-height: 1.8; }
+		dt { font-weight: bold; }
+		dd { margin-left: 20px; }
+	</style>
+</head>
+<body>
+	<h1>Congratulations!</h1>
+	<p>You successfully paid to access this page via the Baskerville x402 paywall.</p>
+	<dl>
+		<dt>Amount paid</dt>
+		<dd><?php echo esc_html($amount . ' ' . $currency); ?></dd>
+		<dt>Grant TTL</dt>
+		<dd><?php echo esc_html($ttl); ?> seconds</dd>
+		<dt>Expires at</dt>
+		<dd><?php echo esc_html($expires_at); ?></dd>
+		<dt>Request ID</dt>
+		<dd><?php echo esc_html($req_id); ?></dd>
+		<dt>Canonical URL</dt>
+		<dd><?php echo esc_html($url); ?></dd>
+	</dl>
+</body>
+</html>
+		<?php
+	}
+
+	/**
+	 * Main paywall check — hooked to template_redirect at priority 1.
+	 */
+	public function check_paywall(): void {
+		$options = get_option('baskerville_settings', []);
+
+		// 1. Quick exits
+		$pay_enabled = !empty($options['pay_enabled']);
+		$pay_mode    = $options['pay_mode'] ?? 'off';
+		if (!$pay_enabled || $pay_mode === 'off' || $pay_mode === 'test') {
+			return;
+		}
+
+		$method = strtoupper(sanitize_text_field(wp_unslash($_SERVER['REQUEST_METHOD'] ?? 'GET')));
+		if (!in_array($method, ['GET', 'HEAD'], true)) {
+			return;
+		}
+
+		if (is_user_logged_in()) {
+			return;
+		}
+
+		if (is_admin() || (defined('REST_REQUEST') && REST_REQUEST) || wp_doing_ajax()) {
+			return;
+		}
+
+		// 2. Check path against protected_paths
+		$uri = sanitize_text_field(wp_unslash($_SERVER['REQUEST_URI'] ?? '/'));
+		$path = wp_parse_url($uri, PHP_URL_PATH) ?: '/';
+
+		if (!$this->path_matches($path, $options)) {
+			return;
+		}
+
+		// 3. Check grant token (Authorization header, ?grant= query param, or cookie)
+		$canonical_url = $this->canonical_url();
+		$grant_token   = $this->get_grant_token();
+
+		if ($grant_token) {
+			$payload = $this->grant->validate($grant_token, $canonical_url, $method);
+			if ($payload !== null) {
+				return; // Valid grant — allow access
+			}
+		}
+
+		// 4. Get ai_score
+		$ai_score = $this->get_ai_score();
+
+		// 5. Check threshold
+		$threshold = (int) ($options['pay_ai_threshold'] ?? 70);
+		if ($ai_score < $threshold) {
+			return;
+		}
+
+		// 6. Observe mode — add header but don't block
+		if ($pay_mode === 'observe') {
+			if (!headers_sent()) {
+				header('Baskerville-Paywall: would-402');
+			}
+			return;
+		}
+
+		// 7. Enforce mode — generate challenge and return 402
+		if ($pay_mode === 'enforce') {
+			$this->send_402($canonical_url, $ai_score, $options);
+			exit;
+		}
+	}
+
+	/**
+	 * Check if request path matches any protected path pattern.
+	 */
+	private function path_matches(string $path, array $options): bool {
+		$patterns_raw = $options['pay_protected_paths'] ?? '/*';
+		$lines = array_filter(array_map('trim', explode("\n", $patterns_raw)));
+
+		if (empty($lines)) {
+			return true; // No patterns = match all
+		}
+
+		foreach ($lines as $pattern) {
+			if (fnmatch($pattern, $path)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Extract grant token from Authorization header, query param, or cookie.
+	 *
+	 * Checks in order:
+	 * 1. Authorization: Bearer BV1.xxx header
+	 * 2. ?grant=BV1.xxx query parameter (CDN-friendly: unique URL bypasses cache)
+	 * 3. baskerville_grant cookie (set by verify endpoint)
+	 */
+	private function get_grant_token(): ?string {
+		// 1. Authorization: Bearer header
+		$auth = isset($_SERVER['HTTP_AUTHORIZATION'])
+			? sanitize_text_field(wp_unslash($_SERVER['HTTP_AUTHORIZATION']))
+			: '';
+
+		// Fallback for CGI/FastCGI
+		if (!$auth && isset($_SERVER['REDIRECT_HTTP_AUTHORIZATION'])) {
+			$auth = sanitize_text_field(wp_unslash($_SERVER['REDIRECT_HTTP_AUTHORIZATION']));
+		}
+
+		if ($auth && stripos($auth, 'Bearer ') === 0) {
+			$token = trim(substr($auth, 7));
+			if (strpos($token, 'BV1.') === 0) {
+				return $token;
+			}
+		}
+
+		// 2. Query parameter ?grant=BV1.xxx (CDN cache-bust)
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
+		if (isset($_GET['grant'])) {
+			// phpcs:ignore WordPress.Security.NonceVerification.Recommended
+			$token = sanitize_text_field(wp_unslash($_GET['grant']));
+			if (strpos($token, 'BV1.') === 0) {
+				return $token;
+			}
+		}
+
+		// 3. Cookie fallback
+		if (isset($_COOKIE['baskerville_grant'])) {
+			$token = sanitize_text_field(wp_unslash($_COOKIE['baskerville_grant']));
+			if (strpos($token, 'BV1.') === 0) {
+				return $token;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Extract Bearer token from Authorization header.
+	 *
+	 * @deprecated Use get_grant_token() instead.
+	 */
+	private function get_auth_header(): ?string {
+		return $this->get_grant_token();
+	}
+
+	/**
+	 * Compute AI score for the current request.
+	 */
+	private function get_ai_score(): int {
+		$headers = [
+			'user_agent'      => sanitize_text_field(wp_unslash($_SERVER['HTTP_USER_AGENT'] ?? '')),
+			'accept'          => sanitize_text_field(wp_unslash($_SERVER['HTTP_ACCEPT'] ?? '')),
+			'accept_language' => sanitize_text_field(wp_unslash($_SERVER['HTTP_ACCEPT_LANGUAGE'] ?? '')),
+			'accept_encoding' => sanitize_text_field(wp_unslash($_SERVER['HTTP_ACCEPT_ENCODING'] ?? '')),
+			'connection'      => sanitize_text_field(wp_unslash($_SERVER['HTTP_CONNECTION'] ?? '')),
+			'remote_addr'     => sanitize_text_field(wp_unslash($_SERVER['REMOTE_ADDR'] ?? '')),
+		];
+
+		// Score from server-side headers (no JS fingerprint)
+		$evaluation = $this->aiua->baskerville_score_fp(['fingerprint' => []], ['headers' => $headers]);
+		$score = (int) ($evaluation['score'] ?? 0);
+
+		// Also check if there's a FP cookie score (take max)
+		$fp_data = $this->core->read_fp_cookie();
+		if ($fp_data !== null) {
+			$fp_score = (int) ($fp_data['sc'] ?? 0);
+			$score = max($score, $fp_score);
+		}
+
+		return $score;
+	}
+
+	/**
+	 * Build the canonical URL for the current request.
+	 */
+	private function canonical_url(): string {
+		$scheme = (is_ssl() || (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https'))
+			? 'https' : 'http';
+		$host = sanitize_text_field(wp_unslash($_SERVER['HTTP_HOST'] ?? 'localhost'));
+		$uri  = sanitize_text_field(wp_unslash($_SERVER['REQUEST_URI'] ?? '/'));
+		$path = wp_parse_url($uri, PHP_URL_PATH) ?: '/';
+
+		return $scheme . '://' . $host . $path;
+	}
+
+	/**
+	 * Generate 402 response with challenge.
+	 */
+	private function send_402(string $canonical_url, int $ai_score, array $options): void {
+		$nonce     = $this->core->b64u_enc(random_bytes(16));
+		$day       = wp_date('Y-m-d');
+		$origin    = home_url();
+		$req_id    = $this->core->b64u_enc(
+			hash('sha256', $origin . '|' . $canonical_url . '|' . $day . '|' . $nonce, true)
+		);
+
+		$price           = $options['pay_price'] ?? '0.10';
+		$currency        = $options['pay_currency'] ?? 'USDC';
+		$network         = $options['pay_network'] ?? 'polygon';
+		$wallet          = $options['pay_wallet_address'] ?? '';
+		$asset_type      = $options['pay_asset_type'] ?? 'erc20';
+		$token_contract  = $options['pay_token_contract'] ?? '';
+		$token_decimals  = (int) ($options['pay_token_decimals'] ?? 6);
+		$grant_ttl       = (int) ($options['pay_grant_ttl'] ?? 900);
+		$ip              = sanitize_text_field(wp_unslash($_SERVER['REMOTE_ADDR'] ?? ''));
+
+		// Store challenge
+		$this->storage->insert_challenge([
+			'req_id'         => $req_id,
+			'canonical_url'  => $canonical_url,
+			'price'          => $price,
+			'currency'       => $currency,
+			'network'        => $network,
+			'wallet_address' => $wallet,
+			'asset_type'     => $asset_type,
+			'token_contract' => $token_contract,
+			'token_decimals' => $token_decimals,
+			'ai_score'       => $ai_score,
+			'ip'             => $ip,
+			'nonce'          => $nonce,
+		]);
+
+		// Build response
+		$proof_endpoint = rest_url('baskerville/v1/payments/verify');
+
+		$body = [
+			'error'            => 'payment_required',
+			'req_id'           => $req_id,
+			'amount'           => $price,
+			'currency'         => $currency,
+			'network'          => $network,
+			'wallet'           => $wallet,
+			'asset_type'       => $asset_type,
+			'proof_endpoint'   => $proof_endpoint,
+			'grant_ttl_seconds' => $grant_ttl,
+		];
+
+		if ($asset_type === 'erc20' && $token_contract) {
+			$body['token_contract'] = $token_contract;
+			$body['token_decimals'] = $token_decimals;
+		}
+
+		// Send headers — no-store is stronger than nocache_headers() for CDN bypass
+		status_header(402);
+		nocache_headers();
+		header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0', true);
+		header('Vary: Authorization, Cookie', false);
+		header('Content-Type: application/json');
+		header('Baskerville-Pay: required');
+		header('Baskerville-Req-Id: ' . $req_id);
+		header('Baskerville-Price: ' . $price);
+		header('Baskerville-Currency: ' . $currency);
+		header('Baskerville-Network: ' . $network);
+		header('Baskerville-Wallet: ' . $wallet);
+		header('Baskerville-Asset-Type: ' . $asset_type);
+		if ($asset_type === 'erc20' && $token_contract) {
+			header('Baskerville-Token-Contract: ' . $token_contract);
+		}
+		header('Baskerville-Proof-Endpoint: ' . $proof_endpoint);
+		header('Baskerville-Grant-TTL: ' . $grant_ttl);
+		header('Baskerville-Reason: ai_score=' . $ai_score . ';policy=paywall');
+
+		echo wp_json_encode($body);
+	}
+}