X402 Payment Protocol

Executive Summary

The X402 protocol represents a revolutionary approach to internet payments by leveraging the HTTP 402 "Payment Required" status code to enable instant, programmatic payments without registration, OAuth, or complex authentication flows. Developed by Coinbase and supported by major infrastructure providers including Cloudflare, X402 provides a blockchain-agnostic payment standard that works seamlessly with existing HTTP infrastructure.

This report presents a comprehensive architecture and implementation roadmap for deploying X402 payments on Passet Hub, Polkadot's EVM-compatible smart contract platform. The implementation faces unique challenges due to Passet Hub's PolkaVM architecture and the lack of native EIP-3009 support in standard USDT. Through extensive research and analysis, we have identified viable paths forward including deploying custom EIP-3009 compatible tokens and building a self-hosted facilitator adapted for PolkaVM's constraints.

What is X402?

Overview

X402 is an open standard for internet-native payments built around the HTTP 402 "Payment Required" status code. The protocol enables users and autonomous agents to pay for resources via API without requiring registration, email addresses, OAuth flows, or complex cryptographic operations. By leveraging standard HTTP headers and blockchain settlement, X402 provides a seamless payment experience that feels natural to both Web2 and Web3 developers.

Core Principles

Use Cases

Payment Flow

Key Components

Protocol Architecture

Facilitator Models

The X402 protocol supports three facilitator deployment models, each with different trade-offs in terms of control, complexity, and network support. The facilitator is responsible for payment verification and blockchain settlement, acting as a bridge between the HTTP layer and the blockchain layer.

EIP-3009 Token Requirements

All X402 facilitators require EIP-3009 compatible tokens on their supported networks. EIP-3009 is a standard that enables gasless token transfers through signature-based authorization, eliminating the need for separate approval transactions. This is critical for X402's seamless payment experience.

// Transfer tokens with signature authorization
function transferWithAuthorization(
    address from,
    address to,
    uint256 value,
    uint256 validAfter,
    uint256 validBefore,
    bytes32 nonce,
    uint8 v,
    bytes32 r,
    bytes32 s
) external;

// Receive tokens with signature authorization
function receiveWithAuthorization(
    address from,
    address to,
    uint256 value,
    uint256 validAfter,
    uint256 validBefore,
    bytes32 nonce,
    uint8 v,
    bytes32 r,
    bytes32 s
) external;

// EIP-712 domain separator for signature verification
function DOMAIN_SEPARATOR() external view returns (bytes32);

// Token metadata for EIP-712
function name() external view returns (string memory);
function version() external view returns (string memory);

Payment Verification Flow

The facilitator performs several critical verification steps before submitting transactions to the blockchain. This multi-layered validation ensures payment integrity and prevents common attack vectors.

USDT Integration Research

Standard USDT Analysis

Through comprehensive research including source code review and documentation analysis, we have identified critical limitations with standard Tether USDT that prevent direct X402 integration.

USDT Contract Details

Alternative USDT Implementations

Research has identified several modern USDT implementations that DO support EIP-3009, providing potential templates for Passet Hub deployment.

1. USDT0 (OpenZeppelin Audited)

2. txfusion/tether-l2

3. Polygon Bridged USDT

USDT Integration Options for Passet Hub

Option 1: Deploy Custom EIP-3009 USDT (Recommended)

Option 2: Wrapper Contract Approach

Option 3: Use DOT with EIP-3009 Wrapper

Recommended Approach

EIP-3009 Implementation

Technical Specification

EIP-3009 defines a standard interface for signature-based token transfers, enabling gasless transactions and seamless integration with payment protocols like X402. The implementation requires careful attention to security, particularly signature verification and replay protection.

Core Contract Structure

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

contract USDTPH {
    // Token metadata
    string private constant NAME = "USDT Passet Hub";
    string private constant SYMBOL = "USDT-PH";
    string private constant VERSION = "1";
    uint8 private constant DECIMALS = 6;
    
    // State variables
    mapping(address => uint256) private _balances;
    mapping(address => mapping(address => uint256)) private _allowances;
    mapping(address => mapping(bytes32 => bool)) private _authorizationStates;
    uint256 private _totalSupply;
    
    // EIP-712 type hashes
    bytes32 private constant TRANSFER_WITH_AUTHORIZATION_TYPEHASH = keccak256(
        "TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"
    );
    
    // Events
    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
    event AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce);
    
    // EIP-712 domain separator (computed on-demand for PolkaVM)
    function DOMAIN_SEPARATOR() public view returns (bytes32) {
        return keccak256(abi.encode(
            keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
            keccak256(bytes(NAME)),
            keccak256(bytes(VERSION)),
            block.chainid,
            address(this)
        ));
    }
    
    // EIP-3009: Transfer with authorization
    function transferWithAuthorization(
        address from,
        address to,
        uint256 value,
        uint256 validAfter,
        uint256 validBefore,
        bytes32 nonce,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external {
        require(block.timestamp > validAfter, "Authorization not yet valid");
        require(block.timestamp < validBefore, "Authorization expired");
        require(!_authorizationStates[from][nonce], "Authorization already used");
        
        bytes32 digest = keccak256(abi.encodePacked(
            "\x19\x01",
            DOMAIN_SEPARATOR(),
            keccak256(abi.encode(
                TRANSFER_WITH_AUTHORIZATION_TYPEHASH,
                from,
                to,
                value,
                validAfter,
                validBefore,
                nonce
            ))
        ));
        
        address signer = ecrecover(digest, v, r, s);
        require(signer == from, "Invalid signature");
        
        _authorizationStates[from][nonce] = true;
        _transfer(from, to, value);
        
        emit AuthorizationUsed(from, nonce);
    }
    
    // Internal transfer logic
    function _transfer(address from, address to, uint256 value) internal {
        require(from != address(0), "Transfer from zero address");
        require(to != address(0), "Transfer to zero address");
        require(_balances[from] >= value, "Insufficient balance");
        
        _balances[from] -= value;
        _balances[to] += value;
        
        emit Transfer(from, to, value);
    }
    
    // Standard ERC-20 functions
    function name() external pure returns (string memory) {
        return NAME;
    }
    
    function symbol() external pure returns (string memory) {
        return SYMBOL;
    }
    
    function decimals() external pure returns (uint8) {
        return DECIMALS;
    }
    
    function version() external pure returns (string memory) {
        return VERSION;
    }
    
    function totalSupply() external view returns (uint256) {
        return _totalSupply;
    }
    
    function balanceOf(address account) external view returns (uint256) {
        return _balances[account];
    }
    
    // ... additional ERC-20 functions
}

PolkaVM Adaptations

Security Considerations

Replay Protection

The contract uses a nonce-based replay protection mechanism where each authorization can only be used once. The nonce is a bytes32 value chosen by the authorizer, providing flexibility in nonce management strategies.

mapping(address => mapping(bytes32 => bool)) private _authorizationStates;

function transferWithAuthorization(..., bytes32 nonce, ...) external {
    require(!_authorizationStates[from][nonce], "Authorization already used");
    // ... signature verification
    _authorizationStates[from][nonce] = true;
    // ... execute transfer
}

Time-Bound Authorization

Authorizations include validAfter and validBefore timestamps, creating a time window during which the authorization is valid. This prevents stale authorizations from being executed and provides additional security.

require(block.timestamp > validAfter, "Authorization not yet valid");
require(block.timestamp < validBefore, "Authorization expired");

Signature Verification

The contract uses EIP-712 typed structured data for signatures, providing a secure and user-friendly signing experience. The signature covers all authorization parameters along with the domain separator.

bytes32 digest = keccak256(abi.encodePacked(
    "\x19\x01",
    DOMAIN_SEPARATOR(),
    keccak256(abi.encode(
        TRANSFER_WITH_AUTHORIZATION_TYPEHASH,
        from, to, value, validAfter, validBefore, nonce
    ))
));

address signer = ecrecover(digest, v, r, s);
require(signer == from, "Invalid signature");

Facilitator Development

Self-Hosted Facilitator Architecture

Since Passet Hub is not supported by existing facilitator infrastructure, we must implement a self-hosted facilitator adapted for PolkaVM's unique characteristics. The facilitator serves as the bridge between HTTP payment requests and blockchain settlement.

Core Components

PolkaVM-Specific Adaptations

Multi-Dimensional Resource Metering

Unlike Ethereum's single gas metric, PolkaVM uses three separate resource dimensions. The facilitator must handle this complexity when estimating costs and submitting transactions.

Existential Deposit Handling

Passet Hub requires accounts to maintain a minimum balance (existential deposit) to remain active. The facilitator must ensure payment amounts account for this requirement, particularly when creating new recipient accounts.

// Pseudo-code for existential deposit handling
const EXISTENTIAL_DEPOSIT = ethers.utils.parseEther("0.01"); // Example value

async function validatePayment(payment) {
    const recipientBalance = await provider.getBalance(payment.to);
    
    if (recipientBalance.isZero()) {
        // New account - ensure payment exceeds existential deposit
        if (payment.value.lt(EXISTENTIAL_DEPOSIT)) {
            throw new Error("Payment below existential deposit for new account");
        }
    }
    
    // ... additional validation
}

Facilitator API

Verify Payment Endpoint

POST /verify
Content-Type: application/json

{
    "from": "0x...",
    "to": "0x...",
    "value": "1000000",
    "validAfter": 1699564800,
    "validBefore": 1699651200,
    "nonce": "0x...",
    "signature": {
        "v": 27,
        "r": "0x...",
        "s": "0x..."
    },
    "token": "0x..."
}

Response:
{
    "valid": true,
    "message": "Payment verified"
}

Submit Payment Endpoint

POST /submit
Content-Type: application/json

{
    "from": "0x...",
    "to": "0x...",
    "value": "1000000",
    "validAfter": 1699564800,
    "validBefore": 1699651200,
    "nonce": "0x...",
    "signature": {
        "v": 27,
        "r": "0x...",
        "s": "0x..."
    },
    "token": "0x..."
}

Response:
{
    "txHash": "0x...",
    "status": "pending"
}

Check Settlement Endpoint

GET /settlement/:txHash

Response:
{
    "txHash": "0x...",
    "status": "confirmed",
    "blockNumber": 12345678,
    "confirmations": 12
}

Passet Hub Integration

Network Configuration

Hardhat Configuration

require("@nomicfoundation/hardhat-toolbox");
require("@parity/hardhat-polkadot");
const { vars } = require("hardhat/config");

module.exports = {
    solidity: "0.8.28",
    resolc: {
        version: "0.3.0",
        compilerSource: "npm"
    },
    networks: {
        passetHub: {
            polkavm: true,
            url: "https://testnet-passet-hub-eth-rpc.polkadot.io",
            accounts: [vars.get("PRIVATE_KEY")],
            chainId: 420420422
        }
    }
};

Deployment Workflow

npx hardhat compile
npx hardhat ignition deploy ./ignition/modules/USDTPH.js --network passetHub

npx hardhat ignition deploy ./ignition/modules/PaymentEscrow.js --network passetHub

// .env file
PASSET_HUB_RPC=https://testnet-passet-hub-eth-rpc.polkadot.io
USDT_TOKEN_ADDRESS=0x...
ESCROW_CONTRACT_ADDRESS=0x...
FACILITATOR_PRIVATE_KEY=0x...
CHAIN_ID=420420422

npm install
npm run build
npm start

Testing on Passet Hub

Implementation Roadmap

The following 6-week roadmap provides a structured approach to implementing X402 payments on Passet Hub. Each phase builds upon the previous one, with clear milestones and deliverables.

Phase 1: Token Deployment & Facilitator Setup (Weeks 1-2)

Phase 2: Smart Contract & Server Development (Weeks 3-4)

Phase 3: Frontend & UX Implementation (Weeks 5-6)

Timeline Summary

Testing Strategy

Unit Tests

USDT-PH Token Tests

Facilitator Tests

Integration Tests

Security Tests

Performance Tests