Skip to main content

Usage

Configuration

Return Value

Example Implementation

Payment Flows

Standard Wallet (no session)

  1. x402Fetch makes initial request
  2. Server returns 402 with PAYMENT-REQUIRED header
  3. Hook parses requirement, validates against maxPaymentAmount and allowedRecipients
  4. Signs SNIP-12 typed data locally via signTypedData() (no on-chain transaction)
  5. Retries with X-PAYMENT header containing the signed payload
  6. Facilitator settles the payment on-chain

Session Key (automatic payments)

  1. Same flow, but signs using session key via executeTransactionWithSession()
  2. Payment executes on-chain immediately (pre-signed)
  3. lastTxHash contains the actual transaction hash
  4. No owner signature needed — session key handles it

Security

  • maxPaymentAmount enforced before signing — prevents overpayment
  • allowedRecipients whitelist — prevents payment to unauthorized addresses
  • Only "exact" scheme and "starknet-mainnet" network accepted
  • Only USDC asset accepted (native USDC contract address validated)
  • Amount validation uses BigInt math (no float precision issues)
Standard wallet payments return lastTxHash: null because the signature is SNIP-12 off-chain — the facilitator settles on-chain later. Session payments return the actual transaction hash.