@402-stellar | Monetize Web3 Effortlessly

A detailed look at the actual JSON structures used in Stellar x402 vs the base x402 protocol (EVM). This helps you understand the differences at a glance.

1. Payment Required Response (402 Response)

When a server requires payment, it returns a 402 Payment Required status.

Base x402 Format (EVM Example)

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "1000000",
      "resource": "https://api.example.com/premium",
      "payTo": "0x2096...12287C",
      "asset": "0x036C...3dCF7e"
    }
  ]
}

Stellar x402 Format

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "stellar-testnet",
      "maxAmountRequired": "10000000", // 1 XLM
      "resource": "https://api.example.com/premium",
      "payTo": "GC63P...W5BSIRT",
      "asset": "native", // Native XLM
      "extra": {
        "feeSponsorship": true
      }
    }
  ]
}

Key Differences

network: "stellar-testnet" vs "base-sepolia"
asset: "native" for XLM vs ERC-20 address
maxAmountRequired: Stroops (7 decimals) vs wei/token units
payTo: Stellar address (G...) vs EVM address (0x...)

2. Payment Payload (X-PAYMENT Header)

The client sends this as the X-PAYMENT header (base64-encoded JSON).

Base x402 (Signature-based)

{
  "payload": {
    "signature": "0x2d6a...",
    "authorization": {
      "from": "0x857b...",
      "to": "0x2096...",
      "value": "1000000",
      "validBefore": "1740672154",
      "nonce": "0xf374..."
    }
  }
}

Stellar x402 (XDR-based)

{
  "payload": {
    "signedTxXdr": "AAAAAg...", // Complete signed tx
    "sourceAccount": "GABC...",
    "destination": "GC63...",
    "amount": "10000000",
    "asset": "native",
    "validUntilLedger": 12345678,
    "nonce": "550e84..."
  }
}

Why XDR?

Stellar uses XDR (eXternal Data Representation) for all transactions
The signedTxXdr contains the complete, signed transaction ready for submission
Facilitator can optionally fee-bump without modifying the client's transaction
Built-in replay protection via Stellar's sequence numbers

3. Facilitator Verify Request

// Stellar x402 Format (Compatible, with flexibility)
{
  "x402Version": 1,
  "paymentPayload": { /* PaymentPayload object */ },  // OR
  "paymentHeader": "base64-encoded-payment-header",   // Alternative format
  "paymentRequirements": { /* PaymentRequirements object */ }
}

Summary of Format Differences

Aspect	EVM (Coinbase)	Stellar (Ours)
Payment Structure	Signature + authorization object	Complete signed XDR transaction
Expiry	Unix timestamp (validBefore)	Ledger sequence (validUntilLedger)
Native Asset	Requires ERC-20 contract	"native" (no contract)
Replay Protection	Nonce in authorization	Sequence numbers (protocol-level)

Protocol Format Comparison