freezeradar 0.1.0__tar.gz

freezeradar-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.python-version
+*.log
+.DS_Store

freezeradar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreezeRadar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

freezeradar-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: freezeradar
+Version: 0.1.0
+Summary: FreezeRadar Python SDK: address freeze-risk screening for exchanges, OTC desks, and compliance teams.
+Project-URL: Homepage, https://freezeradar.com
+Project-URL: Documentation, https://freezeradar.com/developers
+Project-URL: Source, https://github.com/Freezeradar/python-sdk
+Project-URL: Issues, https://github.com/Freezeradar/python-sdk/issues
+Project-URL: OpenAPI, https://freezeradar.com/api/openapi/v1
+Author-email: FreezeRadar <mehdiraized@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aml,blacklist,compliance,freezeradar,sanctions,stablecoin,usdc,usdt
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: pydantic<3,>=2.5.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# freezeradar
+
+Python SDK for [FreezeRadar](https://freezeradar.com) wallet-risk intelligence. Exchanges, OTC desks, and compliance teams can screen freezeable-asset counterparties (USDT, USDC, PAXG, XAUt, and others) for issuer blacklists, sanctions hits, and explainable freeze-risk scores.
+
+The client talks to the live API documented at [freezeradar.com/developers](https://freezeradar.com/developers) and [GET /api/openapi/v1](https://freezeradar.com/api/openapi/v1). Models are generated from that OpenAPI document (snapshot in `openapi/v1.json`).
+
+## Install
+
+```bash
+pip install freezeradar
+```
+
+Python 3.9+. Sync and async clients use [httpx](https://www.python-httpx.org/). Types use Pydantic v2.
+
+```python
+from freezeradar import FreezeRadar, AsyncFreezeRadar, Action
+
+with FreezeRadar() as client:  # public checks; no key required
+    check = client.check_address("TBZefVsyQpzzxc2WSCLbZBECvxVdzGqdtC")
+    print(check.chain, check.blacklisted, check.sanctioned, check.matches)
+```
+
+Business API methods (`create_address_screening`, `get_report`, full `screen_*`) need a Bearer key from the Developer Console:
+
+```bash
+export FREEZERADAR_API_KEY=fr_live_...
+# optional
+export FREEZERADAR_BASE_URL=https://freezeradar.com
+```
+
+```python
+client = FreezeRadar(api_key="fr_live_...")  # or from the environment
+```
+
+## Quick start
+
+```python
+from freezeradar import FreezeRadar, Thresholds
+
+client = FreezeRadar(
+    thresholds=Thresholds(block_score=75, review_score=40, high_value_amount=25_000),
+)
+
+# Fast path: issuer blacklist + sanctions (public, IP rate-limited)
+check = client.check_address("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", chain="ethereum")
+
+# Batch (sequential sync / concurrent async). Same public endpoints.
+results = client.check_addresses([
+    "TBZefVsyQpzzxc2WSCLbZBECvxVdzGqdtC",
+    {"address": "0x0000000000000000000000000000000000000000", "chain": "ethereum"},
+])
+
+# Withdrawal / deposit policy: allow | review | block
+decision = client.screen_withdrawal(
+    "TLXDJUauN4vgN75tJtCbXiAm4mQaDTmTNY",
+    asset="USDT",
+    amount=12_000,
+)
+if decision.action.value == "block":
+    raise SystemExit(decision.reasons)
+
+# Full scored report (Business API key, async job, polled)
+job = client.create_address_screening("0x...", "ethereum", assets=["USDT"])
+report = client.get_report(job.id)  # waits until COMPLETED / FAILED
+```
+
+Async:
+
+```python
+async with AsyncFreezeRadar() as client:
+    checks = await client.check_addresses(addresses, max_concurrency=5)
+    decision = await client.screen_deposit(from_address, asset="USDC", amount=500)
+```
+
+## CLI
+
+```bash
+freezeradar check TBZefVsyQpzzxc2WSCLbZBECvxVdzGqdtC
+freezeradar check 0x... --chain ethereum --json --decide
+freezeradar screen-file examples/addresses.csv --out results.csv
+```
+
+CSV columns: `address` (required), optional `chain`, `asset`, `amount`, `direction` (`withdrawal` or `deposit`).
+
+## Endpoints used
+
+Base URL: `https://freezeradar.com` (override with `FREEZERADAR_BASE_URL` or `base_url=`).
+
+| SDK method | HTTP | Auth | Notes |
+|---|---|---|---|
+| `check_address` / `check_addresses` | `GET /api/widget/check` + `GET /api/sanctions/check` | none | Default synchronous screen. Widget is 30/min per IP; sanctions is 20/min per IP. Bitcoin uses sanctions only (no blacklist). |
+| `check_address(..., use_quick_check=True)` | `POST /api/v1/quick-check` | Bearer | **Not live yet.** If the route 404s, the SDK falls back to the public pair. |
+| `create_address_screening` | `POST /api/v1/address-screenings` | Bearer | Body: `address`, `chain`, optional `assets`, `scanMode`. |
+| `create_transaction_screening` | `POST /api/v1/transaction-screenings` | Bearer | Body: `chain`, `transactionHash`, optional `policyId`. |
+| `get_report` | `GET /api/v1/screenings/{id}` | Bearer | Polls `QUEUED` / `RUNNING` until `COMPLETED` or `FAILED`. |
+| `list_chains` | `GET /api/chains` | none | Includes bitcoin (sanctions-only). |
+| `list_assets` | `GET /api/assets` | none | |
+| `get_stats` | `GET /api/stats` | none | |
+| `list_events` | `GET /api/events` | none | |
+
+`screen_withdrawal` / `screen_deposit` always run the synchronous address check, then apply `Thresholds`. If an API key is configured (or `full=True`), they also create an address screening and wait for `get_report`. Pass `full=False` to keep the hook in the public, low-latency path.
+
+Authentication for Business routes: `Authorization: Bearer <key>`. Public routes send the header only when a key is present.
+
+Retries: 429 / 5xx / transport errors, exponential backoff, `Retry-After` honored. Rate-limit headers (`X-RateLimit-Limit|Remaining|Reset`) are stored on the client. Timeouts default to 30s.
+
+Chain detection: Tron (`T` + Base58), EVM (`0x` + 40 hex; defaults to `ethereum` unless you pass `bsc` / `polygon` / `base` / `arbitrum` / `optimism` / `avalanche`), Solana (Base58 32–44), Bitcoin (1… / 3… / bc1…, sanctions only). Explicit `chain` is validated against the address family.
+
+## Planned endpoint the main app must expose
+
+`POST /api/v1/quick-check` is **not** in the live OpenAPI spec. Enable it from the SDK with `FreezeRadar(use_quick_check=True)` or `check_address(..., use_quick_check=True)`. Until the route exists, those calls fall back to widget + sanctions.
+
+The main FreezeRadar app should add:
+
+```
+POST https://freezeradar.com/api/v1/quick-check
+Authorization: Bearer <Business API key>
+Content-Type: application/json
+
+{
+  "address": "T...",
+  "chain": "tron"
+}
+```
+
+`chain` optional when it can be detected. Response:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "address": "T...",
+    "chain": "tron",
+    "blacklisted": true,
+    "sanctioned": false,
+    "matches": [
+      { "source": "OFAC", "entityName": "...", "entitySlug": "..." }
+    ]
+  }
+}
+```
+
+That is the union of `/api/widget/check` and `/api/sanctions/check` in one authenticated, quota-metered call — the shape exchanges need for `check_address` without burning two IP rate limits. Native bulk (`POST /api/v1/address-checks` taking `{ "addresses": [...] }`) is also not published; `check_addresses` fans out to the public GETs today.
+
+There is no public PDF `get_report` route. `get_report` in this SDK is the structured `GET /api/v1/screenings/{id}` object.
+
+## Decisions
+
+`Thresholds` (all overridable):
+
+| Field | Default | Effect |
+|---|---|---|
+| `block_if_blacklisted` | `True` | Issuer blacklist → block |
+| `block_if_sanctioned` | `True` | Sanctions match → block |
+| `block_score` | `75` | `overallRisk` ≥ this → block |
+| `review_score` | `40` | `overallRisk` ≥ this → review |
+| `block_categories` | `HIGH`, `CRITICAL` | |
+| `review_categories` | `MEDIUM` | |
+| `high_value_amount` | unset | If `amount` ≥ this, use `high_value_review_score` |
+| `high_value_review_score` | `25` | |
+
+Transaction screening `verdict` values `CLEAR` / `REVIEW` / `BLOCK` are mapped onto the same actions when a transaction report is present.
+
+## Webhooks
+
+```python
+from freezeradar import verify_signature
+
+raw = verify_signature(request.body, request.headers, webhook_secret)
+```
+
+Signature is `sha256=` + HMAC-SHA256 of `{timestamp}.{raw_body}` using headers `x-freezeradar-timestamp` and `x-freezeradar-signature`, as documented on `/developers`. Deliveries are retried up to 5 times with backoff; dedupe on event `id` and order by timestamp.
+
+## Examples
+
+- `examples/fastapi_withdrawal.py` — FastAPI withdrawal screen that 403s on `block`
+- `examples/django_withdrawal_hook.py` — Django JSON view
+- `examples/celery_deposit_screening.py` — deposit task that holds / queues / clears a credit
+- `examples/addresses.csv` — input for `freezeradar screen-file`
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests examples
+ruff format src tests examples
+mypy
+pytest
+```
+
+CI runs that matrix on Python 3.9–3.13. The `publish.yml` workflow uses PyPI trusted publishing on GitHub Release (OIDC). It does not publish from CI on push.
+
+## What you need to do manually
+
+1. **Do not ship a real API key** in this repo. Create Business keys in the FreezeRadar Developer Console and inject `FREEZERADAR_API_KEY` at runtime.
+2. **PyPI trusted publishing:** create a PyPI project `freezeradar`, add a pending publisher for GitHub org `Freezeradar`, repo `python-sdk`, workflow `publish.yml`, environment `pypi`. Create the GitHub Environment `pypi` (optional protection rules). Then cut a GitHub Release when you actually want a package on PyPI.
+3. **Expose `POST /api/v1/quick-check`** on the main app (schema above) so `use_quick_check=True` stops falling back. Optionally add a bulk address-check route if exchange customers outgrow per-IP public GETs.
+4. **Grant this SDK repo access** to private docs if you want models regenerated from internal types rather than `/api/openapi/v1`.
+5. Results are explainable risk signals, not legal advice, AML certification, or an instruction to freeze funds.
+
+## License
+
+MIT. See `LICENSE`.

freezeradar-0.1.0/README.md

@@ -0,0 +1,203 @@
+# freezeradar
+
+Python SDK for [FreezeRadar](https://freezeradar.com) wallet-risk intelligence. Exchanges, OTC desks, and compliance teams can screen freezeable-asset counterparties (USDT, USDC, PAXG, XAUt, and others) for issuer blacklists, sanctions hits, and explainable freeze-risk scores.
+
+The client talks to the live API documented at [freezeradar.com/developers](https://freezeradar.com/developers) and [GET /api/openapi/v1](https://freezeradar.com/api/openapi/v1). Models are generated from that OpenAPI document (snapshot in `openapi/v1.json`).
+
+## Install
+
+```bash
+pip install freezeradar
+```
+
+Python 3.9+. Sync and async clients use [httpx](https://www.python-httpx.org/). Types use Pydantic v2.
+
+```python
+from freezeradar import FreezeRadar, AsyncFreezeRadar, Action
+
+with FreezeRadar() as client:  # public checks; no key required
+    check = client.check_address("TBZefVsyQpzzxc2WSCLbZBECvxVdzGqdtC")
+    print(check.chain, check.blacklisted, check.sanctioned, check.matches)
+```
+
+Business API methods (`create_address_screening`, `get_report`, full `screen_*`) need a Bearer key from the Developer Console:
+
+```bash
+export FREEZERADAR_API_KEY=fr_live_...
+# optional
+export FREEZERADAR_BASE_URL=https://freezeradar.com
+```
+
+```python
+client = FreezeRadar(api_key="fr_live_...")  # or from the environment
+```
+
+## Quick start
+
+```python
+from freezeradar import FreezeRadar, Thresholds
+
+client = FreezeRadar(
+    thresholds=Thresholds(block_score=75, review_score=40, high_value_amount=25_000),
+)
+
+# Fast path: issuer blacklist + sanctions (public, IP rate-limited)
+check = client.check_address("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", chain="ethereum")
+
+# Batch (sequential sync / concurrent async). Same public endpoints.
+results = client.check_addresses([
+    "TBZefVsyQpzzxc2WSCLbZBECvxVdzGqdtC",
+    {"address": "0x0000000000000000000000000000000000000000", "chain": "ethereum"},
+])
+
+# Withdrawal / deposit policy: allow | review | block
+decision = client.screen_withdrawal(
+    "TLXDJUauN4vgN75tJtCbXiAm4mQaDTmTNY",
+    asset="USDT",
+    amount=12_000,
+)
+if decision.action.value == "block":
+    raise SystemExit(decision.reasons)
+
+# Full scored report (Business API key, async job, polled)
+job = client.create_address_screening("0x...", "ethereum", assets=["USDT"])
+report = client.get_report(job.id)  # waits until COMPLETED / FAILED
+```
+
+Async:
+
+```python
+async with AsyncFreezeRadar() as client:
+    checks = await client.check_addresses(addresses, max_concurrency=5)
+    decision = await client.screen_deposit(from_address, asset="USDC", amount=500)
+```
+
+## CLI
+
+```bash
+freezeradar check TBZefVsyQpzzxc2WSCLbZBECvxVdzGqdtC
+freezeradar check 0x... --chain ethereum --json --decide
+freezeradar screen-file examples/addresses.csv --out results.csv
+```
+
+CSV columns: `address` (required), optional `chain`, `asset`, `amount`, `direction` (`withdrawal` or `deposit`).
+
+## Endpoints used
+
+Base URL: `https://freezeradar.com` (override with `FREEZERADAR_BASE_URL` or `base_url=`).
+
+| SDK method | HTTP | Auth | Notes |
+|---|---|---|---|
+| `check_address` / `check_addresses` | `GET /api/widget/check` + `GET /api/sanctions/check` | none | Default synchronous screen. Widget is 30/min per IP; sanctions is 20/min per IP. Bitcoin uses sanctions only (no blacklist). |
+| `check_address(..., use_quick_check=True)` | `POST /api/v1/quick-check` | Bearer | **Not live yet.** If the route 404s, the SDK falls back to the public pair. |
+| `create_address_screening` | `POST /api/v1/address-screenings` | Bearer | Body: `address`, `chain`, optional `assets`, `scanMode`. |
+| `create_transaction_screening` | `POST /api/v1/transaction-screenings` | Bearer | Body: `chain`, `transactionHash`, optional `policyId`. |
+| `get_report` | `GET /api/v1/screenings/{id}` | Bearer | Polls `QUEUED` / `RUNNING` until `COMPLETED` or `FAILED`. |
+| `list_chains` | `GET /api/chains` | none | Includes bitcoin (sanctions-only). |
+| `list_assets` | `GET /api/assets` | none | |
+| `get_stats` | `GET /api/stats` | none | |
+| `list_events` | `GET /api/events` | none | |
+
+`screen_withdrawal` / `screen_deposit` always run the synchronous address check, then apply `Thresholds`. If an API key is configured (or `full=True`), they also create an address screening and wait for `get_report`. Pass `full=False` to keep the hook in the public, low-latency path.
+
+Authentication for Business routes: `Authorization: Bearer <key>`. Public routes send the header only when a key is present.
+
+Retries: 429 / 5xx / transport errors, exponential backoff, `Retry-After` honored. Rate-limit headers (`X-RateLimit-Limit|Remaining|Reset`) are stored on the client. Timeouts default to 30s.
+
+Chain detection: Tron (`T` + Base58), EVM (`0x` + 40 hex; defaults to `ethereum` unless you pass `bsc` / `polygon` / `base` / `arbitrum` / `optimism` / `avalanche`), Solana (Base58 32–44), Bitcoin (1… / 3… / bc1…, sanctions only). Explicit `chain` is validated against the address family.
+
+## Planned endpoint the main app must expose
+
+`POST /api/v1/quick-check` is **not** in the live OpenAPI spec. Enable it from the SDK with `FreezeRadar(use_quick_check=True)` or `check_address(..., use_quick_check=True)`. Until the route exists, those calls fall back to widget + sanctions.
+
+The main FreezeRadar app should add:
+
+```
+POST https://freezeradar.com/api/v1/quick-check
+Authorization: Bearer <Business API key>
+Content-Type: application/json
+
+{
+  "address": "T...",
+  "chain": "tron"
+}
+```
+
+`chain` optional when it can be detected. Response:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "address": "T...",
+    "chain": "tron",
+    "blacklisted": true,
+    "sanctioned": false,
+    "matches": [
+      { "source": "OFAC", "entityName": "...", "entitySlug": "..." }
+    ]
+  }
+}
+```
+
+That is the union of `/api/widget/check` and `/api/sanctions/check` in one authenticated, quota-metered call — the shape exchanges need for `check_address` without burning two IP rate limits. Native bulk (`POST /api/v1/address-checks` taking `{ "addresses": [...] }`) is also not published; `check_addresses` fans out to the public GETs today.
+
+There is no public PDF `get_report` route. `get_report` in this SDK is the structured `GET /api/v1/screenings/{id}` object.
+
+## Decisions
+
+`Thresholds` (all overridable):
+
+| Field | Default | Effect |
+|---|---|---|
+| `block_if_blacklisted` | `True` | Issuer blacklist → block |
+| `block_if_sanctioned` | `True` | Sanctions match → block |
+| `block_score` | `75` | `overallRisk` ≥ this → block |
+| `review_score` | `40` | `overallRisk` ≥ this → review |
+| `block_categories` | `HIGH`, `CRITICAL` | |
+| `review_categories` | `MEDIUM` | |
+| `high_value_amount` | unset | If `amount` ≥ this, use `high_value_review_score` |
+| `high_value_review_score` | `25` | |
+
+Transaction screening `verdict` values `CLEAR` / `REVIEW` / `BLOCK` are mapped onto the same actions when a transaction report is present.
+
+## Webhooks
+
+```python
+from freezeradar import verify_signature
+
+raw = verify_signature(request.body, request.headers, webhook_secret)
+```
+
+Signature is `sha256=` + HMAC-SHA256 of `{timestamp}.{raw_body}` using headers `x-freezeradar-timestamp` and `x-freezeradar-signature`, as documented on `/developers`. Deliveries are retried up to 5 times with backoff; dedupe on event `id` and order by timestamp.
+
+## Examples
+
+- `examples/fastapi_withdrawal.py` — FastAPI withdrawal screen that 403s on `block`
+- `examples/django_withdrawal_hook.py` — Django JSON view
+- `examples/celery_deposit_screening.py` — deposit task that holds / queues / clears a credit
+- `examples/addresses.csv` — input for `freezeradar screen-file`
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests examples
+ruff format src tests examples
+mypy
+pytest
+```
+
+CI runs that matrix on Python 3.9–3.13. The `publish.yml` workflow uses PyPI trusted publishing on GitHub Release (OIDC). It does not publish from CI on push.
+
+## What you need to do manually
+
+1. **Do not ship a real API key** in this repo. Create Business keys in the FreezeRadar Developer Console and inject `FREEZERADAR_API_KEY` at runtime.
+2. **PyPI trusted publishing:** create a PyPI project `freezeradar`, add a pending publisher for GitHub org `Freezeradar`, repo `python-sdk`, workflow `publish.yml`, environment `pypi`. Create the GitHub Environment `pypi` (optional protection rules). Then cut a GitHub Release when you actually want a package on PyPI.
+3. **Expose `POST /api/v1/quick-check`** on the main app (schema above) so `use_quick_check=True` stops falling back. Optionally add a bulk address-check route if exchange customers outgrow per-IP public GETs.
+4. **Grant this SDK repo access** to private docs if you want models regenerated from internal types rather than `/api/openapi/v1`.
+5. Results are explainable risk signals, not legal advice, AML certification, or an instruction to freeze funds.
+
+## License
+
+MIT. See `LICENSE`.

freezeradar-0.1.0/examples/addresses.csv

@@ -0,0 +1,4 @@
+address,chain,asset,amount,direction
+TBZefVsyQpzzxc2WSCLbZBECvxVdzGqdtC,tron,USDT,25000,withdrawal
+TLXDJUauN4vgN75tJtCbXiAm4mQaDTmTNY,tron,USDT,1000,deposit
+0x0000000000000000000000000000000000000000,ethereum,USDC,50,withdrawal

freezeradar-0.1.0/examples/celery_deposit_screening.py

@@ -0,0 +1,61 @@
+"""Celery task that screens a deposit sender before crediting a balance.
+
+Run the worker with ``FREEZERADAR_API_KEY`` set if you want full Business
+API reports (``full=True``). Public blacklist/sanctions checks work without a key.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from freezeradar import Action, FreezeRadar, Thresholds
+
+# from celery import shared_task
+
+client = FreezeRadar(
+    thresholds=Thresholds(block_score=80, review_score=35, high_value_amount=25_000),
+)
+
+
+def screen_deposit_task(
+    from_address: str,
+    asset: str = "USDT",
+    amount: Optional[float] = None,
+    chain: Optional[str] = None,
+    credit_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Replace with ``@shared_task`` in a real Celery app."""
+    decision = client.screen_deposit(
+        from_address,
+        asset=asset,
+        amount=amount,
+        chain=chain,
+        full=False,
+    )
+    result = {
+        "credit_id": credit_id,
+        "action": decision.action.value,
+        "reasons": decision.reasons,
+        "chain": decision.chain,
+        "blacklisted": decision.blacklisted,
+        "sanctioned": decision.sanctioned,
+        "overall_risk": decision.overall_risk,
+    }
+    if decision.action is Action.BLOCK:
+        # Hold the credit and open a compliance case.
+        result["credit_status"] = "held"
+    elif decision.action is Action.REVIEW:
+        result["credit_status"] = "pending_review"
+    else:
+        result["credit_status"] = "clear"
+    return result
+
+
+try:
+    from celery import shared_task  # type: ignore[import-not-found]
+
+    screen_incoming_deposit = shared_task(name="freezeradar.screen_incoming_deposit")(
+        screen_deposit_task
+    )
+except ImportError:
+    screen_incoming_deposit = screen_deposit_task

freezeradar-0.1.0/examples/django_withdrawal_hook.py

@@ -0,0 +1,43 @@
+"""Django withdrawal screening view.
+
+Wire this into your withdrawals app. The SDK is the only FreezeRadar dependency;
+Django itself is assumed to already be installed in that service.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from freezeradar import Action, FreezeRadar, Thresholds
+
+client = FreezeRadar(
+    thresholds=Thresholds(block_if_blacklisted=True, block_if_sanctioned=True),
+)
+
+
+def screen_withdrawal_view(request: Any) -> Any:
+    # from django.http import JsonResponse
+    from django.http import JsonResponse  # type: ignore[import-not-found]
+
+    if request.method != "POST":
+        return JsonResponse({"error": "POST required"}, status=405)
+    body = json.loads(request.body.decode("utf-8"))
+    decision = client.screen_withdrawal(
+        body["to_address"],
+        asset=body.get("asset", "USDT"),
+        amount=float(body.get("amount", 0)),
+        chain=body.get("chain"),
+        full=False,
+    )
+    status = 200 if decision.action is not Action.BLOCK else 403
+    return JsonResponse(
+        {
+            "action": decision.action.value,
+            "reasons": decision.reasons,
+            "chain": decision.chain,
+            "blacklisted": decision.blacklisted,
+            "sanctioned": decision.sanctioned,
+        },
+        status=status,
+    )

freezeradar-0.1.0/examples/fastapi_withdrawal.py

@@ -0,0 +1,48 @@
+"""FastAPI withdrawal hook.
+
+Install extras in your service: ``pip install freezeradar fastapi``
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+from freezeradar import Action, FreezeRadar, Thresholds
+
+app = FastAPI()
+client = FreezeRadar(
+    thresholds=Thresholds(block_score=75, review_score=40, high_value_amount=50_000),
+)
+
+
+class WithdrawalRequest(BaseModel):
+    to_address: str
+    asset: str = "USDT"
+    amount: float
+    chain: Optional[str] = None
+
+
+@app.post("/withdrawals/screen")
+def screen_withdrawal(body: WithdrawalRequest) -> dict[str, object]:
+    decision = client.screen_withdrawal(
+        body.to_address,
+        asset=body.asset,
+        amount=body.amount,
+        chain=body.chain,
+        full=False,
+    )
+    if decision.action is Action.BLOCK:
+        raise HTTPException(
+            status_code=403,
+            detail={"action": decision.action.value, "reasons": decision.reasons},
+        )
+    return {
+        "action": decision.action.value,
+        "reasons": decision.reasons,
+        "chain": decision.chain,
+        "blacklisted": decision.blacklisted,
+        "sanctioned": decision.sanctioned,
+    }