@solinkify/gate

@solinkify/gate

A toll booth between AI scrapers and your content. Add one middleware — mainstream AI crawlers (ChatGPT / Claude / Perplexity) get an x402-aligned HTTP 402 paywall, while ethical AI agents auto-pay USDC on Solana to get in.

• 🛡️ AI bot detection via User-Agent (OpenAI, Anthropic, Perplexity, Google, and more)
• 💸 Stablecoin (USDC) payments into an on-chain escrow — 99% goes to the creator
• ⚡ Adapters for Next.js, Express/Node, Cloudflare Workers, Astro, SvelteKit, Hono, Nuxt, Remix, Fastify, Lambda@Edge, and any Fetch runtime (one core, many frameworks)

Install

npm install @solinkify/gate
# or: pnpm add @solinkify/gate

Peer dependency: Next.js ≥ 14 (optional — only for the Next.js adapter; Express & Workers don't need Next).

1. Register your endpoint (once)

Open solinkify.com/gate/setup → connect a wallet → register an endpoint (you get an endpointId + a price per request). This is what binds payments to your content on-chain.

2. Add the middleware (1-paste)

Create middleware.ts at the root of your Next.js project:

import { protectFromAI } from '@solinkify/gate';

export const middleware = protectFromAI({
  wallet: 'YOUR_CREATOR_WALLET',   // Solana wallet that receives 99%
  price: 0.001,                    // price per request (USDC)
  endpointId: 'my-blog',           // from step 1
});

export const config = {
  matcher: '/:path*',              // run on every route (scope with protectedPaths)
};

Done. Requests from AI scrapers → 402 + paywall message; regular visitors & browsers → pass through untouched.

Configuration (GateConfig)

Option	Required	Default	Description
wallet	✅	—	Creator's Solana wallet (receives 99%)
price	✅	—	Price per request (token units, e.g. 0.001 USDC)
endpointId	⚠️	''	On-chain endpoint id (step 1) — required so payments bind to your endpoint
tokenMint		USDC mainnet	Settlement SPL mint (override for devnet)
apiUrl		https://api.solinkify.com	Verification API
protectedPaths		['/*']	Paths to protect (glob: /articles/*)
excludePaths		[]	Paths always let through
detection		'basic'	'basic' (block AI, SEO-safe) · 'strict' (also block search engines) · 'strict+' (aggressive: inspect browser UAs for headless/scraper signals)
blockDatacenterIps		false	strict+ only: block browser-UA requests from datacenter IPs (AWS/GCP/…). Opt-in (may hit legitimate VPN users).
allowBots		[]	Bot whitelist (e.g. ['Googlebot']) to protect SEO
verifyBotIps		true	Verify the client IP against the bot's official published ranges (Google/Bing). A "Googlebot" from a fake IP → blocked (closes the spoofing hole). Needs the adapter to supply an IP; when unverifiable → normal behaviour (safe).
trustProxy		true	Trust x-forwarded-for/x-real-ip as the client IP. Correct behind Vercel/Cloudflare/nginx (which OVERWRITE the header). ⚠️ Set false if your app takes connections STRAIGHT from the internet — a direct client can forge XFF to bypass verify-IP/rate-limit/datacenter checks; with false only the socket IP is used.
customMessage		—	Custom paywall message

Devnet vs mainnet (switch-ready)

Default = mainnet USDC. To test on devnet, override:

protectFromAI({
  wallet: 'YOUR_WALLET',
  price: 0.001,
  endpointId: 'my-blog',
  tokenMint: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU', // USDC devnet
});

Express / Node

import express from 'express';
import { protectFromAIExpress } from '@solinkify/gate/express';

const app = express();

app.use(protectFromAIExpress({
  wallet: 'YOUR_CREATOR_WALLET',
  price: 0.001,
  endpointId: 'my-blog',
}));

app.get('/articles/:id', (req, res) => {
  // req.solinkify = { verified, botName } is set for agents that paid
  res.send('Protected content');
});

Same GateConfig as Next.js. This adapter is zero-dependency (duck-typed req/res) — compatible with Express & Connect, no @types/express needed. If the middleware itself hits an unexpected error, the request fails open (passes) so your site never goes down because of the gate.

Astro / SvelteKit / Hono

// Astro — src/middleware.ts
import { createAstroGate } from '@solinkify/gate/astro';
export const onRequest = createAstroGate({ wallet, endpointId, price: 0.001 });

// SvelteKit — src/hooks.server.ts
import { createSvelteKitGate } from '@solinkify/gate/sveltekit';
export const handle = createSvelteKitGate({ wallet, endpointId, price: 0.001 });

// Hono (Workers/Deno/Bun/Node/edge)
import { createHonoGate } from '@solinkify/gate/hono';
app.use('/articles/*', createHonoGate({ wallet, endpointId, price: 0.001 }));

Nuxt / Remix

// Nuxt (Nitro) — server/middleware/solinkify.ts
import { createNuxtGate } from '@solinkify/gate/nuxt';
export default createNuxtGate({ wallet, endpointId, price: 0.001 });

// Remix / React Router — app/root.tsx
import { createRemixGate } from '@solinkify/gate/remix';
const gate = createRemixGate({ wallet, endpointId, price: 0.001 });
export async function loader({ request }) {
  await gate(request);         // throws a 402 Response for unpaid AI scrapers
  return json({ /* ... */ });
}

Fastify

import Fastify from 'fastify';
import { createFastifyGate } from '@solinkify/gate/fastify';

const app = Fastify();
app.addHook('onRequest', createFastifyGate({ wallet, endpointId, price: 0.001 }));

Any other Fetch runtime (Deno / Bun / edge) — guardFetch

Any handler with a Web Request can gate in ~5 lines:

import { resolveConfig } from '@solinkify/gate/core';
import { guardFetch } from '@solinkify/gate/fetch';
const gate = resolveConfig({ wallet, endpointId, price: 0.001 });

// Deno
Deno.serve((req) => guardFetch(req, gate, () => new Response('protected content')));

// Bun
Bun.serve({ fetch: (req) => guardFetch(req, gate, () => new Response('protected content')) });

// Vercel Edge / Netlify Edge Functions / Fastly Compute (JS) — same signature:
export default (req: Request) => guardFetch(req, gate, () => fetch(req));

AWS CloudFront (Lambda@Edge)

Gate ANY origin (S3 static site, ALB, legacy server) without touching its code — attach to the viewer-request event:

// index.mjs — Lambda@Edge (region us-east-1)
import { createLambdaEdgeGate } from '@solinkify/gate/lambda-edge';
export const handler = createLambdaEdgeGate({ wallet, endpointId, price: 0.001 });

Cloudflare Workers

import { createWorkerHandler } from '@solinkify/gate/worker';
export default { fetch: createWorkerHandler() };

Configure via environment variables (SOLINKIFY_WALLET, SOLINKIFY_PRICE, SOLINKIFY_ENDPOINT_ID, …). See src/worker.ts.

Build your own adapter (framework-agnostic core)

Every adapter is built on one dependency-free core:

import { resolveConfig, evaluateGate } from '@solinkify/gate/core';

const cfg = resolveConfig({ wallet, price: 0.001, endpointId: 'my-blog' });
const result = await evaluateGate(
  { pathname, userAgent, paymentId, payerPubkey },
  cfg,
);
// result.action === 'block' → send 402 (result.manifest + result.headers)
// result.action === 'next'  → pass through (result.verified carries metadata)

Tiered pricing & multi-stablecoin

Different prices per path (each tier binds to its own on-chain endpoint) + pick your stablecoin:

import { protectFromAI } from '@solinkify/gate';
import { stablecoinMint } from '@solinkify/gate';

export const middleware = protectFromAI({
  wallet: 'YOUR_WALLET',
  endpointId: 'standard',           // default for other paths
  price: 0.001,
  tokenMint: stablecoinMint('USDC'),     // or 'USDT' | 'PYUSD'
  protectedPaths: ['/articles/*', '/premium/*'],
  tiers: [
    { pattern: '/premium/*', endpointId: 'premium', price: 0.01 }, // premium costs more
  ],
});

The first matching tier wins; no match → the top-level endpointId/price/tokenMint apply. Agents pay — and are verified — against that same tier's endpoint + price. Register each endpointId on-chain (one per tier). stablecoinMint(symbol, 'devnet'|'mainnet') saves you memorizing mint addresses.

Anti-abuse layers 4–5 (opt-in): JS challenge (PoW) + rate limiting

For scrapers whose UA is honest but NOT a known bot (curl, python, HTTP libraries) and for bulk scraping:

protectFromAI({
  wallet, endpointId, price: 0.001,
  challenge: true,               // Layer 4: JS proof-of-work interstitial
  challengeSecret: process.env.GATE_CHALLENGE_SECRET, // REQUIRED for multi-instance
  rateLimit: { max: 120, windowSecs: 60 },            // Layer 5: per-IP rate anomaly
});

• challenge — all non-bot traffic must pass a PoW page once per hour (HMAC clearance cookie, bound to IP + expiry). Real browsers clear it in ±1 second; non-browsers never do. Known AI bots STILL get the 402 (they're the monetization target); robots.txt/sitemap/discovery are never challenged. ⚠️ Aggressive — humans see a brief splash on first visit.
• rateLimit — above the threshold → 402 paywall. Fails open: a rate backend outage never blocks humans.

Pre-paid balance & subscriptions (no per-request transaction)

Besides pay-per-request, agents get two access modes that need no transaction per request — both work automatically, zero extra middleware config:

• Pre-paid — the agent deposits stablecoin once into its own on-chain balance, then sends x-solinkify-payer + x-solinkify-prepaid headers. The Solinkify backend debits exactly your endpoint's price per request (fail-closed, on-chain split, 99% still yours) — it shows up in your dashboard like any payment.
• Subscription — you attach a plan per endpoint (price × duration) from the dashboard → Manage Endpoints panel. The agent pays once (subscribe, 99% straight to you) then accesses with the x-solinkify-subscription header until the plan expires.

The 402 manifest and /.well-known/solinkify advertise both via the access_modes field, so ethical agents discover them on their own. Agent side: see @solinkify/gate-sdk (depositPrepaid, subscribe, and a GateClient that automatically uses the prepaid balance when it covers the price).

Edit prices, enable/disable endpoints, and manage subscription plans — all from the Manage Endpoints panel, no CLI required.

SEO-safe by default (+ robots.txt)

The two-tier detector protects your SEO:

• All AI gets blocked (402): GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot, Gemini/Vertex, Meta AI, CCBot, Bytespider, DeepSeek, and more — plus AI-search & agent tooling (Firecrawl, etc.).
• Traditional search engines always pass (default basic mode): Googlebot, bingbot, Baidu, Yandex, PetalBot → ranking & indexing untouched.
• /robots.txt & /sitemap*.xml are always crawlable (never 402'd).

⚠️ detection: 'strict' also blocks Googlebot/bingbot → hurts SEO. The SDK emits a console.warn; if you truly need strict, whitelist search engines: allowBots: ['Googlebot', 'Bingbot'].

Google/Apple AI can't be blocked via User-Agent (Googlebot & Applebot serve search + AI from the same UA). Opt out of their AI training via robots.txt (Google-Extended, Applebot-Extended) — without hurting search. The generator is included:

// app/robots.ts (Next.js)
import { generateRobotsTxt } from '@solinkify/gate/robots';

export function GET() {
  return new Response(
    generateRobotsTxt({ sitemap: 'https://example.com/sitemap.xml' }),
    { headers: { 'Content-Type': 'text/plain' } },
  );
}

Result: every robots.txt-respecting AI crawler gets Disallow, while User-agent: * stays Allow: /. Layered defense = the 402 gate (UA) + robots.txt (declarative).

How it works (the 402 flow)

• An AI scraper sends a request → the middleware detects the bot User-Agent.
• It answers HTTP 402 + a payment manifest (escrow_address, payment_id, endpoint_id, token_mint).
• Mainstream AI shows a "content is protected" message (it can't pay — intended).
• An ethical AI agent (using @solinkify/gate-sdk) → auto-pays into escrow → retries with proof → gets the content. Agents with a pre-paid balance / active subscription skip the payment step entirely (see above).
• Escrow release: 99% creator, the rest is the protocol fee (enforced on-chain).

Track earnings

Real-time at solinkify.com/gate/earnings.

License

MIT © Solinkify