zynpay 0.1.0

Accept crypto payments with ease. No API keys required!

ZynPay Python SDK

🧪 Currently Available on Testnet | Mainnet deployment coming soon!

Accept crypto payments in your Python app

Built for merchants and businesses who want to accept USDC payments. Your customers pay with their wallet—MetaMask, Coinbase Wallet, or any web3 wallet.

Why businesses choose ZynPay

What your customers get:

• ✅ Pay with their existing wallet (MetaMask, Coinbase Wallet, etc.)
• ✅ See the exact amount before approving
• ✅ Their private keys never leave their wallet
• ✅ No sign-ups or extra accounts needed

What you get as a merchant:

• ✅ Get paid in USDC directly to your wallet
• ✅ Integrate in under 10 minutes
• ✅ Python backend + MetaMask frontend
• ✅ Zero backend infrastructure required
• ✅ Works on Base, Arc, Ethereum (testnet ready, mainnet soon)

Installation

pip install zynpay

🧪 Testnet Ready: Test with free tokens on Base Sepolia before going live!

🎯 Quick Start: Web App with MetaMask

The recommended way - customers pay with MetaMask (no private keys on your server!)

Backend (FastAPI)

from fastapi import FastAPI
from zynpay import ZynPayClient, Environment

app = FastAPI()

client = ZynPayClient(
    merchant_wallet="0xYourBusinessWallet",  # You receive payments here
    environment=Environment.TESTNET
)

@app.post("/api/payment/create")
async def create_payment(amount: float):
    payment = client.payments.create(amount=amount, chain="base")
    return {
        'payment_id': payment.id,
        'amount': payment.amount,
        'router_address': payment.router_address
    }

Frontend (HTML + MetaMask)

// Customer connects MetaMask
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = await provider.getSigner();

// Create payment on your backend
const response = await fetch("/api/payment/create", {
  method: "POST",
  body: JSON.stringify({ amount: 49.99 }),
});
const { payment_id, router_address } = await response.json();

// Customer approves and pays in MetaMask
// (No private keys exposed!)

💡 Full example: See examples/web_app/ for complete FastAPI + MetaMask integration

🔐 Server-Side Payments (Advanced)

For automation and backend-to-backend payments only. Not for customer-facing payments!

import os
from zynpay import ZynPayClient, Environment

client = ZynPayClient(
    merchant_wallet="0x1234567890123456789012345678901234567890",
    environment=Environment.TESTNET
)

# Create payment
payment = client.payments.create(amount=5.00, chain="base")

# Execute with environment variable ONLY
payer_key = os.getenv("PAYER_PRIVATE_KEY")  # NEVER hardcode!
if payer_key:
    tx_hash = client.payments.pay(payment, payer_key, wait_for_confirmation=True)
    print(f"✅ Payment confirmed! TX: {tx_hash}")

⚠️ IMPORTANT: For customer payments, use the MetaMask web app (see examples/web_app/). Only use private keys for server-side automation!

Features

Environment Management

from zynpay import Environment

# Testnet (safe for development)
client = ZynPayClient(
    merchant_wallet="0x...",
    environment=Environment.TESTNET
)
print(client.is_testnet)  # True

# Mainnet (production)
client = ZynPayClient(
    merchant_wallet="0x...",
    environment=Environment.MAINNET
)
print(client.is_mainnet)  # True

Check Balance

# Check USDC and native balance
balance = client.web3.get_balance(
    wallet="0x...",
    chain="base"
)

print(f"USDC: {balance.usdc}")
print(f"Native: {balance.native}")
print(f"Has funds: {balance.has_usdc and balance.has_gas}")

Estimate Gas

# Estimate gas cost for payment
estimate = client.web3.estimate_gas(
    amount=5.00,
    chain="base"
)

print(f"Gas cost: ${estimate.total_cost_usd:.2f}")

Testnet Helpers

if client.is_testnet:
    # Get faucet URL
    faucet_url = client.testnet.get_faucet_url("base")
    print(f"Get testnet USDC: {faucet_url}")

    # Or use helper
    client.testnet.get_usdc(wallet="0x...", amount=10.0)

Verify Payment

# Verify payment on blockchain
verified = client.payments.verify(payment)

if verified:
    print("✅ Payment confirmed on blockchain!")
    print(f"Merchant received: {payment.amount * 0.90} USDC")
    print(f"Platform received: {payment.amount * 0.10} USDC")

Supported Networks

🧪 Testnet (Currently Available - Free Tokens!)

• ✅ Base Sepolia (chain="base") - Recommended for testing

  • Router: 0x73a43f90e29843f0fE4D0Ee59F7FC8ee5f9cde52 (3% fee)
  • Get free ETH & USDC: https://portal.cdp.coinbase.com/products/faucets

• ✅ Arc Testnet (chain="arc") - USDC is the gas token 🔥

  • Router: 0x3309F63914954a1A35cc662E76a3805E86D37715
  • Get free USDC: https://faucet.circle.com

• 🔜 Ethereum Sepolia (chain="ethereum") - Coming soon

🚀 Mainnet (Coming Soon)

• 🔜 Base Mainnet (chain="base") - Production deployment planned
• 🔜 Ethereum Mainnet (chain="ethereum") - Production deployment planned

Note: Mainnet contracts will be deployed and audited before production release. Follow @zyntrialabs for updates!

Error Handling

from zynpay import (
    ZynPayClient,
    InsufficientFundsException,
    PaymentFailedException
)

try:
    payment = client.payments.create(amount=5.00)
    # Note: For customer payments, use MetaMask integration
    # See examples/web_app/ for the recommended approach
except InsufficientFundsException as e:
    print(f"Not enough funds: {e.required} USDC required")
except PaymentFailedException as e:
    print(f"Payment failed: {e.reason}")

Complete Example: FastAPI + MetaMask

See the full working example in examples/web_app/:

cd examples/web_app
pip install -r requirements.txt
python app.py
# Open http://localhost:5000 and connect MetaMask!

What it includes:

• FastAPI backend for payment creation
• Beautiful frontend with MetaMask integration
• Real-time balance checking
• Step-by-step payment flow
• No private keys on server!

API Reference

ZynPayClient

client = ZynPayClient(
    merchant_wallet="0x...",           # Required: Your wallet address
    environment=Environment.TESTNET,   # TESTNET or MAINNET
    default_chain="base",              # Default blockchain
    require_confirmation=False,        # Confirm mainnet operations
    verbose=True                       # Print info messages
)

Payments

client.payments.create()

payment = client.payments.create(
    amount=5.00,                       # Amount in USDC
    chain="base",                      # Chain name
    metadata={"order_id": "123"}       # Optional metadata
)

client.payments.pay() (Server-side only)

For automation/backend use only. For customer payments, use MetaMask web app.

import os
tx_hash = client.payments.pay(
    payment=payment,                   # Payment object
    payer_private_key=os.getenv("PAYER_PRIVATE_KEY"),  # From env only!
    wait_for_confirmation=True         # Wait for blockchain confirmation
)

client.payments.verify()

verified = client.payments.verify(
    payment=payment,                   # Payment object
    tx_hash="0x..."                    # Optional: tx hash
)

Web3

client.web3.get_balance()

balance = client.web3.get_balance(
    wallet="0x...",
    chain="base"
)
# Returns: Balance(usdc=10.0, native=0.5, chain="base")

client.web3.estimate_gas()

estimate = client.web3.estimate_gas(
    amount=5.00,
    chain="base"
)
# Returns: GasEstimate(gas_limit=300000, total_cost_usd=0.02, ...)

Testnet (only in testnet mode)

client.testnet.get_faucet_url()

url = client.testnet.get_faucet_url("base")
# Returns: "https://portal.cdp.coinbase.com/products/faucets"

client.testnet.get_usdc()

client.testnet.get_usdc(wallet="0x...", amount=10.0)
# Prints faucet URL and instructions

Run Examples

Web App with MetaMask (Recommended)

cd examples/web_app
pip install -r requirements.txt
python app.py
# Open http://localhost:5000 in browser with MetaMask

Server-Side Example (Automation only)

# Set environment variable (NEVER hardcode!)
export PAYER_PRIVATE_KEY="0x..."

# Run example
python examples/basic_payment.py

💡 For customer payments, always use the web app with MetaMask!

Development

Install for Development

git clone https://github.com/zynpay/zynpay-python
cd zynpay-python
pip install -e ".[dev]"

Run Tests

pytest tests/

Why No API Keys?

Traditional payment platforms require API keys because they:

• Track transactions on their servers
• Manage user accounts
• Handle authentication

ZynPay is different:

• Works directly with blockchain (no servers needed)
• No accounts or authentication
• 3% fee enforced by smart contract
• Fully decentralized

Result: Simpler for merchants, more reliable, truly permissionless! 🚀

Business Model

For Merchants (You)

• ✅ Free to use: No monthly fees, no setup costs
• ✅ Instant setup: Just provide your wallet address
• ✅ Receive 97%: Automatic via smart contract
• ✅ No chargebacks: Payments are final

For Platform (ZynPay)

• ✅ Automatic income: 3% from every payment
• ✅ No tracking needed: Smart contract handles it
• ✅ Scales infinitely: No servers to maintain
• ✅ Truly decentralized: Just the SDK + blockchain

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://docs.zynpay.com
• GitHub: https://github.com/zynpay/zynpay-python
• Issues: https://github.com/zynpay/zynpay-python/issues

Links

• Website: https://zynpay.com
• TypeScript SDK: https://github.com/zynpay/zynpay-typescript

---

Made with ❤️ by the ZynPay team

No API keys. No servers. Just payments. ⚡