Metadata-Version: 2.4
Name: dwsdk
Version: 1.0.0
Summary: Official async Python SDK for D-Wallet
Keywords: dwallet,discord,litecoin,ltc,dltc,payments,asyncio
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Programming Language :: Python :: 3
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.11
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.9

# D-Wallet Python SDK

Official asynchronous Python SDK for D-Wallet.

**SDK version:** `1.0.0`  
**Import package:** `dwallet`  
**Production API:** `https://api.dwallet.online`

## Installation

After the public PyPI upload:

```bash
pip install dwsdk
```

Python 3.11 or newer is required.

## Configuration

Create a D-Wallet Developer Application and API Key, then keep the key outside source code.

```env
DWALLET_API_KEY=dwk_live_...
DWALLET_BASE_URL=https://api.dwallet.online
DWALLET_TIMEOUT_SECONDS=15
```

`DWALLET_BASE_URL` is optional. `DWalletClient.from_env()` defaults to the production HTTPS API.

## Quick Start

```python
import asyncio
from dwallet import DWalletClient

async def main():
    async with DWalletClient.from_env() as client:
        user = client.for_user("123456789012345678")
        balance = await user.balance()

        print("LTC available:", balance["available"])
        print("LTC total:", balance["total"])

asyncio.run(main())
```

## Wallet APIs

The SDK currently exposes public wallet operations including:

- wallet information
- LTC balance
- LTC receive address
- transaction history
- wallet creation
- Tip / Send Intent creation and Intent read/cancel
- DLTC market/balance/history
- merchant Payment create/read/cancel

Public API-key scopes are still enforced server-side.

## DLTC

```python
async with DWalletClient.from_env() as client:
    market = await client.dltc_market(interval="5m", limit=288)

    user = client.for_user("123456789012345678")
    balance = await user.dltc_balance()
    history = await user.dltc_history(limit=30)
```

The public SDK does not directly execute a DLTC Swap.

## Merchant Payments

A Developer Application can create a Payment request for LTC or DLTC.

```python
async with DWalletClient.from_env() as client:
    payment = await client.create_payment(
        payer_discord_user_id="123456789012345678",
        asset="LTC",
        amount="0.01000000",
        idempotency_key="order-1001",
        merchant_reference="ORDER-1001",
        description="Example order",
    )

    print(payment["payment_id"])
    print(payment["status"])
```

Or through the user facade:

```python
user = client.for_user("123456789012345678")

payment = await user.create_payment(
    asset="DLTC",
    amount="25.00000000",
    idempotency_key="order-1002",
)
```

Payment public operations are intentionally limited to:

```text
create
read
cancel
```

The payer approves the Payment through the **official D-Wallet Discord Bot**. The public SDK has no confirm/execute/settle/refund method.

## Tip / Send Intents

Tip and Send are Intent-based. Creating an Intent does not directly move funds. The final execution remains behind the D-Wallet confirmation flow.

## Error handling

Typed SDK errors include:

```python
from dwallet import (
    DWalletAPIError,
    DWalletUnauthorizedError,
    DWalletForbiddenError,
    DWalletNotFoundError,
    DWalletConflictError,
    DWalletRateLimitError,
    DWalletServerError,
    DWalletTransportError,
)
```

The API key is redacted from `repr()` and SDK errors.

## Rate limits

After a request, the latest server-provided quota metadata is available from:

```python
client.last_rate_limit
```

The SDK never increases or bypasses server-side limits.

## Security boundary

The public SDK intentionally does **not** expose:

- Litecoin Core RPC
- wallet private keys or seed phrases
- xpriv/xpub material
- Treasury control
- administrative balance adjustment
- forced withdrawals
- Payment confirmation/execution/settlement/refund
- Tip/Send confirmation bypass
- direct privileged internal database access

Remote plain HTTP endpoints are rejected by the SDK. HTTP is allowed only for loopback development endpoints.

## Package naming

The PyPI distribution name and Python import package are intentionally different:

```text
pip install dwsdk
import dwallet
```

PyPI publication itself is performed separately after the release package is reviewed.
