Metadata-Version: 2.4
Name: kaleidoswap-sdk
Version: 0.5.0
Summary: Python SDK for the Kaleidoswap protocol - Trade RGB assets on Lightning Network
Project-URL: Homepage, https://kaleidoswap.com
Project-URL: Documentation, https://docs.kaleidoswap.com
Project-URL: Repository, https://github.com/kaleidoswap/kaleido-sdk
Author-email: Kaleidoswap <dev@kaleidoswap.com>
License-Expression: MIT
Keywords: bitcoin,lightning,rgb,sdk,swap,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: attrs>=23.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic[email]>=2.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: openapi-python-client>=0.21.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Kaleidoswap Python SDK

Pure Python SDK for interacting with the Kaleidoswap protocol. Trade RGB assets on Lightning Network with ease.

## Installation

```bash
pip install kaleidoswap-sdk
```

Or with development dependencies:

```bash
pip install kaleidoswap-sdk[dev]
```

## Quick Start

```python
import asyncio
from kaleidoswap_sdk import KaleidoClient

async def main():
    # Create client
    client = KaleidoClient.create(
        base_url="https://api.kaleidoswap.com"
    )

    async with client:
        # List available assets
        assets = await client.maker.list_assets()
        for asset in assets.assets:
            print(f"{asset.ticker}: {asset.name}")

        # Get trading pairs
        pairs = await client.maker.list_pairs()
        for pair in pairs.pairs:
            print(f"{pair.base.ticker}/{pair.quote.ticker}")

asyncio.run(main())
```

## Features

- **Async-first design** - All API methods are async using `asyncio`
- **Type-safe** - Full type hints with Pydantic models
- **Feature parity** - Matches the TypeScript SDK 1-to-1

### MakerClient (Market Operations)

```python
# List assets
assets = await client.maker.list_assets()

# List trading pairs
pairs = await client.maker.list_pairs()

# Get a quote
quote = await client.maker.get_quote(PairQuoteRequest(...))

# Create swap order
order = await client.maker.create_swap_order(CreateSwapOrderRequest(...))

# Get order status
status = await client.maker.get_swap_order_status(SwapOrderStatusRequest(...))

# LSP operations
lsp_info = await client.maker.get_lsp_info()
```

### RlnClient (RGB Lightning Node Operations)

Requires `node_url` configuration:

```python
client = KaleidoClient.create(
    base_url="https://api.kaleidoswap.com",
    node_url="http://localhost:3000"
)

# Node info
info = await client.rln.get_node_info()

# BTC operations
balance = await client.rln.get_btc_balance()
address = await client.rln.get_address()

# RGB asset operations
assets = await client.rln.list_assets()
await client.rln.send_asset(SendAssetRequest(...))

# Lightning channels
channels = await client.rln.list_channels()
await client.rln.open_channel(OpenChannelRequest(...))

# Payments
await client.rln.send_payment(SendPaymentRequest(...))
```

### WebSocket Streaming

```python
# Enable WebSocket
ws = client.maker.enable_websocket("wss://api.kaleidoswap.com/ws")

# Stream quotes
unsubscribe = await client.maker.stream_quotes(
    from_asset="BTC",
    to_asset="USDT",
    from_amount=100000,
    from_layer=Layer.BTC_LN,
    to_layer=Layer.RGB_LN,
    on_update=lambda quote: print(quote),
)

# Later: stop streaming
unsubscribe()
ws.disconnect()
```

## Utility Functions

```python
from kaleidoswap_sdk import to_smallest_units, to_display_units

# Convert BTC to satoshis
sats = to_smallest_units(1.5, 8)  # 150000000

# Convert satoshis to BTC
btc = to_display_units(150000000, 8)  # 1.5
```

## Error Handling

```python
from kaleidoswap_sdk import (
    KaleidoError,
    APIError,
    ValidationError,
    NotFoundError,
    NodeNotConfiguredError,
)

try:
    quote = await client.maker.get_quote(request)
except ValidationError as e:
    print(f"Invalid request: {e}")
except NotFoundError as e:
    print(f"Resource not found: {e}")
except APIError as e:
    print(f"API error ({e.status_code}): {e}")
except KaleidoError as e:
    print(f"SDK error: {e}")
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=kaleidoswap_sdk

# Type checking
mypy kaleidoswap_sdk

# Linting
ruff check kaleidoswap_sdk
```

## License

MIT
