Core Concepts

Understanding the fundamental concepts of X402 and how Shade402 implements them.

X402 Protocol Overview

X402 is a payment protocol that extends HTTP with payment capabilities. The protocol follows this flow:

  1. Client Request: Client makes a standard HTTP request to a protected resource

  2. Payment Required: Server responds with HTTP 402 and a payment request

  3. Client Payment: Client creates a payment transaction on the blockchain

  4. Payment Authorization: Client retries the request with payment proof

  5. Server Verification: Server verifies the payment and serves the resource

Payment Request

A payment request is returned when a server requires payment. It contains:

  • max_amount_required: Maximum payment amount needed

  • asset_type: Type of asset (e.g., "SPL")

  • asset_address: Token mint address or "native" for SOL

  • payment_address: Recipient wallet address

  • network: Blockchain network identifier

  • expires_at: When the payment request expires

  • nonce: Unique identifier for this request

  • payment_id: Unique payment identifier

  • resource: The resource path being requested

  • description: Optional description of what the payment is for

Payment Authorization

After making a payment, the client creates a payment authorization containing:

  • payment_id: Links to the original payment request

  • actual_amount: Amount actually paid

  • payment_address: Recipient address

  • asset_address: Token mint address

  • network: Blockchain network

  • timestamp: When the payment was made

  • signature: Transaction signature (proof of payment)

  • public_key: Payer's public key

  • transaction_hash: Transaction hash (optional, same as signature for Solana)

The authorization is sent in the X-Payment-Authorization header as base64-encoded JSON.

Solana Integration

Shade402 uses Solana for payments:

  • SPL Tokens: Support for any SPL token (USDC, USDT, etc.)

  • Native SOL: Support for native SOL payments

  • Associated Token Accounts: Automatic creation of associated token accounts

  • Transaction Signing: Client signs transactions with their wallet

  • On-chain Verification: Server verifies transactions on-chain

Payment Flow

Server-side Flow

  1. Receive request without payment authorization

  2. Generate payment request with unique payment ID

  3. Return HTTP 402 with payment request

  4. Receive retry with payment authorization header

  5. Verify payment authorization:

    • Check payment ID matches

    • Verify amount is sufficient

    • Verify addresses match

    • Check expiration

    • Verify transaction on-chain (if enabled)

  6. Process request and return resource

Client-side Flow

  1. Make initial HTTP request

  2. Receive HTTP 402 response

  3. Parse payment request

  4. Check wallet balance

  5. Create and sign Solana transaction

  6. Broadcast transaction to blockchain

  7. Create payment authorization

  8. Retry request with authorization header

  9. Receive resource

Resource Encryption

Shade402 supports optional resource encryption for privacy:

  • Server generates RSA key pair

  • Server exposes public key in 402 response headers

  • Client encrypts resource field using public key

  • Client includes encrypted resource in retry request

  • Server decrypts resource using private key

This prevents payment request replay attacks by ensuring the resource is encrypted and can only be decrypted by the server.

Error Handling

Shade402 defines specific error types:

  • PaymentRequiredError: Payment is required (402)

  • PaymentExpiredError: Payment request has expired (410)

  • InsufficientFundsError: Wallet has insufficient balance

  • PaymentVerificationError: Payment verification failed (403)

  • TransactionBroadcastError: Failed to broadcast transaction (502)

  • InvalidPaymentRequestError: Invalid payment request format (400)

Security Considerations

Server-side

  • Always verify payments on-chain in production

  • Use secure key storage for wallet private keys

  • Validate all payment authorization data

  • Check payment expiration

  • Verify payment amounts match requirements

  • Use encryption for sensitive resources

Client-side

  • Validate URLs to prevent SSRF attacks

  • Use maximum payment amounts to prevent overpayment

  • Store wallet keys securely

  • Verify payment requests before paying

  • Check transaction status before retrying

Network Configuration

Shade402 supports different Solana networks:

  • solana-devnet: Development network (for testing)

  • solana-mainnet: Production network (real payments)

  • solana-testnet: Test network (deprecated)

Configure the network when initializing the client or server.

Token Decimals

SPL tokens have different decimal places. Common values:

  • USDC: 6 decimals

  • USDT: 6 decimals

  • Native SOL: 9 decimals

Shade402 handles decimals automatically when converting amounts. The default is 6 decimals (USDC standard).

Payment Expiration

Payment requests can expire to prevent stale requests. The expiration time is:

  • Set when creating the payment request

  • Checked by the client before paying

  • Checked by the server when verifying authorization

Typical expiration times:

  • Short-lived: 5 minutes (300 seconds)

  • Standard: 10 minutes (600 seconds)

  • Long-lived: 1 hour (3600 seconds)

Next Steps

PreviousGetting StartedNextExpress Integration

Last updated