Quickstart

Run the Sol402 paywall in five minutes

Provision a paywalled link, return an HTTP 402 challenge, and let PayAI handle settlement. These steps mirror what ships in the repository today.

Launch the builder Read API reference Inspect dashboard
  • Runtime: Cloudflare Workers · Hono
  • Payments: PayAI facilitator · Solana USDC
  • Analytics: ClickHouse + Grafana exporters

Four steps to production

This mirrors the automation path built into sol402.app. Follow the steps manually, or connect your wallet and let the builder mint everything for you.

01

Provision

POST to /admin/links with your origin URL, price in USD, and merchant wallet. The response includes the public link ID and a scoped admin key.

  • Supports JSON, file URLs, HTML, API endpoints
  • Scoped admin key is tied to your merchant wallet
02

Integrate

Serve the 402 challenge from /p/:id. Your client (browser, agent, script) redirects to PayAI, collects the payment, and retries with X-PAYMENT.

  • Headers include X-PAYMENT-REQUIREMENTS for invoice details
  • Works with PayAI facilitator UI or programmatic clients
03

Observe

Every successful request emits analytics events to ClickHouse. The dashboard shows revenue, conversion, referrers, and recent payments within ~60 seconds.

  • Events: link_paid_call, link_free_call
  • KV → ClickHouse export runs via Worker cron
04

Scale

Use the admin API to rotate keys, adjust pricing, or update link metadata. Premium tiers unlock webhook dispatch and direct ClickHouse sync.

  • PATCH endpoints to edit price and quotas
  • Roadmap: automated webhooks + revenue exports

Resources & reference

Dive deeper into architecture, scripts, and troubleshooting. These links map to the canonical docs in this repository.

Architecture overview README

Understand the Worker, paywall middleware, analytics pipeline, and deployment targets.
Self-serve link flow Guide

See how wallet balances, tiers, and admin keys provisioned through the builder connect.
Analytics dashboard Spec

Metrics schema, ClickHouse queries, and dashboard widgets powering the /dashboard route.
Support Email

Contact us for high-volume pricing, premium tier unlocks, or partnership requests.

Integration FAQ

Answers to the questions teams ask before shipping the paywall.

How do I test without spending real USDC? ➜

Point SOLANA_RPC_URL at devnet and use FREE_CALLS_PER_WALLET_PER_DAY to simulate quota. You can also set SETTLE_WITH_PAYAI=false for full local flows.

Can I bring my own facilitator or paywall UI? ➜

Yes. The 402 response includes a standard paymentRequirements payload. You can implement your own client as long as it posts a valid receipt in X-PAYMENT.

What happens if the RPC provider flakes? ➜

The token service retries with exponential backoff and emits metrics to Grafana via the RPC_METRICS_URL endpoint. Premium tiers also get priority RPC pools.

How do merchants rotate admin keys? ➜

Call POST /admin/keys/rotate with your current key. The dashboard will surface a downloadable copy and invalidate the previous secret instantly.