Metadata-Version: 2.5
Name: whollycrypto
Version: 1.0.0
Summary: Lightweight Python SDK for the Wholly Crypto self-hosted merchant API.
Project-URL: Homepage, https://www.whollycrypto.com
Project-URL: Documentation, https://github.com/whollycrypto-com/whollycrypto-python-sdk#readme
Project-URL: Source, https://github.com/whollycrypto-com/whollycrypto-python-sdk
Project-URL: Issues, https://github.com/whollycrypto-com/whollycrypto-python-sdk/issues
Project-URL: Changelog, https://github.com/whollycrypto-com/whollycrypto-python-sdk/blob/main/CHANGELOG.md
Author: Wholly Crypto
License-Expression: MIT
License-File: LICENSE
Keywords: bitcoin,crypto,lightning,merchant,payments,sdk,whollycrypto
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Wholly Crypto Python SDK

The official Python client for your **self-hosted Wholly Crypto merchant API**.
Create invoices, check payments, manage accepted assets and verify IPN/webhooks.

Python **3.10+**. Standard library only, with **no runtime dependencies**.
SDK **1.0.0** targets API **v1**, tested against merchant **3.5.0**.
SDK and merchant versions are independent.

## Install

```bash
python -m pip install whollycrypto
```

Use a virtual environment for your application. Import the package as `whollycrypto`.

## Create an invoice

Use **your installation's API domain**, not its merchant-console or checkout domain.
Create a credential in **Settings → API access** with read/write access to the project.

Find both UUIDs under **Project → Stores → select store → Basic → API IDs**.
Copy **Project API ID** and **Store API ID**, not the readable project/store identifiers.
Projects and stores are created in the console; the public API does not list or create them.

```python
import os
from whollycrypto import Client

# Persist this key AND the exact payload with your order before the request.
# Reuse the same key, credential and payload if the response is lost.
idempotency_key = "order-1042-payment-attempt-1"

with Client("https://api.your-domain.com", os.environ["WHOLLY_API_TOKEN"]) as client:
    result = client.create_invoice(
        "11111111-1111-4111-8111-111111111111",  # Your Project API ID
        "22222222-2222-4222-8222-222222222222",  # Your Store API ID
        {
            "amount": "49.90",  # A string, never a float
            "currency": "EUR",
            "order_id": "order-1042",
            "email": "customer@example.com",
            "description": "Annual plan",
            "ipn_url": "https://your-shop.com/wholly/ipn",
            "redirect_url": "https://your-shop.com/orders/1042",
            "cancel_url": "https://your-shop.com/cart",
        },
        idempotency_key=idempotency_key,
    )

public_invoice_id = result["data"]["public_id"]
checkout_url = result["links"]["checkout"]
```

The UUIDs above are placeholders. Return `checkout_url` to your customer, or redirect
from your server. Never put an API token in browser JavaScript, HTML, checkout URLs
or source control. A return/success URL is **not proof of payment**.

Every API method returns the **complete response envelope**. Fields such as `data`,
`links`, `pagination` and reconciliation's separate top-level fields are preserved.
The SDK does not rename fields or round amounts. JSON fractional numbers decode as
`decimal.Decimal`; monetary strings and arbitrarily large JSON integers stay exact.

## Check and list payments

Reuse one client per worker/request context, then close it. The default transport
reuses its HTTPS connection. Calls are synchronous; run them outside an async event
loop or in a thread worker. Do not share a client across concurrent workers, because
`last_response` describes its most recent call.

```python
invoice = client.get_invoice(project_id, public_invoice_id)["data"]
if invoice["status"] == "settled":
    # Match the stored order, amount/currency and project/store first.
    # Fulfil exactly once using your database's transaction/idempotency mechanism.
    pass

page = client.list_invoices(project_id, {
    "store_id": store_id, "status": "settled", "search": "order-1042",
    "limit": 50, "offset": 0,
})

for invoice in client.iter_invoices(project_id, {"status": "settled"}):
    # Each next page is requested only when needed.
    pass
```

These snippets use an open `client`. Invoice paths use `public_id`, **not** internal
`id` or `order_id`. `processing` is not `settled`. Pages are separate snapshots, so
deduplicate by public invoice ID if exporting while new invoices are arriving.

## Amounts and invoice options

Amount, spread, tolerance and fixed token prices accept plain decimal strings or
`Decimal`. Floats are rejected for these fields. `Decimal` values are encoded as
plain strings without exponent notation. Other request values use normal JSON types.

```python
from decimal import Decimal

payload = {
    "amount": Decimal("25.00"),
    "currency": "USD",
    "exchange_rate_spread_percent": "0.5",
    "underpayment_tolerance_percent": "1",
    "expires_in_seconds": 900,
    "language": "de",
    "metadata": {
        "firstname": "Ada", "lastname": "Lovelace",
        "street": "12 Example Street", "street2": "Suite 2", "zip": "10115",
        "city": "Berlin", "country": "Germany", "countryiso2": "DE",
        "company": "Example GmbH", "vatid": "DE123456789",
    },
    "checkout_appearance": {
        "title": "Complete your order", "intro": "Thanks for choosing us.",
        "outro": "Questions? https://your-shop.com/help",
        "intro_font_size": 18, "outro_font_size": 16,
        "theme": "light", "accent_color": "#1768CE",
    },
}
```

Omitted options inherit store settings. Use `{}` for objects, not `[]`.
An empty `checkout_appearance` object freezes the resolved store design for that
invoice; omitting it keeps normal store appearance behavior. Appearance accepts
structured settings, not arbitrary HTML, JavaScript or CSS. The server remains
authoritative for currencies, allowed assets, confirmation policy and validation.

Request object keys are sorted for deterministic bytes. List order, strings and
decimal precision are preserved. Never switch SDKs/encodings during an invoice retry:
the server binds idempotency to the original credential and **exact raw JSON bytes**.
`Client.new_idempotency_key()` generates a key; you must persist it before use.

## Merchant API methods

| Method | Purpose |
| --- | --- |
| `service_info()` / `health()` | Public service/health; no token sent |
| `create_invoice(project, store, payload, idempotency_key)` | Create or safely replay an invoice |
| `get_invoice(project, public_id)` | Private invoice detail and current checkout link |
| `list_invoices(project, filters)` / `iter_invoices(project, filters)` | Search and paginate invoices |
| `list_project_payment_assets(project)` | Native/token policies and readiness |
| `update_project_payment_asset(project, asset, policy)` | Update a project asset policy |
| `list_token_candidates(project, chain_slug, filters)` | Search catalog tokens with `q` and `limit` |
| `register_token_asset(project, token)` | Verify/register a catalog token |
| `discover_custom_dex_pools(project, chain_slug, contract)` | Discover supported DEX pricing candidates |
| `register_custom_token(project, token)` | Verify/register a custom contract or mint |
| `list_store_payment_assets(project, store)` | Accepted on-chain assets and separate Lightning readiness |
| `update_store_payment_assets(project, store, assets)` | **Replace** the entire on-chain selection |
| `update_store_confirmation_policy(project, store, asset, policy)` | Inherit or override confirmations |
| `list_project_wallets(project)` | Public addresses and balances; no keys |
| `list_reconciliation(project, filters)` | Needs-attention queue, fixed 25 cases per page |
| `get_reconciliation(project, public_id, page=1)` | Detail and paginated decision history |

IDs accept strings or `uuid.UUID`. See the
[full API reference](https://www.whollycrypto.com/api/) and
[payment-method examples](https://github.com/whollycrypto-com/whollycrypto-python-sdk/blob/main/docs/payment-methods.md).

`update_store_payment_assets()` receives the list itself, not an `assets` wrapper.
`[]` removes **all on-chain selections**. It does not configure Lightning.
Refunds, sends, reconciliation decisions, accounts, exchange credentials and Lightning
configuration are console-only; the SDK does not invent public routes for them.

## Verify IPN and webhooks

Both use the same signature format. Use the **IPN/webhook signing secret** from
the store configuration, not an API token. Pass the exact raw body as `bytes`.

```python
from whollycrypto import InvalidSignatureError, parse_notification

try:
    notice = parse_notification(raw_body, request_headers, signing_secret)
except InvalidSignatureError:
    # Return HTTP 400 without logging secrets or the customer's payload.
    raise

# Durably enqueue before returning 2xx. Failed storage must not be acknowledged.
# Persist (configured_project_id, notice.invoice_id, notice.sequence) for deduplication.
# Your worker re-fetches the invoice through the authenticated client before fulfilment.
```

Verification uses HMAC-SHA256 and a constant-time comparison, with a five-minute
past/future clock window. Keep your server clock synchronized. `verify_signature()`
is also available for signature-only checks. `parse_notification()` additionally
validates UUIDs, status and sequence, then returns a readonly `Notification` payload.
`notice.invoice_id` is the **public** invoice UUID.

Signatures cover the timestamp and raw body, **not** event/delivery ID headers.
Do not deduplicate using event ID alone: changing it must not let an attacker
bypass replay protection, and a forged collision must not suppress a different
signed invoice. Use the signed invoice ID and sequence, scoped to your configured
project. Keep invoice state monotonic and re-check the authenticated invoice.
Event names are not sent in the payload or headers.

The [WSGI inbox example](https://github.com/whollycrypto-com/whollycrypto-python-sdk/blob/main/examples/webhook_wsgi.py)
verifies before storage, queues durably in private SQLite, handles duplicates and
does not acknowledge failed writes. It does **not** fulfil orders or start a web
server. Mount it behind your application's HTTPS server and implement an idempotent
worker. The example's private filesystem checks target Linux/POSIX deployments.

## Errors, timeouts and retries

```python
from whollycrypto import APIError, Client, Options, TransportError

client = Client("https://api.your-domain.com", token, options=Options(
    timeout_seconds=20, connect_timeout_seconds=5,
    max_retries=1, max_retry_delay_seconds=30,
))
try:
    result = client.get_invoice(project_id, public_invoice_id)
except APIError as error:
    status = error.status_code
    code = error.error_code
    retry_after = error.retry_after  # Seconds or None
    # error.api_message / error.response.body are opt-in private details, not log text.
except TransportError:
    # A timeout does NOT prove invoice creation failed.
    # Retry its original payload with the same stored key and credential.
    pass
finally:
    client.close()
```

Retries are **off by default**. With retries enabled, only GETs and invoice creation
with its explicit key can retry transient connections or HTTP 429/502/503/504.
Other writes never retry automatically. Retries reuse the immutable request and
honor `Retry-After` seconds or a standard HTTP date. Invalid headers or waits longer
than the configured limit are surfaced to your queue, never retried early.
At most three retries can be enabled. Include attempts/backoff in your worker budget;
network timeouts depend on the operating system's DNS/socket behavior.

`client.last_response.rate_limit()` returns `limit`, `remaining` and `reset` headers
when present. `last_response` is `None` if the most recent attempted request has no
HTTP response. The default limit is 8 MiB per response and 32 KiB per merchant request.

TLS verification is always enabled. No automatic redirects, cookie storage, proxy
environment discovery or `.netrc` lookup. `Options(ca_file="/path/to/ca.pem")` can
trust your private CA without disabling hostname verification. A custom transport
receives credentials and must be trusted. Closing a client closes its default
transport; injected/shared transports remain caller-owned.

Repr and normal SDK exception messages omit credentials and response bodies.
Python debuggers can still inspect private attributes and frame locals: disable
local-variable/body capture in production error monitoring and never pickle clients.

## Public checkout and Lightning

```python
from whollycrypto import CheckoutClient

with CheckoutClient("https://pay.your-domain.com") as checkout:
    view = checkout.get_invoice(public_invoice_id)
    url = checkout.invoice_url(public_invoice_id)
```

This separate reader never holds or sends a merchant API token. It also exposes
`get_preview(project, store=None)` and `preview_url(project, store=None, state="waiting")`.
Preview states are illustrative, not evidence of payment. Use the QR and image URLs
returned by checkout JSON instead of reconstructing them.

Preserve `payment_rail`, `asset_decimals`, destination tags/memos, `payment_uri` and
`payable`. Lightning BTC uses **11 atomic decimals (millisatoshis)**; on-chain BTC
uses 8. Its payment hash is not an on-chain address. Use the BOLT11/payment URI.
The SDK never signs or sends funds.

## Development

```bash
python -m pip install -e .
python -m unittest discover -s tests -t . -v
python -m pip install build twine
python -m build
python -m twine check dist/*
```

Tests cover all 17 merchant endpoints, validation, precision, retry identity, HTTP
connection reuse, TLS rejection, signature verification and the durable receiver.
They use only mocks/disposable loopback servers and SQLite, never live payments.
Tests require OpenSSL CLI, SSL and SQLite support. Plain HTTP is available only for
explicit `Options(allow_insecure_localhost=True)` tests on localhost/127.0.0.1/::1;
this never disables HTTPS certificate verification.

An optional Python 3.10–3.14 CI template is provided in
[ci/github-actions.yml](https://github.com/whollycrypto-com/whollycrypto-python-sdk/blob/main/ci/github-actions.yml).
Enabling it requires a maintainer with workflow-write permission. See
[maintenance notes](https://github.com/whollycrypto-com/whollycrypto-python-sdk/blob/main/docs/maintaining.md)
for API drift checks and release verification.

## License

[MIT](https://github.com/whollycrypto-com/whollycrypto-python-sdk/blob/main/LICENSE),
for this client SDK only. The merchant application and other Wholly Crypto software
have their own licenses. No server implementation or private-service code is included.
