fractalpay 1.0.0__tar.gz

fractalpay-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+target/
+*.exe
+*.dll
+*.so
+*.dylib

fractalpay-1.0.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to the `fractalpay` Python SDK are documented here. Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-05-25
+
+Initial public release. Stripe-shaped API on top of the existing FractalPay
+intent infrastructure (`/api/pay`, `/api/pay/webhook`).
+
+### Added
+
+- `FractalPay` client class with `httpx` under the hood
+- `FractalPay.intents.create()` — wraps `POST /api/pay` with snake_case→camelCase
+- `FractalPay.intents.retrieve(id)` — wraps `GET /api/pay?id=X`
+- `FractalPay.intents.list(status?, limit?)` — wraps `GET /api/pay?list=true`
+- `FractalPay.intents.stream(id)` — SSE iterator for real-time updates
+- `verify_webhook(payload, signature, secret)` — HMAC-SHA256 verification
+  with constant-time comparison; accepts both `sha256=<hex>` and bare hex
+- `WebhookEvent` dataclass with typed `event.type` and `event.intent`
+- `PaymentIntent` dataclass mirroring API shape (snake_case Pythonic fields)
+- Typed exception hierarchy: `FractalPayError` base + `AuthenticationError`,
+  `InvalidRequestError`, `RateLimitError`, `APIConnectionError`, `APIError`,
+  `SignatureVerificationError`
+- Full pytest suite covering serialization, error mapping, signature
+  verification (positive + adversarial), context-manager lifecycle
+- `examples/quickstart.py` — create + display intent in 20 lines
+- `examples/webhook_handler.py` — Flask example for merchant integration
+
+### Spec compliance
+
+- [x] Mirrors the server-side `PaymentIntent` type from
+      `frontend/lib/types/payment.ts`
+- [x] camelCase wire format (server) ↔ snake_case Pythonic API (SDK)
+- [x] Constant-time HMAC comparison for webhook verification
+      (`hmac.compare_digest`)
+- [x] Bearer token Authorization header when `api_key` is provided
+- [x] Apache-2.0 license; zero non-permissive dependencies

fractalpay-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 FractalAI Foundation and contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fractalpay-1.0.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: fractalpay
+Version: 1.0.0
+Summary: FractalPay AaaS — Python SDK. The post-quantum, AI-verified, multi-chain payment gateway as a service. Stripe-shaped API on top of 9 blockchains (8 EVM + Stellar) with VAID-1 cryptographic attestations.
+Project-URL: Homepage, https://fractalai.net.co/standards/fractalpay
+Project-URL: Documentation, https://fractalai.net.co/docs/fractalpay
+Project-URL: Repository, https://github.com/johnInarti/FRACTAL-AI
+Project-URL: Issues, https://github.com/johnInarti/FRACTAL-AI/issues
+Project-URL: Changelog, https://github.com/johnInarti/FRACTAL-AI/blob/main/sdk/python-fractalpay/CHANGELOG.md
+Author-email: FractalAI Foundation <developers@fractalai.net.co>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: aaas,base,crypto-payments,ethereum,fractalai,fractalpay,multi-chain,payments,post-quantum,stablecoin,stellar,stripe-alternative
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fractalpay
+
+**FractalPay AaaS** — Python SDK for the post-quantum, AI-verified, multi-chain
+payment gateway as a service.
+
+Stripe-shaped API. Nine blockchains (8 EVM + Stellar) native. Cryptographic
+[VAID-1](https://github.com/johnInarti/FRACTAL-AI/blob/main/VAID_1_SPEC.md)
+attestation on every payment. 0.618% fee instead of 2.9% + 30¢.
+
+## Install
+
+```bash
+pip install fractalpay
+```
+
+Requires Python 3.9+. Only dependency is `httpx`.
+
+## Quickstart — receive a payment in 5 lines
+
+```python
+from fractalpay import FractalPay
+
+fp = FractalPay()  # base_url defaults to https://fractalai.net.co
+
+intent = fp.intents.create(
+    amount="100.00",
+    currency="USDC",
+    recipient_address="0xYourWalletOnBase",
+    recipient_chain="base",
+    description="Pro plan — monthly",
+    callback_url="https://your-app.com/webhooks/fractalpay",
+)
+
+print(f"Send your customer to: {intent.web_url}")
+# → https://fractalai.net.co/pay/{intent.id}
+```
+
+That's it. The customer lands on a hosted checkout page, pays in their wallet,
+your webhook fires when the payment is confirmed on-chain.
+
+## Why this exists
+
+| | Stripe | Coinbase Commerce | FractalPay |
+|---|---|---|---|
+| Fee per tx | 2.9% + 30¢ | 1.0% | **0.618%** (φ⁻¹) |
+| Chains supported | 0 (card only) | 4 | **9** (8 EVM + Stellar) |
+| Post-quantum signatures | ❌ | ❌ | ✅ **CRYSTALS-Dilithium** |
+| Cryptographic proof per payment | ❌ (PDF receipt) | ❌ | ✅ **VAID-1 attestation** |
+| Open source | ❌ | ❌ | ✅ Apache-2.0 |
+| Settlement | T+2 to bank | T+0 to crypto | T+0 to crypto, fiat off-ramp roadmap |
+
+## Verify an incoming webhook
+
+```python
+from fractalpay import verify_webhook
+
+@app.route("/webhooks/fractalpay", methods=["POST"])
+def handle_webhook():
+    event = verify_webhook(
+        payload=request.get_data(),
+        signature=request.headers["X-FractalPay-Signature"],
+        secret=os.environ["FRACTALPAY_WEBHOOK_SECRET"],
+    )
+    if event.type == "payment.completed":
+        # event.intent.id, event.intent.tx_hash, event.intent.payer_address
+        fulfill_order(event.intent.metadata["order_id"])
+    return "ok", 200
+```
+
+## Query an intent
+
+```python
+intent = fp.intents.retrieve("intent_abc123")
+print(intent.status)
+# 'created' | 'detecting' | 'confirming' | 'bridging' | 'completed' | 'expired' | 'failed' | 'refunded'
+
+if intent.status == "completed":
+    print(f"Settled: {intent.settled_amount} {intent.currency} on {intent.recipient_chain}")
+    print(f"Payer: {intent.payer_address}")
+    print(f"Tx hash: {intent.tx_hash}")
+```
+
+## List intents
+
+```python
+# All recent
+for intent in fp.intents.list(limit=100):
+    print(intent.id, intent.amount, intent.status)
+
+# Only completed
+for intent in fp.intents.list(status="completed", limit=50):
+    print(intent.id, intent.completed_at)
+```
+
+## Multi-chain payment routing
+
+Your customer can pay from ANY of the 9 supported chains; FractalPay handles the
+routing and bridges to your settlement chain.
+
+```python
+intent = fp.intents.create(
+    amount="500.00",
+    currency="USDC",
+    recipient_address="0xMyBaseWallet",
+    recipient_chain="base",       # I want USDC on Base
+    # Customer can pay from: ethereum, polygon, arbitrum, stellar, etc.
+)
+
+# `intent.suggested_chains` lists the chains the customer can use.
+```
+
+## Hosted vs. embedded checkout
+
+**Hosted (recommended):** redirect the customer to `intent.web_url`. Zero
+frontend work, mobile-optimized, supports every wallet (MetaMask, Coinbase,
+Lobstr, hardware wallets, etc.).
+
+**Embedded:** use the JS widget — see `@fractalai/pay` (TypeScript SDK) and
+`/api/pay/widget` endpoint.
+
+## Real-time updates (SSE)
+
+```python
+for event in fp.intents.stream(intent.id):
+    print(f"{event.timestamp}: {event.status}")
+    if event.status in ("completed", "failed", "expired"):
+        break
+```
+
+## What's a payment intent?
+
+Same concept as Stripe's `PaymentIntent`: a server-side object representing
+your intent to collect payment from a customer. It's created with an amount,
+currency, and recipient; it expires after a TTL (default 30 min); it tracks
+status through its lifecycle from `created` → `detecting` → `confirming` →
+`completed`.
+
+The big difference: FractalPay's intent is **multi-chain native** (the
+customer chooses where to pay from) and **HMAC-signed** (the recipient address
+can't be tampered with in transit).
+
+## License
+
+- This SDK: Apache-2.0 (see `LICENSE`)
+- The FractalPay API and protocol: same license, plus open-source server
+  implementation at github.com/johnInarti/FRACTAL-AI
+
+## Resources
+
+- [API reference](https://fractalai.net.co/docs/fractalpay)
+- [VAID-1 spec](https://github.com/johnInarti/FRACTAL-AI/blob/main/VAID_1_SPEC.md)
+  (the attestation standard every payment carries)
+- [TypeScript SDK](https://www.npmjs.com/package/@fractalai/pay) (coming)
+- [Issues](https://github.com/johnInarti/FRACTAL-AI/issues) (label `fractalpay`)

fractalpay-1.0.0/README.md

@@ -0,0 +1,154 @@
+# fractalpay
+
+**FractalPay AaaS** — Python SDK for the post-quantum, AI-verified, multi-chain
+payment gateway as a service.
+
+Stripe-shaped API. Nine blockchains (8 EVM + Stellar) native. Cryptographic
+[VAID-1](https://github.com/johnInarti/FRACTAL-AI/blob/main/VAID_1_SPEC.md)
+attestation on every payment. 0.618% fee instead of 2.9% + 30¢.
+
+## Install
+
+```bash
+pip install fractalpay
+```
+
+Requires Python 3.9+. Only dependency is `httpx`.
+
+## Quickstart — receive a payment in 5 lines
+
+```python
+from fractalpay import FractalPay
+
+fp = FractalPay()  # base_url defaults to https://fractalai.net.co
+
+intent = fp.intents.create(
+    amount="100.00",
+    currency="USDC",
+    recipient_address="0xYourWalletOnBase",
+    recipient_chain="base",
+    description="Pro plan — monthly",
+    callback_url="https://your-app.com/webhooks/fractalpay",
+)
+
+print(f"Send your customer to: {intent.web_url}")
+# → https://fractalai.net.co/pay/{intent.id}
+```
+
+That's it. The customer lands on a hosted checkout page, pays in their wallet,
+your webhook fires when the payment is confirmed on-chain.
+
+## Why this exists
+
+| | Stripe | Coinbase Commerce | FractalPay |
+|---|---|---|---|
+| Fee per tx | 2.9% + 30¢ | 1.0% | **0.618%** (φ⁻¹) |
+| Chains supported | 0 (card only) | 4 | **9** (8 EVM + Stellar) |
+| Post-quantum signatures | ❌ | ❌ | ✅ **CRYSTALS-Dilithium** |
+| Cryptographic proof per payment | ❌ (PDF receipt) | ❌ | ✅ **VAID-1 attestation** |
+| Open source | ❌ | ❌ | ✅ Apache-2.0 |
+| Settlement | T+2 to bank | T+0 to crypto | T+0 to crypto, fiat off-ramp roadmap |
+
+## Verify an incoming webhook
+
+```python
+from fractalpay import verify_webhook
+
+@app.route("/webhooks/fractalpay", methods=["POST"])
+def handle_webhook():
+    event = verify_webhook(
+        payload=request.get_data(),
+        signature=request.headers["X-FractalPay-Signature"],
+        secret=os.environ["FRACTALPAY_WEBHOOK_SECRET"],
+    )
+    if event.type == "payment.completed":
+        # event.intent.id, event.intent.tx_hash, event.intent.payer_address
+        fulfill_order(event.intent.metadata["order_id"])
+    return "ok", 200
+```
+
+## Query an intent
+
+```python
+intent = fp.intents.retrieve("intent_abc123")
+print(intent.status)
+# 'created' | 'detecting' | 'confirming' | 'bridging' | 'completed' | 'expired' | 'failed' | 'refunded'
+
+if intent.status == "completed":
+    print(f"Settled: {intent.settled_amount} {intent.currency} on {intent.recipient_chain}")
+    print(f"Payer: {intent.payer_address}")
+    print(f"Tx hash: {intent.tx_hash}")
+```
+
+## List intents
+
+```python
+# All recent
+for intent in fp.intents.list(limit=100):
+    print(intent.id, intent.amount, intent.status)
+
+# Only completed
+for intent in fp.intents.list(status="completed", limit=50):
+    print(intent.id, intent.completed_at)
+```
+
+## Multi-chain payment routing
+
+Your customer can pay from ANY of the 9 supported chains; FractalPay handles the
+routing and bridges to your settlement chain.
+
+```python
+intent = fp.intents.create(
+    amount="500.00",
+    currency="USDC",
+    recipient_address="0xMyBaseWallet",
+    recipient_chain="base",       # I want USDC on Base
+    # Customer can pay from: ethereum, polygon, arbitrum, stellar, etc.
+)
+
+# `intent.suggested_chains` lists the chains the customer can use.
+```
+
+## Hosted vs. embedded checkout
+
+**Hosted (recommended):** redirect the customer to `intent.web_url`. Zero
+frontend work, mobile-optimized, supports every wallet (MetaMask, Coinbase,
+Lobstr, hardware wallets, etc.).
+
+**Embedded:** use the JS widget — see `@fractalai/pay` (TypeScript SDK) and
+`/api/pay/widget` endpoint.
+
+## Real-time updates (SSE)
+
+```python
+for event in fp.intents.stream(intent.id):
+    print(f"{event.timestamp}: {event.status}")
+    if event.status in ("completed", "failed", "expired"):
+        break
+```
+
+## What's a payment intent?
+
+Same concept as Stripe's `PaymentIntent`: a server-side object representing
+your intent to collect payment from a customer. It's created with an amount,
+currency, and recipient; it expires after a TTL (default 30 min); it tracks
+status through its lifecycle from `created` → `detecting` → `confirming` →
+`completed`.
+
+The big difference: FractalPay's intent is **multi-chain native** (the
+customer chooses where to pay from) and **HMAC-signed** (the recipient address
+can't be tampered with in transit).
+
+## License
+
+- This SDK: Apache-2.0 (see `LICENSE`)
+- The FractalPay API and protocol: same license, plus open-source server
+  implementation at github.com/johnInarti/FRACTAL-AI
+
+## Resources
+
+- [API reference](https://fractalai.net.co/docs/fractalpay)
+- [VAID-1 spec](https://github.com/johnInarti/FRACTAL-AI/blob/main/VAID_1_SPEC.md)
+  (the attestation standard every payment carries)
+- [TypeScript SDK](https://www.npmjs.com/package/@fractalai/pay) (coming)
+- [Issues](https://github.com/johnInarti/FRACTAL-AI/issues) (label `fractalpay`)

fractalpay-1.0.0/examples/quickstart.py

@@ -0,0 +1,36 @@
+"""
+FractalPay SDK quickstart — create a payment intent in under 20 lines.
+
+Run with:
+    pip install -e ..
+    python quickstart.py
+"""
+
+from fractalpay import FractalPay
+
+# Point at staging or your own deployment with base_url=...; defaults to prod.
+fp = FractalPay()
+
+# Create a $10 USDC payment intent settling on Base.
+intent = fp.intents.create(
+    amount="10.00",
+    currency="USDC",
+    recipient_address="0xC13789e82661635d9Cea38a53A0390CF9939ef4f",
+    recipient_chain="base",
+    merchant_name="FractalPay SDK Demo",
+    description="Pro plan — monthly",
+    metadata={"order_id": "DEMO-001"},
+)
+
+print(f"intent id:         {intent.id}")
+print(f"status:            {intent.status}")
+print(f"amount:            {intent.amount} {intent.currency}")
+print(f"recipient chain:   {intent.recipient_chain}")
+print(f"suggested chains:  {', '.join(intent.suggested_chains)}")
+print(f"expires (unix ms): {intent.expires_at}")
+print()
+print(f"Send your customer to:")
+print(f"   {intent.web_url}")
+print()
+print(f"Mobile deep link:")
+print(f"   {intent.qr_url}")

fractalpay-1.0.0/examples/webhook_handler.py

@@ -0,0 +1,64 @@
+"""
+Example merchant webhook handler.
+
+Flask-style — adapt to FastAPI / Django / whatever framework you use. The
+critical part is calling `verify_webhook` with the RAW request body (not a
+re-serialized JSON dict) and the signature header.
+"""
+
+import os
+
+from flask import Flask, request
+
+from fractalpay import SignatureVerificationError, verify_webhook
+
+app = Flask(__name__)
+
+# The merchant's webhook signing secret. Get this from your FractalPay dashboard.
+WEBHOOK_SECRET = os.environ["FRACTALPAY_WEBHOOK_SECRET"]
+
+
+@app.post("/webhooks/fractalpay")
+def handle_fractalpay_webhook():
+    # IMPORTANT: pass the raw body bytes (not request.json) — re-serializing
+    # changes the bytes and invalidates the signature.
+    try:
+        event = verify_webhook(
+            payload=request.get_data(),
+            signature=request.headers.get("X-FractalPay-Signature"),
+            secret=WEBHOOK_SECRET,
+        )
+    except SignatureVerificationError:
+        # Hostile or misconfigured caller — reject without revealing why.
+        return "", 401
+
+    if event.type == "payment.completed":
+        order_id = (event.intent.metadata or {}).get("order_id")
+        if order_id:
+            mark_order_paid(
+                order_id,
+                amount=event.intent.settled_amount or event.intent.amount,
+                currency=event.intent.currency,
+                tx_hash=event.intent.tx_hash,
+            )
+    elif event.type == "payment.failed":
+        order_id = (event.intent.metadata or {}).get("order_id")
+        if order_id:
+            mark_order_failed(order_id)
+
+    # Always return 2xx to acknowledge — FractalPay won't retry on 2xx.
+    return "", 200
+
+
+def mark_order_paid(order_id: str, *, amount: str, currency: str, tx_hash: str | None) -> None:
+    """Stub — replace with your real order-fulfillment logic."""
+    print(f"[paid] order={order_id} amount={amount} {currency} tx={tx_hash}")
+
+
+def mark_order_failed(order_id: str) -> None:
+    """Stub — replace with your real failure-handling logic."""
+    print(f"[failed] order={order_id}")
+
+
+if __name__ == "__main__":
+    app.run(port=5000, debug=False)

fractalpay-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fractalpay"
+version = "1.0.0"
+description = "FractalPay AaaS — Python SDK. The post-quantum, AI-verified, multi-chain payment gateway as a service. Stripe-shaped API on top of 9 blockchains (8 EVM + Stellar) with VAID-1 cryptographic attestations."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+authors = [
+    { name = "FractalAI Foundation", email = "developers@fractalai.net.co" },
+]
+keywords = [
+    "payments", "stripe-alternative", "crypto-payments", "stablecoin",
+    "post-quantum", "multi-chain", "stellar", "base", "ethereum",
+    "fractalai", "fractalpay", "aaas",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.1.0",
+    "respx>=0.20",
+]
+
+[project.urls]
+Homepage = "https://fractalai.net.co/standards/fractalpay"
+Documentation = "https://fractalai.net.co/docs/fractalpay"
+Repository = "https://github.com/johnInarti/FRACTAL-AI"
+Issues = "https://github.com/johnInarti/FRACTAL-AI/issues"
+Changelog = "https://github.com/johnInarti/FRACTAL-AI/blob/main/sdk/python-fractalpay/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fractalpay"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

fractalpay-1.0.0/src/fractalpay/__init__.py

@@ -0,0 +1,73 @@
+"""
+fractalpay — Python SDK for FractalPay AaaS.
+
+Quick reference for the public API:
+
+    Client:
+        FractalPay              — main entry point
+        FractalPay.intents      — payment intent operations
+
+    Webhook:
+        verify_webhook          — validate + parse a merchant webhook
+        WebhookEvent            — typed event from verify_webhook
+
+    Types:
+        PaymentIntent           — a created/retrieved payment intent
+        PaymentChain            — Literal of supported chains
+        PaymentCurrency         — Literal of supported tokens
+        PaymentStatus           — Literal of intent lifecycle states
+
+    Errors:
+        FractalPayError                 — base class
+        AuthenticationError             — bad/missing credentials
+        InvalidRequestError             — 4xx from API
+        RateLimitError                  — 429
+        APIConnectionError              — network problem
+        APIError                        — 5xx
+        SignatureVerificationError      — webhook verification failed
+
+API docs:
+    https://fractalai.net.co/docs/fractalpay
+"""
+
+from fractalpay.client import FractalPay
+from fractalpay.errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    FractalPayError,
+    InvalidRequestError,
+    RateLimitError,
+    SignatureVerificationError,
+)
+from fractalpay.types import (
+    PaymentChain,
+    PaymentCurrency,
+    PaymentIntent,
+    PaymentStatus,
+)
+from fractalpay.webhook import WebhookEvent, verify_webhook
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Client
+    "FractalPay",
+    # Webhook
+    "verify_webhook",
+    "WebhookEvent",
+    # Types
+    "PaymentIntent",
+    "PaymentChain",
+    "PaymentCurrency",
+    "PaymentStatus",
+    # Errors
+    "FractalPayError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "APIConnectionError",
+    "APIError",
+    "SignatureVerificationError",
+    "__version__",
+]