Metadata-Version: 2.4
Name: solinkify-gate
Version: 0.3.0
Summary: Solinkify Gate for Python — block AI scrapers with an HTTP 402 paywall, monetize ethical AI agents on Solana. WSGI (Django/Flask) + ASGI (FastAPI/Starlette) middleware.
Author: Solinkify
License: MIT
Project-URL: Homepage, https://solinkify.com/gate
Keywords: solana,solinkify,ai,paywall,402,middleware,django,flask,fastapi
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# solinkify-gate (Python)

Solinkify Gate for Python — block AI scrapers with an **HTTP 402** paywall
(manifest aligned with the **x402** standard) and monetize ethical AI agents on
Solana. A port of `@solinkify/gate` (JS). **Zero dependencies** (stdlib only).

Works with: **Flask · Django · FastAPI · Starlette · Bottle · Pyramid · Quart**
(anything WSGI/ASGI).

## Install

```bash
pip install solinkify-gate
```

## 1. Register your endpoint (once)

Open `https://solinkify.com/gate/setup`, connect a wallet, register an
`endpoint_id` + a price per request (USDC).

## 2. Add the middleware (1-paste)

### Flask / any WSGI

```python
from solinkify_gate import GateConfig
from solinkify_gate.wsgi import SolinkifyGateMiddleware

app.wsgi_app = SolinkifyGateMiddleware(app.wsgi_app, GateConfig(
    wallet="<CREATOR_WALLET>",
    price=0.001,                 # USDC per request
    endpoint_id="my-site",
))
```

### Django (`project/wsgi.py`)

```python
from django.core.wsgi import get_wsgi_application
from solinkify_gate import GateConfig
from solinkify_gate.wsgi import SolinkifyGateMiddleware

application = SolinkifyGateMiddleware(get_wsgi_application(), GateConfig(
    wallet="<CREATOR_WALLET>", price=0.001, endpoint_id="my-site",
))
```

### FastAPI / Starlette (ASGI)

```python
from solinkify_gate import GateConfig
from solinkify_gate.asgi import SolinkifyGateMiddleware

app.add_middleware(SolinkifyGateMiddleware, config=GateConfig(
    wallet="<CREATOR_WALLET>", price=0.001, endpoint_id="my-site",
))
```

Done. AI scrapers (GPTBot, ClaudeBot, PerplexityBot, and 40+ others) get a
**402 + payment manifest**; humans & search engines (Googlebot/Bingbot) pass
through normally (SEO-safe by default); ethical agents pay via Solana escrow
and are verified on-chain.

## Configuration (`GateConfig`)

| Field | Default | Description |
|---|---|---|
| `wallet` | — | Creator wallet (required) |
| `price` | — | Price per request, token units (required) |
| `endpoint_id` | `""` | On-chain endpoint from setup |
| `token_mint` | USDC mainnet | Settlement stablecoin mint |
| `api_url` | `https://api.solinkify.com` | Verification backend |
| `protected_paths` | `["/*"]` | Glob: exact, `/*`, `/prefix/*` |
| `exclude_paths` | `[]` | Always let through |
| `detection` | `"basic"` | `"basic"` (SEO-safe) / `"strict"` |
| `allow_bots` | `[]` | Bot-name whitelist (e.g. `["Googlebot"]`) |
| `free_requests` | `0` | Freemium: N free requests per client per day |
| `tiers` | `[]` | `GateTier(pattern, endpoint_id, price)` per-path pricing |
| `license` | `None` | `{"url","terms","attribution"}` → manifest + discovery |
| `analytics` | `True` | Ping the analytics dashboard (fire-and-forget) |
| `trust_proxy` | `True` | Trust `x-forwarded-for`/`x-real-ip`; set `False` when the app takes direct connections |
| `verify_bot_ips` | `True` | Verify the client IP against the bot's official ranges (Google/Bing). A "Googlebot" from a fake IP → paywall; unverifiable → normal behaviour (safe) |

## Parity with the JS SDK

- 402 manifest **aligned with x402** (`x402Version`, `accepts[]`) + backward-compat.
- Automatic **`/.well-known/solinkify`** discovery document.
- Tiered/per-path pricing, freemium metering (fail-closed), analytics ping.
- **Bot IP verification** (`verify_bot_ips`): an impostor "Googlebot" from a
  non-Google IP never gets the SEO free-pass — parity with the JS core.
- **Pre-paid & subscription** (no per-request tx): the manifest/discovery
  advertise `access_modes`; an agent with `x-solinkify-payer` +
  `x-solinkify-prepaid` headers (the backend debits its on-chain balance,
  fail-closed) or `x-solinkify-subscription` (while unexpired) is let through
  automatically — no extra middleware config.
- Fail-open: a Gate bug never takes the creator's site down.

**Note:** the more aggressive `strict+` anti-abuse layers (headless-browser
heuristics, datacenter-IP blocking) are for now only in the JS SDK
`@solinkify/gate`.

## License

MIT
