Jak działa CrawlPay, krok po kroku.
Kompletny przewodnik po platformie: od pierwszego żądania HTTP i odpowiedzi 402, przez podpis płatności i settlement, po podział przychodu prosto na Twój portfel. Bez skrótów — każdy element wyjaśniony.
Wielki obraz: bramka między klientem a Twoją treścią
CrawlPay to warstwa płatności, która staje przed Twoim serwerem. Zamiast blokować boty albo oddawać treść za darmo, mówisz: ta trasa kosztuje tyle-a-tyle. Kto zapłaci — wchodzi. Kto nie — dostaje kod 402 Payment Required z maszynową instrukcją, jak zapłacić.
Gateway
Bramka przed Twoim serwerem (originem). Rozpoznaje, kto puka — człowiek, zweryfikowany bot czy agent AI — egzekwuje cennik, odrzuca nadużycia, weryfikuje płatności i dopiero potem przepuszcza żądanie dalej.
Konsola
Panel wydawcy. Tu tworzysz aplikację (domenę), cennik i trasy, wybierasz kto płaci, konfigurujesz plany przepustek, klucze API i rejestrację w kontrakcie, oglądasz ruch i przychód na żywo.
Facilitator
Kryptograficzne zaplecze płatności. Odzyskuje sygnatariusza z podpisu EIP-712, sprawdza kwotę, odbiorcę i okno ważności, pilnuje jednorazowości nonce i rozlicza transfer USDC.
Strona płacącego
Człowiek płaci widgetem w przeglądarce, agent AI — serwerem MCP albo funkcją payFetch z SDK. W każdym wariancie klucz prywatny podpisuje lokalnie i nigdy nie opuszcza urządzenia płacącego.
klient (człowiek / bot / agent AI) │ ▼ GATEWAY ← cennik, klasyfikacja, anty-abuse │ ├──► FACILITATOR weryfikacja podpisu + settlement ├──► KONSOLA config, księga przychodów (raportowanie) ▼ ORIGIN Twój serwer — dostaje tylko opłacone żądania
Twój serwer (origin) nie musi wiedzieć nic o płatnościach — gateway dostarcza mu już tylko opłacone żądania. Możesz też trzymać egzekwowanie u siebie: wtyczka WordPress albo middleware SDK pytają gateway o decyzję dla każdego żądania.
Cykl życia płatności: od 402 do treści
x402 to otwarty protokół mikropłatności HTTP zbudowany wokół kodu statusu 402 Payment Required. Poniżej pełny cykl życia jednego płatnego żądania — dokładnie to dzieje się w tle, gdy agent AI pobiera Twoją treść.
Żądanie bez płatności
Klient prosi o chronioną trasę. Gateway dopasowuje ją do Twojego cennika i klasyfikuje klienta (segment ruchu). Jeśli ten segment ma płacić — zamiast treści wraca odpowiedź 402.
# agent AI prosi o chronioną trasę: curl -i -A "GPTBot/1.0" https://twoja-strona.pl/api/dane HTTP/1.1 402 Payment Required
Challenge 402 — maszynowa instrukcja zapłaty
Odpowiedź niesie JSON z tablicą accepts: ile zapłacić (maxAmountRequired — kwota w „mikro” USDC, 6 miejsc po przecinku, więc 5000 = 0.005 USDC), komu (payTo), w jakiej sieci i jakim tokenem (asset), oraz jak długo oferta jest ważna.
{ "x402Version": 1, "error": "payment_required", "accepts": [{ "scheme": "exact", "network": "base-sepolia", "maxAmountRequired": "5000", // 0.005 USDC "payTo": "0x1A2b…9C", "asset": "0x036C…e", // kontrakt USDC "maxTimeoutSeconds": 60 }] }
Podpis autoryzacji EIP-3009
Płacący podpisuje kluczem prywatnym ustrukturyzowaną wiadomość EIP-712 typu ReceiveWithAuthorization (EIP-3009) na adres kontraktu-splittera: od kogo, do kogo, ile, okno ważności i jednorazowy 32-bajtowy nonce. Podpis autoryzuje jeden konkretny transfer — nie daje dostępu do portfela, nie pozwala pobrać innej kwoty ani użyć się dwa razy.
Ponowione żądanie z nagłówkiem X-PAYMENT
Klient powtarza to samo żądanie, dołączając podpisaną autoryzację jako base64 w nagłówku X-PAYMENT. Gateway dekoduje nagłówek i przekazuje dowód płatności do weryfikacji.
GET /api/dane HTTP/1.1 X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLC4uLg== # base64 → { scheme, network, payload: { signature, authorization: # { from, to, value, validAfter, validBefore, nonce } } }
Weryfikacja — sześć twardych kontroli
Facilitator odzyskuje z podpisu adres sygnatariusza i sprawdza kolejno: (1) podpis pasuje do nadawcy, (2) kwota ≥ wymaganej, (3) odbiorca zgadza się z payTo z challenge, (4) sieć i token są wspierane, (5) autoryzacja mieści się w oknie ważności, (6) nonce nie był nigdy użyty. Każde odrzucenie zwraca świeże 402 z czytelnym powodem (np. insufficient_amount, signer_mismatch).
Settlement — rozliczenie przed treścią
Płatność jest rozliczana zanim origin odda choćby bajt treści. Nonce zostaje trwale skonsumowany (unikalny indeks w bazie), powstaje zapis rozliczenia z identyfikatorem transakcji. Nieudany settlement = brak treści i zwolnienie blokady antypowtórzeniowej, więc uczciwy klient może bezpiecznie ponowić ten sam dowód.
Proxy i potwierdzenie
Dopiero teraz gateway przepuszcza żądanie do Twojego serwera (z nagłówkami X-Forwarded-*) i zwraca odpowiedź klientowi razem z nagłówkiem X-PAYMENT-RESPONSE (base64: txHash, sieć, adres płacącego). Żądanie i płatność lądują w logach — zasilają telemetrię konsoli i księgę przychodów.
Dwa rodzaje gości, dwa sposoby płacenia
Mikropłatność za każde żądanie ma sens dla maszyn, nie dla ludzi. Dlatego CrawlPay rozdziela te światy: człowiek kupuje jedną płatnością przepustkę czasową, agent AI płaci w tle za każde żądanie.
Człowiek — przepustka (Access Pass)
Czytelnik trafia na paywall z widgetem CrawlPay. Wybiera plan przepustki, klika „Zapłać”, podpisuje jedną płatność w swoim portfelu (np. MetaMask) — i przegląda treść przez cały okres ważności. Nie zakłada konta, nie podaje karty, nie płaci za gaz.
Widget jest serwowany z domeny wydawcy (same-origin), więc cookie przepustki jest first-party i nie wymaga zgody marketingowej — wystarczy wzmianka w polityce prywatności.
Agent AI — mikropłatność x402
Agent nie kupuje przepustek. Dostaje 402, podpisuje autoryzację i ponawia żądanie — automatycznie. Najprościej przez serwer MCP paypercrawl-agent-pay (Claude Desktop / Claude Code); programistycznie przez payFetch z @paypercrawl/sdk.
Pięć niezależnych barier wydatków plus tryb dry-run (symulacja bez płacenia). Klucz prywatny podpisuje wyłącznie lokalnie i nie jest nigdy logowany; narzędzie preview_price pokazuje cenę przed zapłatą.
Kto płaci, a kto nie — Ty decydujesz
Każde żądanie jest klasyfikowane do segmentu: agenci AI, crawlery wyszukiwarek, automatyzacja, ludzie… W cenniku wskazujesz, które segmenty płacą. Możesz kasować boty AI, a Googlebota zostawić darmowym — i nie stracić SEO.
Weryfikacja tożsamości botów
Deklaracja w User-Agent to za mało — każdy może się podpisać „GPTBot”. Deklarowane boty są weryfikowane po oficjalnych zakresach IP publikowanych przez operatorów, po odwrotnym DNS z potwierdzeniem (FCrDNS) i po podpisach Web Bot Auth. Wykryty podszywacz traci przywileje swojej kategorii i dostaje 403.
Ochrona przed nadużyciami
Limit żądań per IP i aplikacja (okno przesuwne 60 s) — z osobnym, ostrzejszym budżetem dla niezweryfikowanej automatyzacji.
Eskalujące blokady czasowe: powtarzające się naruszenia wydłużają blokadę (×2 w 24 h, z twardym sufitem).
Reguły blokowania per aplikacja i globalne: IP, zakresy CIDR, User-Agent, a po weryfikacji płatności także portfel płacącego.
Liczniki odrzuconych płatności per IP i per portfel — przekroczenie progu uruchamia blokadę czasową.
Pieniądze idą prosto do Ciebie
CrawlPay jest niekustodialny: nie ma tu salda do wypłaty ani kolejki przelewów. Odbiorcą każdej płatności jest smart kontrakt (splitter), który w tej samej transakcji przekazuje Twoją część na Twój portfel, a prowizję platformie. Księga przychodów tylko raportuje — każdą rozliczoną płatność księguje dokładnie raz: brutto, prowizja, netto.
Prowizja — jawna i ograniczona
Wysokość prowizji wynika z typu planu (np. standardowy plan per żądanie: 20%). Aplikacje z opublikowanym listingiem w Bazaar rozliczają się podziałem listingu (33% platforma / 67% wydawca). Limit prowizji jest zapisany na sztywno w kodzie i w kontrakcie: nigdy powyżej 50%. Prowizja jest utrwalana w momencie płatności — późniejsze zmiany cennika nie przeliczają historii.
Bez wypłat i bez czekania
Twoja część płatności ląduje na Twoim portfelu w momencie rozliczenia — nie ma salda w platformie, przycisku „wypłać” ani kolejki przelewów.
Zero custody (MiCA)
Platforma nigdy nie przechowuje środków wydawców. Saldo kontraktu po każdej transakcji wynosi zero — to celowa architektura pod europejskie regulacje (MiCA).
Portfel pod Twoją kontrolą
Tylko Ty możesz zrotować swój portfel w kontrakcie (updateMyWallet, podpis obecnym portfelem). Platforma nie ma takiej możliwości.
Jak działa kontrakt-splitter
Payer podpisuje autoryzację ReceiveWithAuthorization na adres kontraktu. Funkcja settle() w jednej, atomowej transakcji ściąga płatność i natychmiast rozdziela ją: netto na portfel wydawcy, prowizję do platformy. Podział wymusza publiczny kod kontraktu, nie obietnica. Wydawca jest identyfikowany po publisherId (hash identyfikatora aplikacji) zarejestrowanym w kontrakcie razem z jego portfelem i prowizją.
Co jest prawdziwe już dziś — szczerze
Nad stroną wisi pasek „wersja demonstracyjna” — oto co dokładnie oznacza. Tryby rozliczenia różnią się wyłącznie ostatnim krokiem: czy transfer USDC faktycznie idzie po łańcuchu.
Simulated
Kryptografia w 100% prawdziwa: pełna weryfikacja podpisu EIP-712, kwoty, odbiorcy, okna ważności i nonce. Emulowany jest wyłącznie ostatni krok — zamiast wywołać settle() na kontrakcie, facilitator generuje deterministyczny pseudo-txHash. Cały przepływ i raportowanie działają, ale żaden prawdziwy USDC się nie przemieszcza.
Onchain
Domknięcie całości: ta sama podpisana autoryzacja jest faktycznie wykonywana na kontrakcie USDC (sieć Base), z oczekiwaniem na potwierdzenia bloków i obsługą błędów świata rzeczywistego. Razem z kontraktem-splitterem urealnia przepływ pieniędzy i podział prowizji.
Zasady, których nie łamiemy
Nonce jednorazowy
Każda autoryzacja niesie losowy 32-bajtowy nonce konsumowany dokładnie raz — unikalny indeks w bazie jest źródłem prawdy, cache tylko przyspiesza odrzucanie powtórek. Replay tej samej płatności nie zadziała.
Settlement przed treścią
Treść originu nigdy nie wychodzi przed rozliczeniem płatności. Nieudany settlement = świeże 402, zero wycieku.
Klucz zostaje u płacącego
Widget podpisuje w przeglądarce czytelnika, serwer MCP — lokalnie na maszynie operatora agenta. Platforma nigdy nie widzi i nie przechowuje kluczy prywatnych płacących.
Granice zaufania
Serwisy wewnętrzne rozmawiają po kluczach wewnętrznych (fail-closed, porównanie constant-time), konsola po OIDC (Keycloak) z JWT. Klient jest zawsze niezaufany.
Przewidywalny tryb awarii
Wtyczka i SDK mają fail-open (domyślnie): gdy gateway nie odpowiada, treść serwuje się bez płatności zamiast wywalić stronę. Możesz przełączyć na fail-closed.
Weryfikowalne płatności
Każde rozliczenie ma identyfikator transakcji zwracany płacącemu w X-PAYMENT-RESPONSE i widoczny w konsoli — obie strony mogą audytować przepływ.
Pojęcia w jednym miejscu
Gotowy na więcej?
Ścieżki integracji A–D
Domena przez gateway, wtyczka WordPress, JS SDK albo płatności dla agentów AI — z realnymi snippetami.
Zobacz integracje →Demo krok po kroku
Przejdź pełny przepływ x402 samodzielnie — z przewodnikiem, żywym statusem trybu i konfiguracją serwera MCP.
Otwórz demo →Konsola wydawcy
Utwórz aplikację, cennik i trasę; checklist startowy ma 5 kroków — od aplikacji po test curlem.
Otwórz konsolę →Wolisz najpierw zobaczyć? Symulacja przeklikowa pokazuje oba przepływy — człowieka i agenta — bez portfela i bez środków.