Ako funguje x402 platba krok za krokom: od 402 po settlement

Celá x402 platba sú v jadre dve HTTP požiadavky. Prvá zistí cenu, druhá nesie podpísanú platbu a vráti výsledok. Medzi nimi prebehne výber platobnej možnosti a offline podpis, po nich overenie a finálne vyrovnanie (settlement) na blockchaine. Tento článok prechádza celý tok krok za krokom - s reálnymi hlavičkami, dekódovanými dátami a správaním pri chybách.

Ak sa s protokolom stretávate prvýkrát, začnite úvodným sprievodcom. Pojmy ako facilitátor, settlement či nonce podrobnejšie vysvetľuje slovník.

Aktéri a celý tok na jednom diagrame

V typickej platbe vystupujú traja aktéri:

• klient - aplikácia, skript alebo AI agent s peňaženkou, ktorý chce platený zdroj,
• resource server - API alebo web, ktorý zdroj chráni a určuje jeho cenu,
• facilitátor - služba, ktorá za server overuje platby a vykonáva vyrovnanie na blockchaine; nie je povinný, no v praxi ho používa väčšina nasadení.

klient                        resource server               facilitátor
  |                             |                             |
  | 1. GET /zdroj               |                             |
  |---------------------------->|                             |
  |                             |                             |
  | 2. 402 + PAYMENT-REQUIRED   |                             |
  |<----------------------------|                             |
  |                             |                             |
  | 3. výber možnosti,          |                             |
  |    offline podpis           |                             |
  |                             |                             |
  | 4. GET /zdroj               |                             |
  |    + PAYMENT-SIGNATURE      |                             |
  |---------------------------->|                             |
  |                             | 5. POST /verify             |
  |                             |---------------------------->|
  |                             |         payload je platný   |
  |                             |<----------------------------|
  |                             |                             |
  |                             | 6. vykonanie práce,         |
  |                             |    POST /settle             |
  |                             |---------------------------->|  zápis na
  |                             |                             |  blockchain
  |                             |        potvrdenie + hash    |
  |                             |<----------------------------|
  |                             |                             |
  |  200 OK + PAYMENT-RESPONSE  |                             |
  |<----------------------------|                             |

Čísla v diagrame zodpovedajú krokom nižšie. Pri platbe na sieti Base trvá celá výmena typicky niekoľko sekúnd.

Krok 1: prvá požiadavka, zatiaľ bez platby

Klient žiada zdroj ako ktorýkoľvek iný HTTP klient - bez registrácie, bez API kľúča, bez cookies:

GET /v1/company/36723246 HTTP/1.1
Host: api.example.sk

Server vidí, že ide o platený zdroj a požiadavka neobsahuje platobný dôkaz. Namiesto obsahu preto vráti ponuku.

Krok 2: odpoveď 402 s platobnými podmienkami

Stav 402 Payment Required tu nie je chybou, ale strojovo čitateľnou ponukou: „obsah existuje a stojí toľkoto“.

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Miwi...

Hlavička PAYMENT-REQUIRED nesie podmienky zakódované v Base64. Po dekódovaní vyzerajú takto:

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "10000",
      "payTo": "0x51bd..."
    }
  ]
}

Dve veci si zaslúžia pozornosť. Po prvé, amount sa číta vždy spolu s poľom asset: USDC má šesť desatinných miest, takže 10000 znamená 0,01 USDC. Po druhé, accepts je pole - server môže naraz ponúknuť viac možností (inú sieť, iný token) a klient si vyberie tú, ktorú podporuje. Podmienky môžu niesť aj ďalšie polia, napríklad popis zdroja či platnosť ponuky; presný zoznam určuje schéma.

Krok 3: výber možnosti a offline podpis

Klient si z ponuky vyberie kombináciu schémy a siete, ktorú vie obslúžiť, a požiada peňaženku o podpis platobnej autorizácie. Pri USDC na Base sa používa štandard EIP-3009: peňaženka podpíše štruktúrovanú správu, ktorá hovorí „z mojej adresy smie na payTo adresu odísť presne 0,01 USDC, v tomto časovom okne, s týmto jednorazovým číslom“.

{
  "from": "0x7ac9...",
  "to": "0x51bd...",
  "value": "10000",
  "validAfter": "1786579200",
  "validBefore": "1786579260",
  "nonce": "0x9f1c..."
}

Polia validAfter a validBefore ohraničujú platnosť autorizácie, nonce bráni jej opakovanému použitiu. A tri veci sa v tomto kroku nestanú:

• na blockchain sa nič neposiela - podpis vzniká úplne offline,
• klient neplatí žiadny gas,
• súkromný kľúč neopúšťa peňaženku - von ide iba podpis.

Pre autonómneho agenta je toto zároveň posledný moment na kontrolu rozpočtu a dôvery: čo smie kúpiť, za koľko a od koho. Tejto politike sa venuje článok x402 pre AI agentov.

Krok 4: opakovaná požiadavka s podpísanou platbou

Klient zopakuje pôvodnú požiadavku a pridá jedinú hlavičku:

GET /v1/company/36723246 HTTP/1.1
Host: api.example.sk
PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Miwi...

V PAYMENT-SIGNATURE je opäť Base64 JSON: zvolená schéma a sieť, autorizácia z predchádzajúceho kroku a podpis.

{
  "x402Version": 2,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x1c8e...",
    "authorization": {
      "from": "0x7ac9...",
      "to": "0x51bd...",
      "value": "10000",
      "validAfter": "1786579200",
      "validBefore": "1786579260",
      "nonce": "0x9f1c..."
    }
  }
}

Je to obyčajná nová HTTP požiadavka. Server si medzi krokmi nedrží žiadny stav ani session - všetko potrebné nesie hlavička.

Krok 5: overenie skôr, než sa čokoľvek vykoná

Server platobný payload overí - buď lokálne, alebo ho spolu s pôvodnými podmienkami pošle na /verify endpoint facilitátora. Kontroluje sa najmä:

1. podpis kryptograficky zodpovedá adrese from,
2. to, value, aktívum aj sieť sedia s pôvodnou ponukou,
3. autorizácia je platná práve teraz (validAfter/validBefore),
4. nonce ešte nebol použitý - ochrana pred replay útokom,
5. adresa from má dostatočný zostatok.

Okrem kontroly zostatku ide o kryptografické kontroly bez zápisu na blockchain: overenie je rýchle a nič nestojí. Až po ňom dáva zmysel vykonať platenú operáciu.

Rola facilitátora. Facilitátor je server s tromi endpointmi: /verify overí payload, /settle vykoná vyrovnanie, /supported vráti podporované dvojice schémy a siete. Poskytovateľ API vďaka nemu nepotrebuje blockchainový uzol, RPC pripojenie ani vlastné kryptomeny na poplatky - stačí mu payTo adresa. Najpoužívanejší verejný facilitátor prevádzkuje CDP, prehľad ďalších nájdete na stránke Ekosystém.

Krok 6: vykonanie práce a settlement

Po úspešnom overení server vykoná platenú operáciu a požiada o vyrovnanie - pošle payload na /settle. Facilitátor odošle na blockchain transakciu transferWithAuthorization, zaplatí za ňu gas a počká na potvrdenie; na Base ide o sekundy. Prostriedky prejdú priamo z adresy klienta na payTo adresu - facilitátor ich nikdy nedrží.

Poradie si volí server: lacnú a rýchlu operáciu sa oplatí vykonať pred vyrovnaním, pri drahom výpočte je bezpečnejšie najprv vyrovnať platbu a až potom míňať zdroje.

Úspešná odpoveď nesie výsledok aj potvrdenie:

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLC...

{
  "success": true,
  "transaction": "0x3d41...",
  "network": "eip155:8453",
  "payer": "0x7ac9..."
}

Pole transaction je hash on-chain transakcie: platba sa dá dohľadať v blokovom exploreri aj na x402scan.

Settlement je konečný. Neexistuje chargeback ani centrálny sprostredkovateľ, ktorý platbu vráti. Refundy a reklamácie sú produktová vrstva, ktorú si služba navrhuje sama.

Keď niečo zlyhá

Šťastná cesta je len polovica návrhu. Typické chybové situácie a správna reakcia klienta:

Opakovanie požiadaviek robí zvládnuteľným dvojica vlastností:

• Tá istá autorizácia sa nedá vyrovnať dvakrát. Nonce je jednorazový: ak klient po výpadku pošle nezmenený payload znova, druhé vyrovnanie neprejde. Opakovanie s tým istým podpisom preto nemôže strhnúť peniaze dvakrát.
• Nový podpis je nová platba. Ak si klient po chybe vypýta nové podmienky a podpíše ich, sieť to vníma ako ďalšiu platbu - hoci logicky ide o tú istú operáciu. Idempotencia platených operácií preto patrí do návrhu od prvého dňa; kontrolný zoznam nájdete v článku o V2 formáte.

Base alebo Solana: kde sa platba vyrovná

Protokol je voči sieti neutrálny. V praxi sa dnes settlement odohráva najmä na sieťach Base a Solana; kroky 1 až 6 sú rovnaké, líši sa mechanika podpisu:

Na Solane neexistuje EIP-3009, takže klient nepodpisuje autorizáciu, ale priamo transakciu prevodu, v ktorej je ako platca poplatkov uvedený facilitátor; ten ju dopodpíše a odošle. Výsledok je pre klienta rovnaký: neplatí poplatky a peniaze idú priamo na payTo adresu. Voľba siete je tak pre poskytovateľa hlavne otázkou, kde chce prostriedky prijímať a ktoré dvojice schémy a siete podporuje jeho facilitátor.

EIP-3009 alebo Permit2: dve podpisové cesty

Na EVM sieťach vedú k podpísanej platbe dve cesty:

EIP-3009 je jednoduchší a pre platby v USDC či EURC niet dôvodu siahať inam. Permit2 rozširuje x402 na tokeny bez natívnej podpory autorizácií, za cenu jednej aktivačnej transakcie navyše - klient na ňu výnimočne potrebuje natívny token siete na gas.

Poznámka k verziám protokolu

Staršie návody a SDK príklady často ukazujú V1 formát. Logika krokov sa nemení, líši sa miesto, kadiaľ dáta tečú:

Pri integrácii preto vždy kontrolujte verziu protokolu aj SDK na oboch stranách. Detailný rozbor V2 formátu, schém a overenia nájdete v článku Ako funguje x402 V2.

Kde pokračovať

• Ako funguje x402 V2: hlavičky, schémy a overenie - wire formát a kontrolný zoznam implementácie,
• x402 slovník - všetky pojmy z tohto článku na jednom mieste,
• Ekosystém - facilitátory, explorery a adresáre x402 služieb,
• normatívnym zdrojom je špecifikácia x402; podpisové štandardy definujú EIP-3009 a Permit2.