kaleido-sdk 0.1.0__tar.gz

kaleido_sdk-0.1.0/.gitignore

@@ -0,0 +1,120 @@
+target/
+
+# Node.js
+node_modules/
+
+# TypeScript SDK build artifacts
+typescript-sdk/dist/
+typescript-sdk/coverage/
+typescript-sdk/*.js
+typescript-sdk/*.js.map
+typescript-sdk/*.d.ts
+!typescript-sdk/jest.config.js
+!typescript-sdk/.eslintrc.js
+
+# NAPI-RS build artifacts (Node.js native modules)
+*.node
+!node_modules/**/*.node
+
+# Lock files - only pnpm is used
+package-lock.json
+npm-shrinkwrap.json
+
+
+# Package.json filtering
+package-lock.json
+!crates/*/package.json
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+!typescript/packages/*/src/lib/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+test-results.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# Sphinx documentation
+docs/_build/
+
+# pyenv
+.python-version 
+
+# Log files
+*.log
+*.log.*
+logs/
+log/ 
+
+*.pyc
+__pycache__/
+*.DS_Store
+
+# Generated spec snapshots
+specs/backup/

kaleido_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: kaleido-sdk
+Version: 0.1.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: httpx>=0.27.0
+Requires-Dist: pydantic[email]>=2.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator[ruff]>=0.54.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'
+Description-Content-Type: text/markdown
+
+# Kaleidoswap Python SDK
+
+[![pypi package](https://img.shields.io/pypi/v/kaleido-sdk?label=pypi%20package)](https://pypi.org/project/kaleido-sdk/)
+
+Python SDK for trading RGB assets on the Lightning Network via the Kaleidoswap protocol.
+
+## Installation
+
+```bash
+pip install kaleido-sdk
+```
+
+## Quick Start
+
+The SDK exposes two sub-clients depending on what you need:
+
+| Sub-client | Config key | What it does |
+|---|---|---|
+| `client.maker` | `base_url` | Kaleidoswap market API — assets, quotes, swap orders, LSP |
+| `client.rln` | `node_url` | Your RGB Lightning Node — wallet, channels, payments, RGB assets |
+
+```python
+from kaleido_sdk import KaleidoClient
+
+# Zero-config — defaults to regtest
+client = KaleidoClient.create()
+assets = await client.maker.list_assets()
+
+# Maker API only
+client = KaleidoClient.create(base_url="https://api.kaleidoswap.com")
+assets = await client.maker.list_assets()
+
+# Node only (base_url still defaults to regtest)
+client = KaleidoClient.create(node_url="http://localhost:3001")
+info = await client.rln.get_node_info()
+
+# Both together
+client = KaleidoClient.create(
+    base_url="https://api.kaleidoswap.com",
+    node_url="http://localhost:3001",
+)
+pairs    = await client.maker.list_pairs()
+channels = await client.rln.list_channels()
+```
+
+## Documentation
+
+Full usage guide, API reference, and examples at **https://docs.kaleidoswap.com/sdk/introduction**
+
+## License
+
+MIT

kaleido_sdk-0.1.0/README.md

@@ -0,0 +1,52 @@
+# Kaleidoswap Python SDK
+
+[![pypi package](https://img.shields.io/pypi/v/kaleido-sdk?label=pypi%20package)](https://pypi.org/project/kaleido-sdk/)
+
+Python SDK for trading RGB assets on the Lightning Network via the Kaleidoswap protocol.
+
+## Installation
+
+```bash
+pip install kaleido-sdk
+```
+
+## Quick Start
+
+The SDK exposes two sub-clients depending on what you need:
+
+| Sub-client | Config key | What it does |
+|---|---|---|
+| `client.maker` | `base_url` | Kaleidoswap market API — assets, quotes, swap orders, LSP |
+| `client.rln` | `node_url` | Your RGB Lightning Node — wallet, channels, payments, RGB assets |
+
+```python
+from kaleido_sdk import KaleidoClient
+
+# Zero-config — defaults to regtest
+client = KaleidoClient.create()
+assets = await client.maker.list_assets()
+
+# Maker API only
+client = KaleidoClient.create(base_url="https://api.kaleidoswap.com")
+assets = await client.maker.list_assets()
+
+# Node only (base_url still defaults to regtest)
+client = KaleidoClient.create(node_url="http://localhost:3001")
+info = await client.rln.get_node_info()
+
+# Both together
+client = KaleidoClient.create(
+    base_url="https://api.kaleidoswap.com",
+    node_url="http://localhost:3001",
+)
+pairs    = await client.maker.list_pairs()
+channels = await client.rln.list_channels()
+```
+
+## Documentation
+
+Full usage guide, API reference, and examples at **https://docs.kaleidoswap.com/sdk/introduction**
+
+## License
+
+MIT

kaleido_sdk-0.1.0/examples/01_hello.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Example 01: Hello Kaleidoswap
+
+Basic example showing how to create a client and list assets.
+"""
+
+import asyncio
+import logging
+import os
+
+from kaleido_sdk import KaleidoClient, get_sdk_name, get_version
+
+API_URL = os.getenv("KALEIDO_API_URL", "https://api.staging.kaleidoswap.com")
+
+# ---------------------------------------------------------------------------
+# Logging setup (application's responsibility — the SDK never does this)
+# ---------------------------------------------------------------------------
+# Show all SDK log levels. Change to logging.INFO or logging.WARNING to reduce noise.
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)-8s] %(name)s — %(message)s",
+    datefmt="%H:%M:%S",
+)
+# Optionally silence the HTTP sub-logger if you only care about higher-level events:
+# logging.getLogger("kaleido_sdk.http").setLevel(logging.WARNING)
+
+
+async def main() -> None:
+    """Main entry point."""
+    # Print SDK info
+    print(f"{get_sdk_name()} v{get_version()}")
+    print("-" * 40)
+
+    # Create client — log_level tells the SDK which records to emit
+    client = KaleidoClient.create(
+        base_url=API_URL,
+        log_level=logging.DEBUG,
+    )
+
+    # List available assets
+    print("\nFetching assets...")
+    assets_response = await client.maker.list_assets()
+
+    print(f"\nFound {assets_response.total} assets:")
+    for asset in assets_response.assets[:5]:
+        print(f"  - {asset.ticker}: {asset.name} (precision: {asset.precision})")
+
+    if assets_response.total > 5:
+        print(f"  ... and {assets_response.total - 5} more")
+
+    # List trading pairs
+    print("\nFetching trading pairs...")
+    pairs_response = await client.maker.list_pairs()
+
+    print(f"\nFound {pairs_response.total} pairs:")
+    for pair in pairs_response.pairs[:5]:
+        print(f"  - {pair.base.ticker}/{pair.quote.ticker}")
+
+    if pairs_response.total > 5:
+        print(f"  ... and {pairs_response.total - 5} more")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

kaleido_sdk-0.1.0/examples/02_get_quote.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Example 02: Get Quote
+
+Example showing how to get a quote for a swap.
+"""
+
+import asyncio
+import logging
+import os
+
+from kaleido_sdk import (
+    KaleidoClient,
+    Layer,
+    PairQuoteRequest,
+    SwapLegInput,
+    to_display_units,
+    to_smallest_units,
+)
+
+API_URL = os.getenv("KALEIDO_API_URL", "https://api.staging.kaleidoswap.com")
+
+# ---------------------------------------------------------------------------
+# Logging setup (application's responsibility — the SDK never does this)
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)-8s] %(name)s — %(message)s",
+    datefmt="%H:%M:%S",
+)
+
+
+async def main() -> None:
+    """Main entry point."""
+    client = KaleidoClient.create(
+        base_url=API_URL,
+        log_level=logging.DEBUG,
+    )
+
+    # Discover trading pairs
+    print("Fetching available pairs...")
+    pairs = await client.maker.list_pairs()
+
+    if not pairs.pairs:
+        print("No trading pairs available")
+        return
+
+    pair = pairs.pairs[0]
+    print(f"\nUsing pair: {pair.base.ticker}/{pair.quote.ticker}")
+    print(f"  Base precision: {pair.base.precision}")
+    print(f"  Quote precision: {pair.quote.precision}")
+
+    if pair.routes:
+        print("  Available routes:")
+        for route in pair.routes:
+            print(f"    - {route.from_layer} -> {route.to_layer}")
+
+    # Get a quote for 0.001 BTC
+    amount = 0.001
+    amount_raw = to_smallest_units(amount, pair.base.precision)
+
+    print(f"\nGetting quote for {amount} {pair.base.ticker}...")
+    print(f"  (raw amount: {amount_raw})")
+
+    if pair.routes:
+        from_layer = Layer(pair.routes[0].from_layer)
+        to_layer = Layer(pair.routes[0].to_layer)
+    else:
+        from_layer = Layer.BTC_LN
+        to_layer = Layer.RGB_LN
+
+    quote_request = PairQuoteRequest(
+        from_asset=SwapLegInput(
+            asset_id=pair.base.ticker,
+            layer=from_layer,
+            amount=amount_raw,
+        ),
+        to_asset=SwapLegInput(
+            asset_id=pair.quote.ticker,
+            layer=to_layer,
+        ),
+    )
+
+    try:
+        quote = await client.maker.get_quote(quote_request)
+
+        from_display = to_display_units(quote.from_asset.amount, quote.from_asset.precision)
+        to_display = to_display_units(quote.to_asset.amount, quote.to_asset.precision)
+
+        print("\nQuote received:")
+        print(f"  RFQ ID: {quote.rfq_id}")
+        print(f"  From: {from_display} {quote.from_asset.ticker}")
+        print(f"  To: {to_display} {quote.to_asset.ticker}")
+        print(f"  Price: {quote.price}")
+        print(f"  Fee: {quote.fee.final_fee} {quote.fee.fee_asset}")
+        print(f"  Expires at: {quote.expires_at}")
+
+    except Exception as e:
+        print(f"\nError getting quote: {e}")
+        print("(This is expected if the pair doesn't support the requested route)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

kaleido_sdk-0.1.0/examples/03_websocket.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Example 03: WebSocket Streaming
+
+Example showing how to stream real-time quotes via WebSocket.
+The SDK automatically requests quotes at a configurable interval.
+"""
+
+import asyncio
+import logging
+import os
+
+from kaleido_sdk import KaleidoClient, Layer
+
+API_URL = os.getenv("KALEIDO_API_URL", "https://api.staging.kaleidoswap.com")
+WS_URL = os.getenv("KALEIDO_WS_URL", "wss://api.staging.kaleidoswap.com/api/v1/market/ws")
+
+# ---------------------------------------------------------------------------
+# Logging setup (application's responsibility — the SDK never does this)
+# ---------------------------------------------------------------------------
+# DEBUG shows every WS message, HTTP request, ping, reconnect, etc.
+# Switch to logging.INFO to see only meaningful lifecycle events.
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)-8s] %(name)s — %(message)s",
+    datefmt="%H:%M:%S",
+)
+
+
+async def main() -> None:
+    """Main entry point."""
+    client = KaleidoClient.create(
+        base_url=API_URL,
+        log_level=logging.DEBUG,
+    )
+
+    # Enable WebSocket
+    ws = client.maker.enable_websocket(WS_URL)
+
+    quotes_received = 0
+    max_quotes = 5
+
+    def on_quote(quote: dict) -> None:
+        nonlocal quotes_received
+        quotes_received += 1
+
+        from_asset = quote.get("from_asset", {})
+        to_asset = quote.get("to_asset", {})
+
+        print(f"\nQuote #{quotes_received}:")
+        print(
+            f"  From: {from_asset.get('amount')} {from_asset.get('ticker')} ({from_asset.get('layer')})"
+        )
+        print(f"  To: {to_asset.get('amount')} {to_asset.get('ticker')} ({to_asset.get('layer')})")
+        print(f"  Price: {quote.get('price')}")
+        print(f"  RFQ ID: {quote.get('rfq_id')}")
+
+    ws.on("connected", lambda: print("Connected to WebSocket!"))
+    ws.on("disconnected", lambda: print("Disconnected from WebSocket"))
+    ws.on("error", lambda e: print(f"WebSocket error: {e}"))
+
+    try:
+        print("Finding available routes...")
+        routes = await client.maker.get_available_routes("BTC", "USDT")
+
+        if not routes:
+            print("No routes found for BTC/USDT")
+            return
+
+        print(f"Found {len(routes)} routes:")
+        for route in routes:
+            print(f"  - {route.from_layer} -> {route.to_layer}")
+
+        print("\nStreaming quotes for BTC/USDT (automatically requests every 2 seconds)...")
+
+        # Start streaming - quotes are automatically requested every 2 seconds
+        stop = await client.maker.stream_quotes(
+            from_asset="BTC",
+            to_asset="USDT",
+            from_amount=100000,
+            from_layer=Layer(routes[0].from_layer),
+            to_layer=Layer(routes[0].to_layer),
+            on_update=on_quote,
+            poll_interval=2.0,  # Request new quotes every 2 seconds
+        )
+
+        # Wait for quotes to arrive via callback
+        while quotes_received < max_quotes:
+            await asyncio.sleep(0.5)
+
+        # Stop streaming and disconnect
+        stop()
+        ws.disconnect()
+        print(f"\nReceived {quotes_received} quotes. Done!")
+
+    except Exception as e:
+        print(f"\nError: {e}")
+        print("(WebSocket streaming requires a working WebSocket endpoint)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

kaleido_sdk-0.1.0/examples/04_create_swap_order.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Example 04: Create Swap Order
+
+Test-backed swap-order flow:
+1. Find the RGB asset ID for USDT
+2. Get a fresh quote for USDT(RGB_LN) -> BTC(BTC_L1)
+3. Ask the local node for a valid BTC receiver address
+4. Create a swap order
+"""
+
+import asyncio
+import logging
+import os
+
+from kaleido_sdk import (
+    CreateSwapOrderRequest,
+    KaleidoClient,
+    Layer,
+    PairQuoteRequest,
+    ReceiverAddress,
+    ReceiverAddressFormat,
+    SwapLegInput,
+)
+
+API_URL = os.getenv("KALEIDO_API_URL", "https://api.staging.kaleidoswap.com")
+NODE_URL = os.getenv("KALEIDO_NODE_URL", "http://localhost:3001")
+
+# ---------------------------------------------------------------------------
+# Logging setup (application's responsibility — the SDK never does this)
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)-8s] %(name)s — %(message)s",
+    datefmt="%H:%M:%S",
+)
+
+
+async def main() -> None:
+    """Main entry point."""
+    client = KaleidoClient.create(
+        base_url=API_URL,
+        log_level=logging.DEBUG,
+    )
+    node_client = KaleidoClient.create(
+        base_url=API_URL,
+        node_url=NODE_URL,
+        log_level=logging.DEBUG,
+    )
+
+    print(f"Maker API: {API_URL}")
+    print(f"Node URL: {NODE_URL}")
+    print("-" * 40)
+
+    print("\nFetching assets...")
+    assets = await client.maker.list_assets()
+    usdt_asset = next((asset for asset in assets.assets if asset.ticker == "USDT"), None)
+    if usdt_asset is None:
+        print("USDT asset not found in maker asset list")
+        return
+
+    protocol_ids = usdt_asset.protocol_ids or {}
+    rgb_asset_id = protocol_ids.get("RGB")
+    if rgb_asset_id is None:
+        print("USDT RGB asset id not found in protocol_ids")
+        return
+
+    print(f"Using RGB asset id for USDT: {rgb_asset_id}")
+
+    print("\nRequesting quote for USDT(RGB_LN) -> BTC(BTC_L1)...")
+    quote = await client.maker.get_quote(
+        PairQuoteRequest(
+            from_asset=SwapLegInput(
+                asset_id=rgb_asset_id,
+                layer=Layer.RGB_LN,
+                amount=1_000_000,
+            ),
+            to_asset=SwapLegInput(
+                asset_id="BTC",
+                layer=Layer.BTC_L1,
+            ),
+        )
+    )
+
+    print(f"RFQ ID: {quote.rfq_id}")
+    print(f"From: {quote.from_asset.amount} {quote.from_asset.ticker}")
+    print(f"To: {quote.to_asset.amount} {quote.to_asset.ticker}")
+
+    print("\nFetching a valid BTC address from the local node...")
+    address_response = await node_client.rln.get_address()
+    receiver_address = address_response.address
+    print(f"Receiver address: {receiver_address}")
+
+    order_request = CreateSwapOrderRequest(
+        rfq_id=quote.rfq_id,
+        from_asset=quote.from_asset,
+        to_asset=quote.to_asset,
+        receiver_address=ReceiverAddress(
+            address=receiver_address,
+            format=ReceiverAddressFormat.BTC_ADDRESS,
+        ),
+        min_onchain_conf=1,
+        refund_address=receiver_address,
+        email="test@example.com",
+    )
+
+    print("\nCreating swap order...")
+    order = await client.maker.create_swap_order(order_request)
+
+    print("\nOrder created:")
+    print(f"  Order ID: {order.id}")
+    print(f"  RFQ ID: {order.rfq_id}")
+    print(f"  Status: {order.status}")
+    if order.deposit_address is not None:
+        print(f"  Deposit address: {order.deposit_address.address}")
+        print(f"  Deposit format: {order.deposit_address.format}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())