Metadata-Version: 2.4
Name: walletdna
Version: 1.0.0
Summary: Official WalletDNA SDK — wallet screening (allow / review / block), batch screening, and signed webhook verification.
Author: WalletDNA
License: MIT
Project-URL: Homepage, https://walletdna.com/developer
Project-URL: Documentation, https://walletdna.com/docs/api
Project-URL: Source, https://github.com/wallet-dna/walletdna
Keywords: walletdna,wallet,screening,sanctions,ofac,aml,crypto,compliance,webhooks
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# walletdna (Python)

Official Python SDK for the [WalletDNA](https://walletdna.com) API — screen any wallet for sanctions and high‑risk exposure, get a clear **allow / review / block** decision, and verify signed webhooks. Standard library only, no dependencies.

API access requires an **Advanced** or **Enterprise** plan. Create an API key at <https://walletdna.com/developer>.

## Install

```sh
pip install walletdna
```

Requires Python 3.8+.

## Screen a wallet

```python
import os
from walletdna import WalletDNA

wdna = WalletDNA(os.environ["WALLETDNA_API_KEY"])

verdict = wdna.screen("0x722122dF12D4e14e13Ac3b6895a86e84145b6967")
print(verdict["decision"])  # "allow" | "review" | "block"

if verdict["decision"] == "block":
    ...  # reject the deposit / withdrawal
```

### Custom thresholds & auto‑monitoring

```python
verdict = wdna.screen(
    address,
    thresholds={"review": 40, "block": 75},  # map riskScore -> decision (sanctioned always blocks)
    monitor=True,                              # also watch this wallet and webhook me on changes
)
```

### Batch (up to 25 addresses)

```python
resp = wdna.screen_batch([addr_a, addr_b, addr_c])
blocked = [r for r in resp["results"] if r.get("decision") == "block"]
```

## Webhooks

Register an endpoint (the signing secret is returned **once** — store it):

```python
hook = wdna.create_webhook(
    "https://api.acme.com/walletdna",
    events=["wallet.risk_changed", "wallet.sanctioned"],
)
secret = hook["secret"]
```

Verify incoming events with the raw request body and the `WalletDNA-Signature` header (Flask example):

```python
from flask import Flask, request, abort
from walletdna import verify_webhook

app = Flask(__name__)

@app.post("/walletdna")
def walletdna_webhook():
    raw = request.get_data(as_text=True)
    if not verify_webhook(raw, request.headers.get("WalletDNA-Signature", ""), WDNA_WEBHOOK_SECRET):
        abort(400)
    event = request.get_json()
    # event["type"], event["data"] (a screening verdict + previousScore/label/reportUrl)
    return "", 200
```

## Errors

Failed requests raise `WalletDNAError` with `.status`, `.code`, and `.body`. A `429` means you've hit your monthly API limit — add credits in the dashboard.

## Reference

Full OpenAPI spec: <https://walletdna.com/api/openapi> · Docs: <https://walletdna.com/docs/api>
