uvd-x402-sdk 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

uvd_x402_sdk/__init__.py

@@ -37,7 +37,7 @@ Supported Networks (14 total):
 - Stellar (1): Stellar
 """
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 __author__ = "Ultravioleta DAO"
 
 from uvd_x402_sdk.client import X402Client

uvd_x402_sdk/networks/__init__.py

@@ -4,12 +4,13 @@ Network configurations for x402 payments.
 This module provides configuration for all supported blockchain networks,
 including USDC contract addresses, RPC URLs, and network-specific parameters.
 
-The SDK supports 14 mainnet networks out of the box:
+The SDK supports 16 mainnet networks out of the box:
 - 10 EVM chains: Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche,
                  Celo, HyperEVM, Unichain, Monad
 - 2 SVM chains: Solana, Fogo
 - 1 NEAR: NEAR Protocol
 - 1 Stellar: Stellar
+- 2 Algorand: Algorand mainnet and testnet
 
 Multi-token support (EVM chains only):
 - USDC: All chains
@@ -47,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
+from uvd_x402_sdk.networks import evm, solana, near, stellar, algorand
 
 __all__ = [
     # Core

uvd_x402_sdk/networks/algorand.py

@@ -0,0 +1,287 @@
+"""
+Algorand network configurations.
+
+This module supports Algorand blockchain networks:
+- Algorand mainnet
+- Algorand testnet
+
+Algorand uses ASA (Algorand Standard Assets) for USDC:
+- Mainnet USDC ASA ID: 31566704
+- Testnet USDC ASA ID: 10458941
+
+Payment Flow:
+1. User creates a signed ASA transfer transaction via Pera Wallet
+2. Transaction transfers USDC from user to recipient
+3. Facilitator submits the pre-signed transaction on-chain
+4. User pays ZERO transaction fees (facilitator covers fees)
+
+Transaction Structure:
+- ASA TransferAsset transaction
+- Signed by user wallet (Pera Wallet)
+- Facilitator submits the signed transaction
+
+Address Format:
+- Algorand addresses are 58 characters, base32 encoded
+- Example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ
+"""
+
+import base64
+import re
+from typing import Any, Dict, Optional
+
+from uvd_x402_sdk.networks.base import (
+    NetworkConfig,
+    NetworkType,
+    register_network,
+)
+
+
+# =============================================================================
+# Algorand Networks Configuration
+# =============================================================================
+
+# Algorand Mainnet
+ALGORAND = NetworkConfig(
+    name="algorand",
+    display_name="Algorand",
+    network_type=NetworkType.ALGORAND,
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address="31566704",  # USDC ASA ID on mainnet
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for Algorand
+    usdc_domain_version="",
+    rpc_url="https://mainnet-api.algonode.cloud",
+    enabled=True,
+    extra_config={
+        # ASA (Algorand Standard Asset) details
+        "usdc_asa_id": 31566704,
+        # Block explorer
+        "explorer_url": "https://allo.info",
+        # Indexer endpoint (for account queries)
+        "indexer_url": "https://mainnet-idx.algonode.cloud",
+        # Network identifier
+        "genesis_id": "mainnet-v1.0",
+        # Genesis hash (for CAIP-2)
+        "genesis_hash": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
+    },
+)
+
+# Algorand Testnet
+ALGORAND_TESTNET = NetworkConfig(
+    name="algorand-testnet",
+    display_name="Algorand Testnet",
+    network_type=NetworkType.ALGORAND,
+    chain_id=0,  # Non-EVM, no chain ID
+    usdc_address="10458941",  # USDC ASA ID on testnet
+    usdc_decimals=6,
+    usdc_domain_name="",  # Not applicable for Algorand
+    usdc_domain_version="",
+    rpc_url="https://testnet-api.algonode.cloud",
+    enabled=True,
+    extra_config={
+        # ASA (Algorand Standard Asset) details
+        "usdc_asa_id": 10458941,
+        # Block explorer
+        "explorer_url": "https://testnet.allo.info",
+        # Indexer endpoint (for account queries)
+        "indexer_url": "https://testnet-idx.algonode.cloud",
+        # Network identifier
+        "genesis_id": "testnet-v1.0",
+        # Genesis hash
+        "genesis_hash": "SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
+    },
+)
+
+# Register Algorand networks
+register_network(ALGORAND)
+register_network(ALGORAND_TESTNET)
+
+
+# =============================================================================
+# Algorand-specific utilities
+# =============================================================================
+
+
+def is_algorand_network(network_name: str) -> bool:
+    """
+    Check if a network is Algorand.
+
+    Args:
+        network_name: Network name to check
+
+    Returns:
+        True if network is Algorand (mainnet or testnet)
+    """
+    from uvd_x402_sdk.networks.base import get_network, NetworkType
+
+    network = get_network(network_name)
+    if not network:
+        return False
+    return network.network_type == NetworkType.ALGORAND
+
+
+def get_algorand_networks() -> list:
+    """
+    Get all registered Algorand networks.
+
+    Returns:
+        List of Algorand NetworkConfig instances
+    """
+    from uvd_x402_sdk.networks.base import list_networks, NetworkType
+
+    return [
+        n for n in list_networks(enabled_only=True)
+        if n.network_type == NetworkType.ALGORAND
+    ]
+
+
+def is_valid_algorand_address(address: str) -> bool:
+    """
+    Validate an Algorand address format.
+
+    Algorand addresses are 58 characters, base32 encoded (RFC 4648).
+    They consist of uppercase letters A-Z and digits 2-7.
+
+    Args:
+        address: Address to validate
+
+    Returns:
+        True if valid Algorand address format
+    """
+    if not address or not isinstance(address, str):
+        return False
+
+    # Algorand addresses are exactly 58 characters
+    if len(address) != 58:
+        return False
+
+    # Base32 alphabet (RFC 4648): A-Z and 2-7
+    base32_pattern = re.compile(r'^[A-Z2-7]+$')
+    return bool(base32_pattern.match(address))
+
+
+def validate_algorand_payload(payload: Dict[str, Any]) -> bool:
+    """
+    Validate an Algorand payment payload structure.
+
+    The payload must contain:
+    - from: Sender's Algorand address
+    - to: Recipient's Algorand address
+    - amount: Amount in base units (microUSDC)
+    - assetId: ASA ID for USDC
+    - signedTxn: Base64-encoded signed transaction
+
+    Args:
+        payload: Payload dictionary from x402 payment
+
+    Returns:
+        True if valid, raises ValueError if invalid
+    """
+    required_fields = ["from", "to", "amount", "assetId", "signedTxn"]
+
+    for field in required_fields:
+        if field not in payload:
+            raise ValueError(f"Algorand payload missing '{field}' field")
+
+    # Validate addresses
+    if not is_valid_algorand_address(payload["from"]):
+        raise ValueError(f"Invalid 'from' address: {payload['from']}")
+    if not is_valid_algorand_address(payload["to"]):
+        raise ValueError(f"Invalid 'to' address: {payload['to']}")
+
+    # Validate amount
+    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: {payload['amount']}") from e
+
+    # Validate assetId
+    try:
+        asset_id = int(payload["assetId"])
+        if asset_id <= 0:
+            raise ValueError(f"Asset ID must be positive: {asset_id}")
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"Invalid assetId: {payload['assetId']}") from e
+
+    # Validate signedTxn is valid base64
+    try:
+        signed_txn = payload["signedTxn"]
+        tx_bytes = base64.b64decode(signed_txn)
+        if len(tx_bytes) < 50:
+            raise ValueError(f"Signed transaction too short: {len(tx_bytes)} bytes")
+    except Exception as e:
+        raise ValueError(f"Invalid signedTxn (not valid base64): {e}") from e
+
+    return True
+
+
+def get_explorer_tx_url(network_name: str, tx_id: str) -> Optional[str]:
+    """
+    Get block explorer URL for a transaction.
+
+    Args:
+        network_name: Network name ('algorand' or 'algorand-testnet')
+        tx_id: Transaction ID
+
+    Returns:
+        Explorer URL or None if network not found
+    """
+    from uvd_x402_sdk.networks.base import get_network
+
+    network = get_network(network_name)
+    if not network or network.network_type != NetworkType.ALGORAND:
+        return None
+
+    explorer_url = network.extra_config.get("explorer_url", "https://allo.info")
+    return f"{explorer_url}/tx/{tx_id}"
+
+
+def get_explorer_address_url(network_name: str, address: str) -> Optional[str]:
+    """
+    Get block explorer URL for an address.
+
+    Args:
+        network_name: Network name ('algorand' or 'algorand-testnet')
+        address: Algorand address
+
+    Returns:
+        Explorer URL or None if network not found
+    """
+    from uvd_x402_sdk.networks.base import get_network
+
+    network = get_network(network_name)
+    if not network or network.network_type != NetworkType.ALGORAND:
+        return None
+
+    explorer_url = network.extra_config.get("explorer_url", "https://allo.info")
+    return f"{explorer_url}/account/{address}"
+
+
+def get_usdc_asa_id(network_name: str) -> Optional[int]:
+    """
+    Get the USDC ASA ID for an Algorand network.
+
+    Args:
+        network_name: Network name ('algorand' or 'algorand-testnet')
+
+    Returns:
+        USDC ASA ID or None if network not found
+    """
+    from uvd_x402_sdk.networks.base import get_network
+
+    network = get_network(network_name)
+    if not network or network.network_type != NetworkType.ALGORAND:
+        return None
+
+    # Try extra_config first, then fall back to usdc_address
+    asa_id = network.extra_config.get("usdc_asa_id")
+    if asa_id:
+        return int(asa_id)
+
+    # Parse from usdc_address (which stores the ASA ID as string)
+    try:
+        return int(network.usdc_address)
+    except (ValueError, TypeError):
+        return None

uvd_x402_sdk/networks/base.py

@@ -22,10 +22,11 @@ from typing import Dict, List, Literal, Optional, Any
 # - eurc: Euro Coin (Circle) - 6 decimals
 # - ausd: Agora USD (Agora Finance) - 6 decimals
 # - pyusd: PayPal USD (PayPal/Paxos) - 6 decimals
-TokenType = Literal["usdc", "eurc", "ausd", "pyusd"]
+# - usdt: Tether USD (USDT0 omnichain via LayerZero) - 6 decimals
+TokenType = Literal["usdc", "eurc", "ausd", "pyusd", "usdt"]
 
 # All supported token types
-ALL_TOKEN_TYPES: List[TokenType] = ["usdc", "eurc", "ausd", "pyusd"]
+ALL_TOKEN_TYPES: List[TokenType] = ["usdc", "eurc", "ausd", "pyusd", "usdt"]
 
 
 @dataclass
@@ -55,6 +56,7 @@ class NetworkType(Enum):
     - SVM: Partially-signed VersionedTransaction (SPL token transfer) - Solana, Fogo
     - NEAR: NEP-366 SignedDelegateAction (meta-transaction)
     - STELLAR: Soroban Authorization Entry XDR
+    - ALGORAND: ASA (Algorand Standard Assets) transfer via signed transaction
 
     Note: SOLANA is deprecated, use SVM instead for Solana-compatible chains.
     """
@@ -64,6 +66,7 @@ class NetworkType(Enum):
     SOLANA = "solana"  # Deprecated: use SVM
     NEAR = "near"
     STELLAR = "stellar"
+    ALGORAND = "algorand"  # Algorand ASA transfers
 
     @classmethod
     def is_svm(cls, network_type: "NetworkType") -> bool:
@@ -368,6 +371,7 @@ _CAIP2_NAMESPACE_MAP = {
     "solana": NetworkType.SVM,
     "near": NetworkType.NEAR,
     "stellar": NetworkType.STELLAR,
+    "algorand": NetworkType.ALGORAND,
 }
 
 # Network name to CAIP-2 format
@@ -390,6 +394,9 @@ _NETWORK_TO_CAIP2 = {
     "near": "near:mainnet",
     # Stellar
     "stellar": "stellar:pubnet",
+    # Algorand
+    "algorand": "algorand:mainnet",
+    "algorand-testnet": "algorand:testnet",
 }
 
 # CAIP-2 to network name mapping (reverse of above)
@@ -443,6 +450,11 @@ def parse_caip2_network(caip2_id: str) -> Optional[str]:
         return "near"
     if namespace == "stellar" and reference in ("pubnet", "mainnet"):
         return "stellar"
+    if namespace == "algorand":
+        if reference == "mainnet":
+            return "algorand"
+        if reference == "testnet":
+            return "algorand-testnet"
 
     return None
 

uvd_x402_sdk/networks/evm.py

@@ -13,6 +13,7 @@ Multi-token support:
 - EURC: Ethereum, Base, Avalanche (6 decimals)
 - AUSD: Ethereum, Arbitrum, Avalanche, Polygon, Monad (6 decimals)
 - PYUSD: Ethereum (6 decimals)
+- USDT: Arbitrum, Optimism, Celo (6 decimals) - USDT0 omnichain via LayerZero
 """
 
 from uvd_x402_sdk.networks.base import (
@@ -122,7 +123,7 @@ POLYGON = NetworkConfig(
     },
 )
 
-# Arbitrum One - supports USDC, AUSD
+# Arbitrum One - supports USDC, AUSD, USDT
 ARBITRUM = NetworkConfig(
     name="arbitrum",
     display_name="Arbitrum One",
@@ -147,10 +148,16 @@ ARBITRUM = NetworkConfig(
             name="Agora Dollar",
             version="1",
         ),
+        "usdt": TokenConfig(
+            address="0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+            decimals=6,
+            name="USD₮0",
+            version="1",
+        ),
     },
 )
 
-# Optimism
+# Optimism - supports USDC, USDT
 OPTIMISM = NetworkConfig(
     name="optimism",
     display_name="Optimism",
@@ -162,6 +169,20 @@ OPTIMISM = NetworkConfig(
     usdc_domain_version="2",
     rpc_url="https://mainnet.optimism.io",
     enabled=True,
+    tokens={
+        "usdc": TokenConfig(
+            address="0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+            decimals=6,
+            name="USD Coin",
+            version="2",
+        ),
+        "usdt": TokenConfig(
+            address="0x01bff41798a0bcf287b996046ca68b395dbc1071",
+            decimals=6,
+            name="USD₮0",
+            version="1",
+        ),
+    },
 )
 
 # Avalanche C-Chain - supports USDC, EURC, AUSD
@@ -198,7 +219,7 @@ AVALANCHE = NetworkConfig(
     },
 )
 
-# Celo
+# Celo - supports USDC, USDT
 # NOTE: Celo uses 'USDC' (not 'USD Coin') for EIP-712 domain name
 CELO = NetworkConfig(
     name="celo",
@@ -211,6 +232,20 @@ CELO = NetworkConfig(
     usdc_domain_version="2",
     rpc_url="https://forno.celo.org",
     enabled=True,
+    tokens={
+        "usdc": TokenConfig(
+            address="0xcebA9300f2b948710d2653dD7B07f33A8B32118C",
+            decimals=6,
+            name="USDC",  # Celo uses "USDC" not "USD Coin"
+            version="2",
+        ),
+        "usdt": TokenConfig(
+            address="0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e",
+            decimals=6,
+            name="Tether USD",  # Celo USDT uses "Tether USD"
+            version="1",
+        ),
+    },
 )
 
 # HyperEVM (Hyperliquid)

{uvd_x402_sdk-0.3.3.dist-info → uvd_x402_sdk-0.4.0.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: uvd-x402-sdk
-Version: 0.3.3
-Summary: Python SDK for x402 payments - gasless crypto payments across 14 blockchains with multi-stablecoin support (USDC, EURC, AUSD, PYUSD)
+Version: 0.4.0
+Summary: Python SDK for x402 payments - gasless crypto payments across 16 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,facilitator,gasless,eip-712,eip-3009
+Keywords: x402,payments,crypto,usdc,eurc,stablecoin,web3,evm,solana,near,stellar,algorand,facilitator,gasless,eip-712,eip-3009
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -56,7 +56,7 @@ Accept **gasless stablecoin payments** across **14 blockchain networks** with a
 ## Features
 
 - **14 Networks**: EVM chains (Base, Ethereum, Polygon, etc.), SVM chains (Solana, Fogo), NEAR, and Stellar
-- **4 Stablecoins**: USDC, EURC, AUSD, PYUSD (EVM chains)
+- **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
 - **Gasless Payments**: Users sign EIP-712/EIP-3009 authorizations, facilitator pays all network fees
@@ -102,6 +102,7 @@ print(f"Paid by {result.payer_address}, tx: {result.transaction_hash}")
 | EURC | Ethereum, Base, Avalanche | 6 |
 | AUSD | Ethereum, Arbitrum, Avalanche, Polygon, Monad | 6 |
 | PYUSD | Ethereum | 6 |
+| USDT | Ethereum, Arbitrum, Optimism, Avalanche, Polygon | 6 |
 
 ## Installation
 
@@ -926,6 +927,11 @@ MIT License - see LICENSE file.
 
 ## Changelog
 
+### v0.3.4 (2025-12-22)
+
+- Added USDT support (USDT0 omnichain via LayerZero) on Ethereum, Arbitrum, Optimism, Avalanche, Polygon
+- SDK now supports 5 stablecoins: USDC, EURC, AUSD, PYUSD, USDT
+
 ### v0.3.3 (2025-12-22)
 
 - Fixed EIP-712 domain names: AUSD uses "Agora Dollar" (not "Agora USD")

{uvd_x402_sdk-0.3.3.dist-info → uvd_x402_sdk-0.4.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-uvd_x402_sdk/__init__.py,sha256=weJYmfHwc8_a2CeId5PJsmaL5EUtKqS_hoPndm6fE8g,4901
+uvd_x402_sdk/__init__.py,sha256=9nsWXd6hA-22hXr8NM_JioVWzJbFu3wIllmKe9O8DW0,4901
 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
@@ -10,14 +10,15 @@ 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=5EECOYHl2OukNv55sIJlHlU4XI9s1Uv2ksoXnxkpduM,2039
-uvd_x402_sdk/networks/base.py,sha256=At8ujOr7snjWqdQQ2-vACQ4AshVvSn0FsennGF6BpQk,14347
-uvd_x402_sdk/networks/evm.py,sha256=Ah-retCWfwE1pFvywQXz03aoRbbziSiJbgw4wp4DDoE,8915
+uvd_x402_sdk/networks/__init__.py,sha256=LKl_TljVoCDb27YB4X_VbQN8XKbdwWFAsCwgiqQtlgo,2092
+uvd_x402_sdk/networks/algorand.py,sha256=ACaVMyXItRX3M29GPwwMMxECMjNXx3FlYARNBeAztH4,8601
+uvd_x402_sdk/networks/base.py,sha256=gOPWfqasGbgtg9w2uG5pWnfjdOEain92L2egnDSBguc,14863
+uvd_x402_sdk/networks/evm.py,sha256=4IbeaMH2I1c9DYCijghys0qYNeL2Nl92IMKLwq-b0Zg,10065
 uvd_x402_sdk/networks/near.py,sha256=sxbxT1NqjcENh8ysFLDpAx5DGizf1EI0YjwgviLfqcY,11608
 uvd_x402_sdk/networks/solana.py,sha256=kVSHRi57eTJdBtgI8SUbHfQUxYzx-_YvI_bEB0HIvNg,9351
 uvd_x402_sdk/networks/stellar.py,sha256=c-6re-dVc2-6gJ5rL4krUTaFsPz5vkactOJD-0wowBA,3534
-uvd_x402_sdk-0.3.3.dist-info/LICENSE,sha256=OcLzB_iSgMbvk7b0dlyvleY_IbL2WUaPxvn1CHw2uAc,1073
-uvd_x402_sdk-0.3.3.dist-info/METADATA,sha256=Aj7XqVbaMBvAKlMvd8VnjCzYFpoOrUBGRI0gXEFL7IM,29338
-uvd_x402_sdk-0.3.3.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-uvd_x402_sdk-0.3.3.dist-info/top_level.txt,sha256=Exyjj_Kl7CDAGFMi72lT9oFPOYiRNZb3l8tr906mMmc,13
-uvd_x402_sdk-0.3.3.dist-info/RECORD,,
+uvd_x402_sdk-0.4.0.dist-info/LICENSE,sha256=OcLzB_iSgMbvk7b0dlyvleY_IbL2WUaPxvn1CHw2uAc,1073
+uvd_x402_sdk-0.4.0.dist-info/METADATA,sha256=nyu6bZIOx876YTkLh-EU-ZBmGX2cpntKd_vgYheYCks,29618
+uvd_x402_sdk-0.4.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+uvd_x402_sdk-0.4.0.dist-info/top_level.txt,sha256=Exyjj_Kl7CDAGFMi72lT9oFPOYiRNZb3l8tr906mMmc,13
+uvd_x402_sdk-0.4.0.dist-info/RECORD,,