uvd-x402-sdk 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

uvd_x402_sdk/__init__.py

@@ -32,16 +32,17 @@ Example usage:
     def protected_endpoint():
         return {"message": "Payment verified!"}
 
-Supported Networks (16 total):
+Supported Networks (18 total):
 - EVM (10): Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche, Celo,
            HyperEVM, Unichain, Monad
 - SVM (2): Solana, Fogo
 - NEAR (1): NEAR Protocol
 - Stellar (1): Stellar
 - Algorand (2): Algorand mainnet, Algorand testnet
+- Sui (2): Sui mainnet, Sui testnet
 """
 
-__version__ = "0.5.2"
+__version__ = "0.5.4"
 __author__ = "Ultravioleta DAO"
 
 from uvd_x402_sdk.client import X402Client
@@ -128,6 +129,8 @@ from uvd_x402_sdk.facilitator import (
     NEAR_FEE_PAYER_TESTNET,
     STELLAR_FEE_PAYER_MAINNET,
     STELLAR_FEE_PAYER_TESTNET,
+    SUI_FEE_PAYER_MAINNET,
+    SUI_FEE_PAYER_TESTNET,
     # EVM facilitator addresses (for reference)
     EVM_FACILITATOR_MAINNET,
     EVM_FACILITATOR_TESTNET,
@@ -224,6 +227,8 @@ __all__ = [
     "NEAR_FEE_PAYER_TESTNET",
     "STELLAR_FEE_PAYER_MAINNET",
     "STELLAR_FEE_PAYER_TESTNET",
+    "SUI_FEE_PAYER_MAINNET",
+    "SUI_FEE_PAYER_TESTNET",
     "EVM_FACILITATOR_MAINNET",
     "EVM_FACILITATOR_TESTNET",
     "get_fee_payer",

uvd_x402_sdk/facilitator.py

@@ -58,6 +58,10 @@ NEAR_FEE_PAYER_TESTNET = "uvd-facilitator.testnet"
 STELLAR_FEE_PAYER_MAINNET = "GCHPGXJT2WFFRFCA5TV4G4E3PMMXLNIDUH27PKDYA4QJ2XGYZWGFZNHB"
 STELLAR_FEE_PAYER_TESTNET = "GBBFZMLUJEZVI32EN4XA2KPP445XIBTMTRBLYWFIL556RDTHS2OWFQ2Z"
 
+# Sui fee payer addresses (sponsor wallets)
+SUI_FEE_PAYER_MAINNET = "0xe7bbf2b13f7d72714760aa16e024fa1b35a978793f9893d0568a4fbf356a764a"
+SUI_FEE_PAYER_TESTNET = "0xabbd16a2fab2a502c9cfe835195a6fc7d70bfc27cffb40b8b286b52a97006e67"
+
 
 # =============================================================================
 # EVM Facilitator Addresses (for reference - EVM uses EIP-3009, no fee payer needed)
@@ -95,6 +99,10 @@ _FEE_PAYER_BY_NETWORK: Dict[str, str] = {
     "stellar": STELLAR_FEE_PAYER_MAINNET,
     "stellar-mainnet": STELLAR_FEE_PAYER_MAINNET,
     "stellar-testnet": STELLAR_FEE_PAYER_TESTNET,
+    # Sui
+    "sui": SUI_FEE_PAYER_MAINNET,
+    "sui-mainnet": SUI_FEE_PAYER_MAINNET,
+    "sui-testnet": SUI_FEE_PAYER_TESTNET,
 }
 
 # CAIP-2 format mappings (x402 v2)
@@ -114,6 +122,9 @@ _FEE_PAYER_BY_CAIP2: Dict[str, str] = {
     # Stellar
     "stellar:pubnet": STELLAR_FEE_PAYER_MAINNET,
     "stellar:testnet": STELLAR_FEE_PAYER_TESTNET,
+    # Sui
+    "sui:mainnet": SUI_FEE_PAYER_MAINNET,
+    "sui:testnet": SUI_FEE_PAYER_TESTNET,
 }
 
 

uvd_x402_sdk/networks/__init__.py

@@ -48,7 +48,7 @@ from uvd_x402_sdk.networks.base import (
 )
 
 # Import all default network configurations
-from uvd_x402_sdk.networks import evm, solana, near, stellar, algorand
+from uvd_x402_sdk.networks import evm, solana, near, stellar, algorand, sui
 
 __all__ = [
     # Core

uvd_x402_sdk/networks/base.py

@@ -57,6 +57,7 @@ class NetworkType(Enum):
     - NEAR: NEP-366 SignedDelegateAction (meta-transaction)
     - STELLAR: Soroban Authorization Entry XDR
     - ALGORAND: ASA (Algorand Standard Assets) transfer via signed transaction
+    - SUI: Sui sponsored transactions (Move-based programmable transactions)
 
     Note: SOLANA is deprecated, use SVM instead for Solana-compatible chains.
     """
@@ -67,12 +68,18 @@ class NetworkType(Enum):
     NEAR = "near"
     STELLAR = "stellar"
     ALGORAND = "algorand"  # Algorand ASA transfers
+    SUI = "sui"  # Sui Move VM chains (sponsored transactions)
 
     @classmethod
     def is_svm(cls, network_type: "NetworkType") -> bool:
         """Check if network type is SVM-compatible (Solana, Fogo, etc.)."""
         return network_type in (cls.SVM, cls.SOLANA)
 
+    @classmethod
+    def is_sui(cls, network_type: "NetworkType") -> bool:
+        """Check if network type is Sui-based."""
+        return network_type == cls.SUI
+
 
 @dataclass
 class NetworkConfig:
@@ -372,6 +379,7 @@ _CAIP2_NAMESPACE_MAP = {
     "near": NetworkType.NEAR,
     "stellar": NetworkType.STELLAR,
     "algorand": NetworkType.ALGORAND,
+    "sui": NetworkType.SUI,
 }
 
 # Network name to CAIP-2 format
@@ -397,6 +405,9 @@ _NETWORK_TO_CAIP2 = {
     # Algorand
     "algorand": "algorand:mainnet",
     "algorand-testnet": "algorand:testnet",
+    # Sui
+    "sui": "sui:mainnet",
+    "sui-testnet": "sui:testnet",
 }
 
 # CAIP-2 to network name mapping (reverse of above)
@@ -455,6 +466,11 @@ def parse_caip2_network(caip2_id: str) -> Optional[str]:
             return "algorand"
         if reference == "testnet":
             return "algorand-testnet"
+    if namespace == "sui":
+        if reference == "mainnet":
+            return "sui"
+        if reference == "testnet":
+            return "sui-testnet"
 
     return None
 

uvd_x402_sdk/networks/sui.py

@@ -0,0 +1,387 @@
+"""
+Sui network configurations.
+
+This module supports Sui blockchain for x402 payments using sponsored transactions:
+- Sui (mainnet)
+- Sui Testnet
+
+Supported Tokens:
+- USDC: Native Sui USDC
+
+All Sui chains use the same payment flow:
+1. User creates a programmable transaction for token transfer
+2. User signs the transaction
+3. Transaction is sent to the facilitator with the user's signature
+4. Facilitator sponsors the transaction (pays gas in SUI)
+5. Facilitator adds sponsor signature and submits to Sui network
+
+Transaction Structure:
+- Programmable Transaction Block (PTB) for USDC transfer
+- TransferObjects or SplitCoins + TransferObjects commands
+- Facilitator is gas sponsor (user pays ZERO SUI)
+
+Key differences from other chains:
+- Uses Move-based programmable transactions
+- BCS (Binary Canonical Serialization) encoding
+- 66-character addresses (0x + 64 hex)
+- Coin types in format: package::module::type
+"""
+
+import base64
+from typing import Dict, Any, Optional
+
+from uvd_x402_sdk.networks.base import (
+    NetworkConfig,
+    NetworkType,
+    TokenConfig,
+    register_network,
+)
+
+# Sui fee payer addresses (facilitator wallets)
+try:
+    from uvd_x402_sdk.facilitator import (
+        SUI_FEE_PAYER_MAINNET,
+        SUI_FEE_PAYER_TESTNET,
+        get_fee_payer,
+    )
+except ImportError:
+    # Fallback if facilitator module not loaded yet
+    SUI_FEE_PAYER_MAINNET = "0xe7bbf2b13f7d72714760aa16e024fa1b35a978793f9893d0568a4fbf356a764a"
+    SUI_FEE_PAYER_TESTNET = "0xabbd16a2fab2a502c9cfe835195a6fc7d70bfc27cffb40b8b286b52a97006e67"
+    get_fee_payer = None  # type: ignore
+
+
+# =============================================================================
+# Sui Networks Configuration
+# =============================================================================
+
+# USDC coin types on Sui
+SUI_USDC_COIN_TYPE_MAINNET = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
+SUI_USDC_COIN_TYPE_TESTNET = "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC"
+
+# Sui Mainnet
+SUI = NetworkConfig(
+    name="sui",
+    display_name="Sui",
+    network_type=NetworkType.SUI,
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address=SUI_USDC_COIN_TYPE_MAINNET,
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for Sui
+    usdc_domain_version="",
+    rpc_url="https://fullnode.mainnet.sui.io:443",
+    enabled=True,
+    tokens={
+        "usdc": TokenConfig(
+            address=SUI_USDC_COIN_TYPE_MAINNET,
+            decimals=6,
+            name="",  # Not applicable for Sui
+            version="",
+        ),
+    },
+    extra_config={
+        # Coin type for USDC (package::module::type format)
+        "usdc_coin_type": SUI_USDC_COIN_TYPE_MAINNET,
+        # Fee payer (facilitator) address
+        "fee_payer": SUI_FEE_PAYER_MAINNET,
+        # Block explorer
+        "explorer_url": "https://suiscan.xyz",
+        # Network identifier
+        "sui_network": "mainnet",
+        # Gas budget (in MIST, 1 SUI = 1e9 MIST)
+        "default_gas_budget": 10_000_000,  # 0.01 SUI
+    },
+)
+
+# Sui Testnet
+SUI_TESTNET = NetworkConfig(
+    name="sui-testnet",
+    display_name="Sui Testnet",
+    network_type=NetworkType.SUI,
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address=SUI_USDC_COIN_TYPE_TESTNET,
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for Sui
+    usdc_domain_version="",
+    rpc_url="https://fullnode.testnet.sui.io:443",
+    enabled=True,
+    tokens={
+        "usdc": TokenConfig(
+            address=SUI_USDC_COIN_TYPE_TESTNET,
+            decimals=6,
+            name="",  # Not applicable for Sui
+            version="",
+        ),
+    },
+    extra_config={
+        # Coin type for USDC (package::module::type format)
+        "usdc_coin_type": SUI_USDC_COIN_TYPE_TESTNET,
+        # Fee payer (facilitator) address
+        "fee_payer": SUI_FEE_PAYER_TESTNET,
+        # Block explorer
+        "explorer_url": "https://suiscan.xyz/testnet",
+        # Network identifier
+        "sui_network": "testnet",
+        # Gas budget (in MIST, 1 SUI = 1e9 MIST)
+        "default_gas_budget": 10_000_000,  # 0.01 SUI
+    },
+)
+
+# Register Sui networks
+register_network(SUI)
+register_network(SUI_TESTNET)
+
+
+# =============================================================================
+# Sui-specific utilities
+# =============================================================================
+
+
+def is_sui_network(network_name: str) -> bool:
+    """
+    Check if a network is Sui-based.
+
+    Args:
+        network_name: Network name to check
+
+    Returns:
+        True if network uses Sui
+    """
+    from uvd_x402_sdk.networks.base import get_network, NetworkType
+
+    network = get_network(network_name)
+    if not network:
+        return False
+    return NetworkType.is_sui(network.network_type)
+
+
+def get_sui_networks() -> list:
+    """
+    Get all registered Sui networks.
+
+    Returns:
+        List of Sui NetworkConfig instances
+    """
+    from uvd_x402_sdk.networks.base import list_networks, NetworkType
+
+    return [
+        n for n in list_networks(enabled_only=True)
+        if NetworkType.is_sui(n.network_type)
+    ]
+
+
+def is_valid_sui_address(address: str) -> bool:
+    """
+    Validate a Sui address format.
+
+    Sui addresses are 66 characters: 0x + 64 hex characters.
+
+    Args:
+        address: Address to validate
+
+    Returns:
+        True if valid Sui address
+    """
+    if not address or not isinstance(address, str):
+        return False
+
+    # Sui addresses start with 0x and have 64 hex characters after
+    if not address.startswith("0x"):
+        return False
+
+    hex_part = address[2:]
+    if len(hex_part) != 64:
+        return False
+
+    # Validate hex characters
+    try:
+        int(hex_part, 16)
+        return True
+    except ValueError:
+        return False
+
+
+def is_valid_sui_coin_type(coin_type: str) -> bool:
+    """
+    Validate a Sui coin type format.
+
+    Sui coin types follow format: package_address::module::type
+    Example: 0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC
+
+    Args:
+        coin_type: Coin type to validate
+
+    Returns:
+        True if valid coin type format
+    """
+    if not coin_type or not isinstance(coin_type, str):
+        return False
+
+    parts = coin_type.split("::")
+    if len(parts) != 3:
+        return False
+
+    package_addr, module_name, type_name = parts
+
+    # Validate package address
+    if not is_valid_sui_address(package_addr):
+        return False
+
+    # Validate module and type names (alphanumeric + underscore)
+    import re
+    if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', module_name):
+        return False
+    if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', type_name):
+        return False
+
+    return True
+
+
+def validate_sui_payload(payload: Dict[str, Any]) -> bool:
+    """
+    Validate a Sui payment payload structure.
+
+    The payload must contain:
+    - transactionBytes: BCS-encoded TransactionData (base64)
+    - senderSignature: User's signature (base64)
+    - from: Sender address
+    - to: Recipient address
+    - amount: Transfer amount (string)
+
+    Args:
+        payload: Payload dictionary from x402 payment
+
+    Returns:
+        True if valid, raises ValueError if invalid
+    """
+    required_fields = ["transactionBytes", "senderSignature", "from", "to", "amount"]
+    for field in required_fields:
+        if field not in payload:
+            raise ValueError(f"Sui payload missing '{field}' field")
+
+    # Validate addresses
+    if not is_valid_sui_address(payload["from"]):
+        raise ValueError(f"Invalid 'from' address: {payload['from']}")
+
+    if not is_valid_sui_address(payload["to"]):
+        raise ValueError(f"Invalid 'to' address: {payload['to']}")
+
+    # Validate transactionBytes is valid base64
+    try:
+        tx_bytes = base64.b64decode(payload["transactionBytes"])
+        if len(tx_bytes) < 50:
+            raise ValueError(f"Transaction bytes too short: {len(tx_bytes)} bytes")
+    except Exception as e:
+        raise ValueError(f"Invalid transactionBytes: {e}")
+
+    # Validate senderSignature is valid base64
+    try:
+        sig_bytes = base64.b64decode(payload["senderSignature"])
+        # Sui signatures are typically 64-65 bytes (Ed25519 or Secp256k1)
+        if len(sig_bytes) < 64:
+            raise ValueError(f"Signature too short: {len(sig_bytes)} bytes")
+    except Exception as e:
+        raise ValueError(f"Invalid senderSignature: {e}")
+
+    # Validate amount is numeric
+    try:
+        amount = int(payload["amount"])
+        if amount <= 0:
+            raise ValueError(f"Amount must be positive: {amount}")
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"Invalid amount: {e}")
+
+    return True
+
+
+def get_sui_fee_payer(network_name: str = "sui") -> str:
+    """
+    Get the fee payer (sponsor) address for a Sui network.
+
+    The fee payer is the facilitator address that sponsors transaction gas.
+
+    Args:
+        network_name: Network name ('sui', 'sui-mainnet', 'sui-testnet')
+
+    Returns:
+        Fee payer address for the specified network
+
+    Example:
+        >>> get_sui_fee_payer("sui")
+        '0xe7bbf2b13f7d72714760aa16e024fa1b35a978793f9893d0568a4fbf356a764a'
+        >>> get_sui_fee_payer("sui-testnet")
+        '0xabbd16a2fab2a502c9cfe835195a6fc7d70bfc27cffb40b8b286b52a97006e67'
+    """
+    # Use facilitator module if available
+    if get_fee_payer is not None:
+        fee_payer = get_fee_payer(network_name)
+        if fee_payer:
+            return fee_payer
+
+    # Fallback to direct lookup
+    network_lower = network_name.lower()
+    if "testnet" in network_lower:
+        return SUI_FEE_PAYER_TESTNET
+    return SUI_FEE_PAYER_MAINNET
+
+
+def get_sui_usdc_coin_type(network_name: str = "sui") -> str:
+    """
+    Get the USDC coin type for a Sui network.
+
+    Args:
+        network_name: Network name ('sui', 'sui-mainnet', 'sui-testnet')
+
+    Returns:
+        USDC coin type in package::module::type format
+
+    Example:
+        >>> get_sui_usdc_coin_type("sui")
+        '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC'
+    """
+    network_lower = network_name.lower()
+    if "testnet" in network_lower:
+        return SUI_USDC_COIN_TYPE_TESTNET
+    return SUI_USDC_COIN_TYPE_MAINNET
+
+
+# =============================================================================
+# Sui Transaction Building Utilities (for reference)
+# =============================================================================
+
+# Default gas budget in MIST (1 SUI = 1e9 MIST)
+DEFAULT_GAS_BUDGET = 10_000_000  # 0.01 SUI
+
+# Sui object ID length
+SUI_OBJECT_ID_LENGTH = 66  # 0x + 64 hex chars
+
+# Sui digest length (base58 encoded)
+SUI_DIGEST_LENGTH = 44  # base58 encoded 32-byte digest
+
+
+def format_sui_amount(usd_amount: float, decimals: int = 6) -> int:
+    """
+    Convert USD amount to Sui token base units.
+
+    Args:
+        usd_amount: Amount in USD (e.g., 10.50)
+        decimals: Token decimals (6 for USDC)
+
+    Returns:
+        Amount in base units
+    """
+    return int(usd_amount * (10 ** decimals))
+
+
+def parse_sui_amount(base_units: int, decimals: int = 6) -> float:
+    """
+    Convert Sui token base units to USD amount.
+
+    Args:
+        base_units: Amount in base units
+        decimals: Token decimals (6 for USDC)
+
+    Returns:
+        Amount in USD
+    """
+    return base_units / (10 ** decimals)

{uvd_x402_sdk-0.5.2.dist-info → uvd_x402_sdk-0.5.4.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: uvd-x402-sdk
-Version: 0.5.2
-Summary: Python SDK for x402 payments - gasless crypto payments across 16 blockchains with multi-stablecoin support (USDC, EURC, AUSD, PYUSD, USDT)
+Version: 0.5.4
+Summary: Python SDK for x402 payments - gasless crypto payments across 18 blockchains with multi-stablecoin support (USDC, EURC, AUSD, PYUSD, USDT)
 Author-email: Ultravioleta DAO <dev@ultravioletadao.xyz>
 Project-URL: Homepage, https://github.com/UltravioletaDAO/uvd-x402-sdk-python
 Project-URL: Documentation, https://docs.ultravioletadao.xyz/x402-sdk
 Project-URL: Repository, https://github.com/UltravioletaDAO/uvd-x402-sdk-python
 Project-URL: Issues, https://github.com/UltravioletaDAO/uvd-x402-sdk-python/issues
-Keywords: x402,payments,crypto,usdc,eurc,stablecoin,web3,evm,solana,near,stellar,algorand,facilitator,gasless,eip-712,eip-3009
+Keywords: x402,payments,crypto,usdc,eurc,stablecoin,web3,evm,solana,near,stellar,algorand,sui,facilitator,gasless,eip-712,eip-3009
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -53,11 +53,13 @@ Requires-Dist: eth-account>=0.10.0; extra == "web3"
 
 Python SDK for integrating **x402 cryptocurrency payments** via the Ultravioleta DAO facilitator.
 
-Accept **gasless stablecoin payments** across **14 blockchain networks** with a single integration. The SDK handles signature verification, on-chain settlement, and all the complexity of multi-chain payments.
+Accept **gasless stablecoin payments** across **16 blockchain networks** with a single integration. The SDK handles signature verification, on-chain settlement, and all the complexity of multi-chain payments.
+
+**New in v0.5.0+**: The SDK now includes embedded facilitator addresses - no manual configuration needed!
 
 ## Features
 
-- **14 Networks**: EVM chains (Base, Ethereum, Polygon, etc.), SVM chains (Solana, Fogo), NEAR, and Stellar
+- **16 Networks**: EVM chains (Base, Ethereum, Polygon, etc.), SVM chains (Solana, Fogo), NEAR, Stellar, and Algorand
 - **5 Stablecoins**: USDC, EURC, AUSD, PYUSD, USDT (EVM chains)
 - **x402 v1 & v2**: Full support for both protocol versions with auto-detection
 - **Framework Integrations**: Flask, FastAPI, Django, AWS Lambda
@@ -95,6 +97,8 @@ print(f"Paid by {result.payer_address}, tx: {result.transaction_hash}")
 | Fogo | SVM | - | `solana:fogo` | Active |
 | NEAR | NEAR | - | `near:mainnet` | Active |
 | Stellar | Stellar | - | `stellar:pubnet` | Active |
+| Algorand | Algorand | - | `algorand:mainnet` | Active |
+| Algorand Testnet | Algorand | - | `algorand:testnet` | Active |
 
 ### Supported Tokens (EVM Chains)
 
@@ -117,6 +121,7 @@ pip install uvd-x402-sdk[flask]      # Flask integration
 pip install uvd-x402-sdk[fastapi]    # FastAPI/Starlette integration
 pip install uvd-x402-sdk[django]     # Django integration
 pip install uvd-x402-sdk[aws]        # AWS Lambda helpers
+pip install uvd-x402-sdk[algorand]   # Algorand atomic group helpers
 
 # All integrations
 pip install uvd-x402-sdk[all]
@@ -375,6 +380,65 @@ from uvd_x402_sdk.networks.near import validate_near_payload
 validate_near_payload(payload.payload)  # Raises ValueError if invalid
 ```
 
+### Algorand
+
+Algorand uses atomic groups with ASA (Algorand Standard Assets) transfers.
+
+```python
+from uvd_x402_sdk import X402Client, X402Config
+
+config = X402Config(
+    recipient_algorand="NCDSNUQ2QLXDMJXRALAW4CRUSSKG4IS37MVOFDQQPC45SE4EBZO42U6ZX4",
+    supported_networks=["algorand"],
+)
+
+client = X402Client(config=config)
+result = client.process_payment(x_payment_header, Decimal("1.00"))
+
+# Algorand uses atomic groups: [fee_tx, payment_tx]
+from uvd_x402_sdk.networks.algorand import (
+    validate_algorand_payload,
+    get_algorand_fee_payer,
+    build_atomic_group,
+)
+
+# Get the facilitator fee payer address
+fee_payer = get_algorand_fee_payer("algorand")
+print(f"Fee payer: {fee_payer}")  # KIMS5H6Q...
+
+# Validate payload structure
+payload = client.extract_payload(x_payment_header)
+validate_algorand_payload(payload.payload)  # Raises ValueError if invalid
+```
+
+#### Building Algorand Payments (requires `pip install uvd-x402-sdk[algorand]`)
+
+```python
+from uvd_x402_sdk.networks.algorand import (
+    build_atomic_group,
+    build_x402_payment_request,
+    get_algorand_fee_payer,
+)
+from algosdk.v2client import algod
+
+# Connect to Algorand node
+client = algod.AlgodClient("", "https://mainnet-api.algonode.cloud")
+
+# Build atomic group
+payload = build_atomic_group(
+    sender_address="YOUR_ADDRESS...",
+    recipient_address="MERCHANT_ADDRESS...",
+    amount=1000000,  # 1 USDC (6 decimals)
+    asset_id=31566704,  # USDC ASA ID on mainnet
+    facilitator_address=get_algorand_fee_payer("algorand"),
+    sign_transaction=lambda txn: txn.sign(private_key),
+    algod_client=client,
+)
+
+# Build x402 payment request
+request = build_x402_payment_request(payload, network="algorand")
+```
+
 ---
 
 ## x402 v1 vs v2
@@ -593,6 +657,94 @@ config = X402Config.from_env()
 
 ---
 
+## Facilitator Addresses
+
+The SDK includes all facilitator addresses as embedded constants. You don't need to configure them manually.
+
+### Fee Payer Addresses (Non-EVM)
+
+Non-EVM chains require a fee payer address for gasless transactions:
+
+```python
+from uvd_x402_sdk import (
+    # Algorand
+    ALGORAND_FEE_PAYER_MAINNET,  # KIMS5H6QLCUDL65L5UBTOXDPWLMTS7N3AAC3I6B2NCONEI5QIVK7LH2C2I
+    ALGORAND_FEE_PAYER_TESTNET,  # 5DPPDQNYUPCTXRZWRYSF3WPYU6RKAUR25F3YG4EKXQRHV5AUAI62H5GXL4
+
+    # Solana
+    SOLANA_FEE_PAYER_MAINNET,    # F742C4VfFLQ9zRQyithoj5229ZgtX2WqKCSFKgH2EThq
+    SOLANA_FEE_PAYER_DEVNET,     # 6xNPewUdKRbEZDReQdpyfNUdgNg8QRc8Mt263T5GZSRv
+
+    # Fogo
+    FOGO_FEE_PAYER_MAINNET,      # F742C4VfFLQ9zRQyithoj5229ZgtX2WqKCSFKgH2EThq
+    FOGO_FEE_PAYER_TESTNET,      # 6xNPewUdKRbEZDReQdpyfNUdgNg8QRc8Mt263T5GZSRv
+
+    # NEAR
+    NEAR_FEE_PAYER_MAINNET,      # uvd-facilitator.near
+    NEAR_FEE_PAYER_TESTNET,      # uvd-facilitator.testnet
+
+    # Stellar
+    STELLAR_FEE_PAYER_MAINNET,   # GCHPGXJT2WFFRFCA5TV4G4E3PMMXLNIDUH27PKDYA4QJ2XGYZWGFZNHB
+    STELLAR_FEE_PAYER_TESTNET,   # GBBFZMLUJEZVI32EN4XA2KPP445XIBTMTRBLYWFIL556RDTHS2OWFQ2Z
+
+    # Helper function
+    get_fee_payer,               # Get fee payer for any network
+)
+
+# Get fee payer for any network
+fee_payer = get_fee_payer("algorand")  # Returns KIMS5H6Q...
+fee_payer = get_fee_payer("solana")    # Returns F742C4VfF...
+fee_payer = get_fee_payer("base")      # Returns None (EVM doesn't need fee payer)
+```
+
+### EVM Facilitator Addresses
+
+EVM chains use EIP-3009 transferWithAuthorization (gasless by design), but the facilitator wallet addresses are available for reference:
+
+```python
+from uvd_x402_sdk import (
+    EVM_FACILITATOR_MAINNET,  # 0x103040545AC5031A11E8C03dd11324C7333a13C7
+    EVM_FACILITATOR_TESTNET,  # 0x34033041a5944B8F10f8E4D8496Bfb84f1A293A8
+)
+```
+
+### Helper Functions
+
+```python
+from uvd_x402_sdk import (
+    get_fee_payer,           # Get fee payer address for a network
+    requires_fee_payer,      # Check if network needs fee payer
+    get_all_fee_payers,      # Get all registered fee payers
+    build_payment_info,      # Build payment info with auto feePayer
+    DEFAULT_FACILITATOR_URL, # https://facilitator.ultravioletadao.xyz
+)
+
+# Check if network needs fee payer
+requires_fee_payer("algorand")  # True
+requires_fee_payer("base")      # False
+
+# Build payment info with automatic fee payer
+info = build_payment_info(
+    network="algorand",
+    pay_to="MERCHANT_ADDRESS...",
+    max_amount_required="1000000",
+    description="API access"
+)
+# info = {
+#     'network': 'algorand',
+#     'payTo': 'MERCHANT_ADDRESS...',
+#     'maxAmountRequired': '1000000',
+#     'description': 'API access',
+#     'asset': '31566704',
+#     'extra': {
+#         'token': 'usdc',
+#         'feePayer': 'KIMS5H6QLCUDL65L5UBTOXDPWLMTS7N3AAC3I6B2NCONEI5QIVK7LH2C2I'
+#     }
+# }
+```
+
+---
+
 ## Registering Custom Networks
 
 ```python
@@ -823,6 +975,7 @@ The facilitator (https://facilitator.ultravioletadao.xyz) handles all on-chain i
 | SVM | Partial transaction | Co-signs + submits transaction |
 | NEAR | DelegateAction (Borsh) | Wraps in `Action::Delegate` |
 | Stellar | Auth entry (XDR) | Wraps in fee-bump transaction |
+| Algorand | ASA transfer tx | Signs fee tx + submits atomic group |
 
 ---
 
@@ -929,6 +1082,46 @@ MIT License - see LICENSE file.
 
 ## Changelog
 
+### v0.5.2 (2025-12-26)
+
+- Added EVM facilitator addresses for reference
+  - `EVM_FACILITATOR_MAINNET`: 0x103040545AC5031A11E8C03dd11324C7333a13C7
+  - `EVM_FACILITATOR_TESTNET`: 0x34033041a5944B8F10f8E4D8496Bfb84f1A293A8
+
+### v0.5.1 (2025-12-26)
+
+- Changed default Algorand mainnet network name from `algorand-mainnet` to `algorand`
+- Aligns with facilitator v1.9.5+ which now uses `algorand` as the primary network identifier
+
+### v0.5.0 (2025-12-26)
+
+- **Facilitator Module**: Added `facilitator.py` with all fee payer addresses embedded as constants
+- SDK users no longer need to configure facilitator addresses manually
+- Added constants: `ALGORAND_FEE_PAYER_MAINNET`, `SOLANA_FEE_PAYER_MAINNET`, `NEAR_FEE_PAYER_MAINNET`, `STELLAR_FEE_PAYER_MAINNET`, etc.
+- Added helper functions: `get_fee_payer()`, `requires_fee_payer()`, `build_payment_info()`
+- Network-specific helpers: `get_algorand_fee_payer()`, `get_svm_fee_payer()`, `get_near_fee_payer()`, `get_stellar_fee_payer()`
+
+### v0.4.2 (2025-12-26)
+
+- **Algorand Atomic Group Fix**: Rewrote Algorand payload format to use GoPlausible x402-avm atomic group spec
+- New `AlgorandPaymentPayload` dataclass with `paymentIndex` and `paymentGroup` fields
+- Added `build_atomic_group()` helper for constructing two-transaction atomic groups
+- Added `validate_algorand_payload()` for payload validation
+- Added `build_x402_payment_request()` for building complete x402 requests
+
+### v0.4.1 (2025-12-26)
+
+- Added AUSD (Agora USD) support on Solana using Token2022 program
+- Added `TOKEN_2022_PROGRAM_ID` constant
+- Added `get_token_program_id()` and `is_token_2022()` helpers
+
+### v0.4.0 (2025-12-26)
+
+- **Algorand Support**: Added Algorand mainnet and testnet networks
+- Added `ALGORAND` NetworkType
+- Added `algorand` optional dependency (`py-algorand-sdk>=2.0.0`)
+- SDK now supports 16 blockchain networks
+
 ### v0.3.4 (2025-12-22)
 
 - Added USDT support (USDT0 omnichain via LayerZero) on Ethereum, Arbitrum, Optimism, Avalanche, Polygon

{uvd_x402_sdk-0.5.2.dist-info → uvd_x402_sdk-0.5.4.dist-info}/RECORD

@@ -1,9 +1,9 @@
-uvd_x402_sdk/__init__.py,sha256=lLRZonhKdxY7yuLDX1owQxqQlaBeDP9GbfJ2fvScpOA,6429
+uvd_x402_sdk/__init__.py,sha256=PMSWL2YXzdKZR5Gq_JueGLE4QidfKTD9RqtSMprUyuc,6577
 uvd_x402_sdk/client.py,sha256=QbK22DtC3HmvvCezphQ-UsYX468vKrIN-M_wF4pv9cM,18389
 uvd_x402_sdk/config.py,sha256=BNGnX2RwZ_ELIcSKU7RkwTUcln4LMFZdCwG1ptASKN8,8644
 uvd_x402_sdk/decorators.py,sha256=XJ7V4554hsa-AVDrizF1oKmeTysg5zlkQRcaeGBI73E,9767
 uvd_x402_sdk/exceptions.py,sha256=kzYNHFn41dSOZ5HaBDrbf4tdwJYQs1YcU9YybTrGZxo,6527
-uvd_x402_sdk/facilitator.py,sha256=zidXzCnCJvKmK4LPXoLldslZqhKgyO8uY_hCZlJdvGs,12323
+uvd_x402_sdk/facilitator.py,sha256=OgmB-4GDu9HvG-C6DprMd4h-3neSwsxVuC5-NffVwVI,12776
 uvd_x402_sdk/models.py,sha256=nfA8Ak0pyIveiNpstjqxnQ6-aPQ8TRJzJq2LJwlJc-E,14282
 uvd_x402_sdk/response.py,sha256=4wxH4kWg1F8pokKEbN1kDvDF55cQxmQUN88HTxXht8g,13608
 uvd_x402_sdk/integrations/__init__.py,sha256=Hq1Y0YIMYWBAtmbOLXDC40KQuCrbSpQVjAqEsbjH56s,1912
@@ -11,15 +11,16 @@ uvd_x402_sdk/integrations/django_integration.py,sha256=e3xaV1Yz3HHI7zZBNcyTmV0Js
 uvd_x402_sdk/integrations/fastapi_integration.py,sha256=j5h1IJwFLBBoWov7ANLCFaxeCa8pugn-XU9ibrzIL0Y,10205
 uvd_x402_sdk/integrations/flask_integration.py,sha256=0iQKO5-WRxE76Pv-1jEl4lYhjCLmq_R-jxR5g9xIcKw,8825
 uvd_x402_sdk/integrations/lambda_integration.py,sha256=nRf4o3nS6Syx-d5P0kEhz66y7jb_S4w-mwaIazgiA9c,10184
-uvd_x402_sdk/networks/__init__.py,sha256=LKl_TljVoCDb27YB4X_VbQN8XKbdwWFAsCwgiqQtlgo,2092
+uvd_x402_sdk/networks/__init__.py,sha256=3cGi6v9mVa1NyDasB2JS1AdsRxidr8za9qGYg06kW_M,2097
 uvd_x402_sdk/networks/algorand.py,sha256=kyet3mu8Uf454QAM6PHQ1FWuQetpPQ7D0jtj7dfojsc,19433
-uvd_x402_sdk/networks/base.py,sha256=gOPWfqasGbgtg9w2uG5pWnfjdOEain92L2egnDSBguc,14863
+uvd_x402_sdk/networks/base.py,sha256=P-wTw3LnLZnd_Gv2NPsdcCZZMQb_yDY_NdEMvnstRhY,15421
 uvd_x402_sdk/networks/evm.py,sha256=4IbeaMH2I1c9DYCijghys0qYNeL2Nl92IMKLwq-b0Zg,10065
 uvd_x402_sdk/networks/near.py,sha256=HMMWJr-Jckj3YQTbSXkavlJWZB7ZV8OQX0bq8DuVxIg,12990
 uvd_x402_sdk/networks/solana.py,sha256=GVUeh0O2W6f8Vbgoom2UQSGI8joZV68Pnpzhh87Bnqg,13640
 uvd_x402_sdk/networks/stellar.py,sha256=ZuF-crx41N9MxSsgf2kAy88fsM-xvDyXY_D2ND6M71Y,5142
-uvd_x402_sdk-0.5.2.dist-info/LICENSE,sha256=OcLzB_iSgMbvk7b0dlyvleY_IbL2WUaPxvn1CHw2uAc,1073
-uvd_x402_sdk-0.5.2.dist-info/METADATA,sha256=-LP-c2xZTdyYZNk_prfgZexH3R_OEC8URkEhU_DchVE,29711
-uvd_x402_sdk-0.5.2.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-uvd_x402_sdk-0.5.2.dist-info/top_level.txt,sha256=Exyjj_Kl7CDAGFMi72lT9oFPOYiRNZb3l8tr906mMmc,13
-uvd_x402_sdk-0.5.2.dist-info/RECORD,,
+uvd_x402_sdk/networks/sui.py,sha256=klDXZ2gLnHlRt5qrv4_Vu7P2qof_WMwbv3mMfL0AQ34,11356
+uvd_x402_sdk-0.5.4.dist-info/LICENSE,sha256=OcLzB_iSgMbvk7b0dlyvleY_IbL2WUaPxvn1CHw2uAc,1073
+uvd_x402_sdk-0.5.4.dist-info/METADATA,sha256=oKeeArzQ44uDq5wyj3Q8LCKoJIf5mz-GfhAKRMXmf-w,36537
+uvd_x402_sdk-0.5.4.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+uvd_x402_sdk-0.5.4.dist-info/top_level.txt,sha256=Exyjj_Kl7CDAGFMi72lT9oFPOYiRNZb3l8tr906mMmc,13
+uvd_x402_sdk-0.5.4.dist-info/RECORD,,