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`)
