SolanaEasy Python SDK

The Stripe for Solana — integrate blockchain payments in less than 10 lines. No blockchain knowledge required.

Quickstart

pip install solanaeasy

from solanaeasy import SolanaEasy

sdk = SolanaEasy(api_key="sk_test_...")

# Create a payment session
session = sdk.create_payment(
    amount=50.00,
    currency="USDC",
    order_id="order_123",
    description="Nike Air Max",
)

print(session.payment_url)   # → redirect your customer here
print(session.session_id)    # → save this to track the payment

# Wait for confirmation (auto-polling, no loop needed)
status = sdk.wait_for_confirmation(session.session_id, timeout=120)
print(status.human_message)  # → "Payment confirmed in 2.3s"

Why SolanaEasy?

Installation

# Core SDK (calls SolanaEasy backend)
pip install solanaeasy

# With direct Solana network access
pip install solanaeasy[solana]

Methods

Payment States

CREATED → PENDING → CONFIRMED ✅
                 └→ FAILED    ❌
                 └→ EXPIRED   ⌛ (15 min timeout)

Error Handling

from solanaeasy import SolanaEasy
from solanaeasy.exceptions import (
    InsufficientFunds,
    SessionNotFoundError,
    WaitTimeout,
    RateLimitError,
)

sdk = SolanaEasy(api_key="sk_test_...")

try:
    status = sdk.wait_for_confirmation(session.session_id, timeout=60)

except WaitTimeout as e:
    print(f"Still {e.last_status.state} after {e.timeout}s")

except InsufficientFunds:
    print("Customer wallet has insufficient balance")

except SessionNotFoundError:
    print("Session not found")

except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

Webhooks

sdk = SolanaEasy(api_key="sk_...", webhook_secret="whsec_...")

# Register handlers using the decorator
@sdk.on("payment.confirmed")
def on_confirmed(event):
    fulfill_order(event.session_id)
    print(event.data.human_message)  # "Payment confirmed in 2.3s"

@sdk.on("payment.failed")
def on_failed(event):
    notify_customer(event.session_id)

# In your webhook endpoint (Flask / FastAPI / Django)
@app.post("/webhook/solana")
def webhook_endpoint(request):
    sdk.process_webhook(
        payload=request.body,
        signature=request.headers["X-SolanaEasy-Signature"],
    )
    return 200

Async Support

from solanaeasy import AsyncSolanaEasy

async def process_order():
    async with AsyncSolanaEasy(api_key="sk_...") as sdk:
        session = await sdk.create_payment(
            amount=50.00,
            order_id="order_123",
            idempotency_key="order_123_v1",  # prevents duplicate charges on retry
        )
        status = await sdk.wait_for_confirmation(session.session_id, timeout=120)
        return status

CLI

# Check payment status
solanaeasy status sess_abc123

# List recent payments
solanaeasy payments --status CONFIRMED --limit 10

# Watch a payment in real-time
solanaeasy wait sess_abc123 --timeout 120

Environment Variables

SOLANAEASY_API_KEY=sk_test_...          # required
SOLANAEASY_NETWORK=devnet               # devnet | mainnet-beta
SOLANAEASY_BASE_URL=http://localhost:8000
SOLANAEASY_WEBHOOK_SECRET=whsec_...

Idempotency

Pass idempotency_key to prevent duplicate charges on network retries:

session = sdk.create_payment(
    amount=50.00,
    order_id="order_123",
    idempotency_key="order_123_attempt_1",
)
# Calling twice with the same key returns the original session

License

MIT © SolanaEasy — UNICAMP Hackathon Team