Primer Pay for WordPress

Monetize any WordPress post or page with x402 micropayments. Add a Content Gate block, set a price, publish. Readers with a compatible x402 browser extension unlock content instantly — everyone else sees a teaser with an install prompt.

How it works

1. You add a Primer Pay Content Gate block to a post and set a price (e.g. $0.01 USDC).
2. A reader visits the post. WordPress serves the teaser and a small unlock container.
3. Our JavaScript fires a fetch to the plugin's REST endpoint.
4. If the reader has a compatible x402 browser extension, it intercepts the 402 response, signs a USDC payment, and retries transparently.
5. The plugin validates the payment via the Primer facilitator, sets an HMAC-signed access cookie, and returns the unlocked content.
6. Subsequent visits are served from the cookie — no re-payment on refresh.

Readers without a compatible extension see a teaser with a prompt explaining how to access the content.

Install

Requirements

• WordPress 5.8+ and PHP 7.4+
• A wallet address that can receive USDC payments on Base or SKALE Base (MetaMask, Coinbase Wallet, or the Primer Pay extension itself all work — same address works on all supported networks)
• HTTPS recommended — cookies are marked Secure on HTTPS sites; HTTP still works for local development

Setup

1. Install the plugin from the zip download above and activate it.
2. Go to Settings → Primer Pay and enter your wallet address.
3. Optionally adjust the default price, Access Duration, and Accepted Networks (Base, SKALE Base, or both — with a preferred-network priority).
4. Edit any post and add the Primer Pay Content Gate block where you want the teaser to end. Configure price, access duration, and wallet override in the block sidebar.

Block editor (Gutenberg)

Add the Primer Pay Content Gate block anywhere in your post. Everything above it is the free teaser; everything below is the paid content. The block sidebar includes:

• Enable Paywall — toggle on/off without deleting the block
• Price (USDC) — per-post override, or leave blank for the site default
• Access Duration — how long the reader retains access after paying
• Payment Wallet — optional per-post wallet override for multi-author sites

Classic editor

Add the [primer_pay_x402] shortcode anywhere in your post content:

This is the free preview everyone sees.

[primer_pay_x402]

This is the paid content only visitors who pay can read.

Configure paywall settings in the Primer Pay meta box in the sidebar. If you don't add a Content Gate block or shortcode, the plugin falls back to the post's excerpt as the teaser.

Agent discovery

The plugin serves a machine-readable JSON index of all paywalled content at /.well-known/x402. AI agents, crawlers, and other x402-aware clients can discover purchasable content without browsing the site:

GET https://yoursite.com/.well-known/x402

Returns titles, URLs, prices, networks, and wallet addresses for all paywalled posts. The response includes the site's enabled networks and preferred network. Results are cached for 5 minutes.

Readers: how to pay

Install a compatible x402 browser extension, fund it with USDC on Base, and browse normally. Paywalled content unlocks automatically — no logins, no forms, no checkout flow.

Supported networks

Enable one or both in Settings → Primer Pay → Accepted Networks. When both are enabled, the preferred network is offered first; if the reader can't pay on it, the next is tried automatically. The same wallet address works on all networks.

Architecture highlights

REST-based unlock flow

Unlike naive x402 paywalls that return 402 on top-level navigation, Primer Pay serves paywalled posts as normal 200 OK pages and runs the x402 exchange via a background fetch() to a REST endpoint. This is compatible with:

• Hosts that insert interstitials or consent banners between the browser and the origin
• CDN bot-protection layers (Cloudflare, etc.)
• Browser content-script sandboxing (which blocks inline scripts in document.write-delivered content)
• Session cookies on unlock (which are discarded by the extension's navigation-path retry)

Theme-matching paywall banner

The paywall banner inherits fonts, colors, and border radius from the active WordPress theme via CSS custom properties (--wp--preset--*). No configuration needed — the banner looks native on any site.

HMAC-signed access cookies

After a successful payment, the plugin sets an HttpOnly, HMAC-signed cookie scoped to that specific post. Subsequent visits within the configured duration skip the x402 dance entirely and serve the content directly. Cookies are:

• HMAC-SHA256 signed with a site-specific secret stored non-autoloaded in wp_options
• HttpOnly — not readable by JavaScript, preventing XSS exfiltration
• SameSite=Lax
• Verified in constant time via hash_equals()

Non-custodial

The plugin never handles private keys or funds. The merchant provides only a receive address; signing happens entirely in the reader's browser extension. Settlement happens through the Primer facilitator, which charges nothing for Base network transactions.

Planned

• Earnings dashboard and payment history export
• MCP server for AI agent integration (search, preview, and purchase content programmatically)
• WooCommerce integration for digital downloads
• SIWX wallet identity for cross-post access passes
• REST API and media-file gating for headless WordPress and gated downloads

Support

Issues and pull requests welcome at github.com/primer-systems/primer-pay-wordpress. For direct contact, email dev@primer.systems.