Suward
Python
PYTHON SDK

Python SDK

Official Fern-generated Python client for the Suward merchant API. Server-side only — never expose your API key to the browser.

suward · PyPIPyPIGitHub

Install

Install · pip
# pip
pip install suward
# poetry
poetry add suward

Initialize the client

client.py
from suward import SuwardSDK
# Initialize with your project API key — server-side only
client = SuwardSDK(api_key="YOUR_API_KEY")

Create a payment

create_payment returns a payment object. The address field is the unique deposit address for this payment. amount is an integer string in the asset’s smallest unit — for USDC (6 decimals), "49990000" means 49.99 USDC. Pass external_id (your order ID) as an idempotency key.

create_payment.py
from suward import SuwardSDK
client = SuwardSDK(api_key="YOUR_API_KEY")
# external_id is your order ID — acts as an idempotency key
payment = client.payments.create_payment(
# 49.99 USDC — integer string in the asset's smallest unit (6 decimals)
amount="49990000",
# asset ID: "USDT_ETHEREUM", "ETH_OPTIMISM", etc.
asset="USDC_BASE",
external_id="order-10472",
webhook_url="https://shop.example.com/webhooks/suward",
)
print(payment.id, payment.address, payment.status)

Get a payment

get_payment.py
# Fetch a payment by its ID
p = client.payments.get_payment(payment_id="pay_3Nk8Qd")
print(p.status, p.amount)

Full method surface

client.payments

  • list_payments(order, limit, last_id)→ListPaymentsResponse
  • create_payment(CreatePaymentRequest)→PaymentResponse
  • get_payment(payment_id)→PaymentResponse
  • activate_payment(payment_id)→PublicPaymentResponse
  • cancel_payment(payment_id)→PaymentResponse
  • simulate_payment(payment_id, SimulatePaymentRequest)→PaymentResponse

client.static_wallets

  • list_static_wallets(order, limit, last_id)→ListStaticWalletsResponse
  • create_static_wallet(CreateStaticWalletRequest)→StaticWalletResponse
  • get_static_wallet(static_wallet_id)→StaticWalletResponse
  • delete_static_wallet(static_wallet_id)→None
  • update_static_wallet(static_wallet_id, UpdateStaticWalletRequest)→StaticWalletResponse
  • list_static_wallet_deposits(static_wallet_id, order, limit, last_id)→ListStaticDepositsResponse
  • simulate_static_wallet_deposit(static_wallet_id, SimulateStaticDepositRequest)→StaticDepositResponse

Error handling

All SDK errors raise SuwardSDKError. Inspect status_code (HTTP status), message, and body for details.

error_handling.py
from suward import SuwardSDK, SuwardSDKError
client = SuwardSDK(api_key="YOUR_API_KEY")
try:
payment = client.payments.create_payment(
amount="49990000",
asset="USDC_BASE",
)
except SuwardSDKError as e:
print(e.status_code, e.message, e.body)

Verify webhooks

The SDK ships a built-in helper. It verifies the Ed25519 signature over the raw body bytes using the project's webhookPublicKey from the dashboard.

Verify function

verify_webhook.py
from suward.webhooks import WebhooksHelper
# raw_body: bytes — do NOT parse before verifying
ok = WebhooksHelper.verify_signature(
body=raw_body,
# "ed25519=<hex>"
signature_header=request.headers["X-Suward-Signature"],
# hex Ed25519 key from dashboard
public_key=project_webhook_public_key,
timestamp_header=request.headers["X-Suward-Timestamp"],
)

Flask handler example

app.py
from flask import Flask, request, Response
from suward.webhooks import WebhooksHelper
app = Flask(__name__)
WEBHOOK_PUBLIC_KEY = "your_project_webhook_public_key_hex"
@app.route("/webhooks/suward", methods=["POST"])
def suward_webhook():
# bytes — do NOT parse before verifying
raw_body = request.get_data()
ok = WebhooksHelper.verify_signature(
body=raw_body,
signature_header=request.headers.get("X-Suward-Signature", ""),
public_key=WEBHOOK_PUBLIC_KEY,
timestamp_header=request.headers.get("X-Suward-Timestamp", ""),
)
if not ok:
return Response(status=401)
event = request.get_json()
# event["type"]: "payment.accepted" | "payment.success" | "payment.failed"
if event["type"] == "payment.success":
# mark order paid; dedupe on event["eventId"]
pass
# non-2xx responses are retried
return Response(status=200)
SDK Reference