defuse-py 0.1.0__py3-none-any.whl

defuse/__init__.py

@@ -0,0 +1,44 @@
+from .client import IntentsClient
+from .enums import DepositMode, DepositType, RecipientType, RefundType, SwapStatus, SwapType
+from .exceptions import IntentsAPIError, IntentsAuthError, IntentsError
+from .models import (
+    AppFee,
+    AnyInputWithdrawalsResponse,
+    ExecutionStatusResponse,
+    Quote,
+    QuoteRequest,
+    QuoteResponse,
+    SubmitDepositRequest,
+    SubmitDepositResponse,
+    TokenResponse,
+)
+from .utils import find_token, from_atomic, to_atomic, token_from_atomic, token_to_atomic, pct_to_bps, bps_to_pct
+
+__all__ = [
+    "IntentsClient",
+    "DepositMode",
+    "DepositType",
+    "RecipientType",
+    "RefundType",
+    "SwapStatus",
+    "SwapType",
+    "IntentsAPIError",
+    "IntentsAuthError",
+    "IntentsError",
+    "AppFee",
+    "AnyInputWithdrawalsResponse",
+    "ExecutionStatusResponse",
+    "Quote",
+    "QuoteRequest",
+    "QuoteResponse",
+    "SubmitDepositRequest",
+    "SubmitDepositResponse",
+    "TokenResponse",
+    "find_token",
+    "from_atomic",
+    "to_atomic",
+    "token_from_atomic",
+    "token_to_atomic",
+    "pct_to_bps",
+    "bps_to_pct",
+]

defuse/client.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Literal
+
+import httpx
+
+from .exceptions import IntentsAPIError, IntentsAuthError
+from .models import (
+    AnyInputWithdrawalsResponse,
+    ExecutionStatusResponse,
+    QuoteRequest,
+    QuoteResponse,
+    SubmitDepositRequest,
+    SubmitDepositResponse,
+    TokenResponse,
+)
+
+_BASE_URL = "https://1click.chaindefuser.com"
+
+
+class IntentsClient:
+    """Async client for the NEAR Intents 1Click Swap API.
+
+    Can be used as an async context manager or standalone. When used standalone,
+    call :meth:`aclose` when finished.
+
+    Args:
+        jwt_token: Optional Bearer JWT token for authenticated endpoints.
+        base_url: Override the default API base URL.
+        timeout: Request timeout in seconds (default: 30).
+    """
+
+    def __init__(
+        self,
+        jwt_token: str | None = None,
+        base_url: str = _BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        headers: dict[str, str] = {"Accept": "application/json", "Content-Type": "application/json"}
+        if jwt_token:
+            headers["Authorization"] = f"Bearer {jwt_token}"
+
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    async def __aenter__(self) -> IntentsClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code == 401:
+            raise IntentsAuthError(401, "Unauthorized — JWT token is missing or invalid")
+        if response.is_error:
+            try:
+                message = self._parse_json(response).get("message", response.text)
+            except Exception:
+                message = response.text
+            raise IntentsAPIError(response.status_code, message)
+
+    def _parse_json(self, response: httpx.Response) -> object:
+        if not response.content:
+            raise IntentsAPIError(response.status_code, "Empty response body")
+        return response.json()
+
+    async def get_tokens(self) -> list[TokenResponse]:
+        """Retrieve all tokens supported by the 1Click API.
+
+        Returns:
+            List of :class:`~intents.models.TokenResponse` objects.
+        """
+        response = await self._http.get("/v0/tokens")
+        await self._raise_for_status(response)
+        return [TokenResponse.model_validate(item) for item in self._parse_json(response)]  # type: ignore[union-attr]
+
+    async def get_quote(self, request: QuoteRequest) -> QuoteResponse:
+        """Request a swap quote.
+
+        Pass ``dry=True`` on the request to simulate the quote without
+        generating a deposit address.
+
+        Args:
+            request: Swap parameters as a :class:`~intents.models.QuoteRequest`.
+
+        Returns:
+            :class:`~intents.models.QuoteResponse` with the deposit address
+            and expected output amounts.
+
+        Raises:
+            IntentsAPIError: On HTTP 400 (bad request).
+            IntentsAuthError: On HTTP 401 (invalid JWT).
+        """
+        response = await self._http.post(
+            "/v0/quote",
+            json=request.to_api_dict(),
+
+        )
+        await self._raise_for_status(response)
+        return QuoteResponse.model_validate(self._parse_json(response))
+
+    async def get_status(
+        self,
+        deposit_address: str,
+        deposit_memo: str | None = None,
+    ) -> ExecutionStatusResponse:
+        """Check the execution status of a swap.
+
+        Args:
+            deposit_address: The deposit address returned by :meth:`get_quote`.
+            deposit_memo: Required for chains that use memo-based deposits.
+
+        Returns:
+            :class:`~intents.models.ExecutionStatusResponse`.
+
+        Raises:
+            IntentsAPIError: On HTTP 404 (deposit address not found).
+            IntentsAuthError: On HTTP 401 (invalid JWT).
+        """
+        params: dict[str, str] = {"depositAddress": deposit_address}
+        if deposit_memo is not None:
+            params["depositMemo"] = deposit_memo
+
+        response = await self._http.get(
+            "/v0/status",
+            params=params,
+
+        )
+        await self._raise_for_status(response)
+        return ExecutionStatusResponse.model_validate(self._parse_json(response))
+
+    async def get_any_input_withdrawals(
+        self,
+        deposit_address: str,
+        deposit_memo: str | None = None,
+        timestamp_from: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        sort_order: Literal["asc", "desc"] | None = None,
+    ) -> AnyInputWithdrawalsResponse:
+        """Retrieve withdrawals for an ``ANY_INPUT`` quote.
+
+        Args:
+            deposit_address: The deposit address for the quote.
+            deposit_memo: Memo used with the deposit, if applicable.
+            timestamp_from: ISO timestamp to filter withdrawals from.
+            page: Page number for pagination (default: 1).
+            limit: Withdrawals per page (max 50, default: 50).
+            sort_order: ``"asc"`` or ``"desc"``.
+
+        Returns:
+            :class:`~intents.models.AnyInputWithdrawalsResponse`.
+        """
+        params: dict[str, str | int] = {"depositAddress": deposit_address}
+        if deposit_memo is not None:
+            params["depositMemo"] = deposit_memo
+        if timestamp_from is not None:
+            params["timestampFrom"] = timestamp_from
+        if page is not None:
+            params["page"] = page
+        if limit is not None:
+            params["limit"] = limit
+        if sort_order is not None:
+            params["sortOrder"] = sort_order
+
+        response = await self._http.get(
+            "/v0/any-input/withdrawals",
+            params=params,
+
+        )
+        await self._raise_for_status(response)
+        return AnyInputWithdrawalsResponse.model_validate(self._parse_json(response))
+
+    async def submit_deposit(self, request: SubmitDepositRequest) -> SubmitDepositResponse:
+        """Notify the 1Click service that a deposit transaction has been sent.
+
+        This is optional but can speed up swap processing by allowing the
+        service to preemptively verify the deposit.
+
+        Args:
+            request: Deposit details as a :class:`~intents.models.SubmitDepositRequest`.
+
+        Returns:
+            :class:`~intents.models.SubmitDepositResponse`.
+
+        Raises:
+            IntentsAPIError: On HTTP 400 (bad request).
+            IntentsAuthError: On HTTP 401 (invalid JWT).
+        """
+        response = await self._http.post(
+            "/v0/deposit/submit",
+            json=request.to_api_dict(),
+
+        )
+        await self._raise_for_status(response)
+        return SubmitDepositResponse.model_validate(self._parse_json(response))

defuse/enums.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SwapType(str, Enum):
+    EXACT_INPUT = "EXACT_INPUT"
+    EXACT_OUTPUT = "EXACT_OUTPUT"
+    FLEX_INPUT = "FLEX_INPUT"
+    ANY_INPUT = "ANY_INPUT"
+
+
+class DepositType(str, Enum):
+    ORIGIN_CHAIN = "ORIGIN_CHAIN"
+    INTENTS = "INTENTS"
+
+
+class RecipientType(str, Enum):
+    DESTINATION_CHAIN = "DESTINATION_CHAIN"
+    INTENTS = "INTENTS"
+
+
+class DepositMode(str, Enum):
+    SIMPLE = "SIMPLE"
+    MEMO = "MEMO"
+
+
+class RefundType(str, Enum):
+    ORIGIN_CHAIN = "ORIGIN_CHAIN"
+    INTENTS = "INTENTS"
+
+
+class SwapStatus(str, Enum):
+    KNOWN_DEPOSIT_TX = "KNOWN_DEPOSIT_TX"
+    PENDING_DEPOSIT = "PENDING_DEPOSIT"
+    INCOMPLETE_DEPOSIT = "INCOMPLETE_DEPOSIT"
+    PROCESSING = "PROCESSING"
+    SUCCESS = "SUCCESS"
+    REFUNDED = "REFUNDED"
+    FAILED = "FAILED"

defuse/exceptions.py

@@ -0,0 +1,15 @@
+class IntentsError(Exception):
+    """Base exception for all Intents API errors."""
+
+
+class IntentsAPIError(IntentsError):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"HTTP {status_code}: {message}")
+
+
+class IntentsAuthError(IntentsAPIError):
+    """Raised when the API returns a 401 Unauthorized response."""

defuse/models.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from .enums import DepositMode, DepositType, RecipientType, RefundType, SwapStatus, SwapType
+
+_camel = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+class TokenResponse(BaseModel):
+    model_config = _camel
+
+    asset_id: str
+    decimals: int
+    blockchain: str
+    symbol: str
+    price: float
+    price_updated_at: datetime
+    contract_address: str | None = None
+
+
+class AppFee(BaseModel):
+    model_config = _camel
+
+    recipient: str
+    fee: int = Field(ge=0, description="Fee in basis points")
+
+
+class QuoteRequest(BaseModel):
+    model_config = _camel
+
+    dry: bool
+    swap_type: SwapType | str
+    slippage_tolerance: int = Field(description="Slippage in basis points")
+    origin_asset: str
+    deposit_type: DepositType | str
+    destination_asset: str
+    amount: str
+    refund_to: str
+    refund_type: RefundType | str
+    recipient: str
+    recipient_type: RecipientType | str
+    deadline: datetime
+    deposit_mode: DepositMode | str = DepositMode.SIMPLE
+    connected_wallets: list[str] | None = None
+    session_id: str | None = None
+    virtual_chain_recipient: str | None = None
+    virtual_chain_refund_recipient: str | None = None
+    custom_recipient_msg: str | None = None
+    referral: str | None = None
+    quote_waiting_time_ms: int = 3000
+    app_fees: list[AppFee] | None = None
+
+    def to_api_dict(self) -> dict:
+        return self.model_dump(by_alias=True, exclude_none=True, mode="json")
+
+
+class Quote(BaseModel):
+    model_config = _camel
+
+    amount_in: str
+    amount_in_formatted: str
+    amount_in_usd: str
+    min_amount_in: str
+    max_amount_in: str | None = None
+    amount_out: str
+    amount_out_formatted: str
+    amount_out_usd: str
+    min_amount_out: str
+    time_estimate: int = Field(description="Estimated swap time in seconds")
+    deposit_address: str | None = None
+    deposit_memo: str | None = None
+    deadline: datetime | None = None
+    time_when_inactive: datetime | None = None
+    virtual_chain_recipient: str | None = None
+    virtual_chain_refund_recipient: str | None = None
+    custom_recipient_msg: str | None = None
+    refund_fee: str | None = None
+
+
+class QuoteResponse(BaseModel):
+    model_config = _camel
+
+    correlation_id: str | None = None
+    timestamp: datetime
+    signature: str
+    quote_request: QuoteRequest
+    quote: Quote
+
+
+class TransactionDetails(BaseModel):
+    model_config = _camel
+
+    hash: str
+    explorer_url: str
+
+
+class SwapDetails(BaseModel):
+    model_config = _camel
+
+    intent_hashes: list[str]
+    near_tx_hashes: list[str]
+    origin_chain_tx_hashes: list[TransactionDetails]
+    destination_chain_tx_hashes: list[TransactionDetails]
+    amount_in: str | None = None
+    amount_in_formatted: str | None = None
+    amount_in_usd: str | None = None
+    amount_out: str | None = None
+    amount_out_formatted: str | None = None
+    amount_out_usd: str | None = None
+    slippage: int | None = None
+    refunded_amount: str | None = None
+    refunded_amount_formatted: str | None = None
+    refunded_amount_usd: str | None = None
+    refund_reason: str | None = None
+    deposited_amount: str | None = None
+    deposited_amount_formatted: str | None = None
+    deposited_amount_usd: str | None = None
+    referral: str | None = None
+
+
+class ExecutionStatusResponse(BaseModel):
+    model_config = _camel
+
+    correlation_id: str
+    quote_response: QuoteResponse
+    status: SwapStatus
+    updated_at: datetime
+    swap_details: SwapDetails
+
+
+class AnyInputWithdrawal(BaseModel):
+    model_config = _camel
+
+    status: str
+    amount_out_formatted: str
+    amount_out_usd: str
+    amount_out: str
+    withdraw_fee_formatted: str
+    withdraw_fee: str
+    withdraw_fee_usd: str
+    timestamp: str
+    hash: str
+
+
+class AnyInputWithdrawalsResponse(BaseModel):
+    model_config = _camel
+
+    asset: str
+    recipient: str
+    affiliate_recipient: str
+    withdrawals: AnyInputWithdrawal | None = None
+
+
+class SubmitDepositRequest(BaseModel):
+    model_config = _camel
+
+    tx_hash: str
+    deposit_address: str
+    near_sender_account: str | None = None
+    memo: str | None = None
+
+    def to_api_dict(self) -> dict:
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
+class SubmitDepositResponse(BaseModel):
+    model_config = _camel
+
+    correlation_id: str
+    quote_response: QuoteResponse
+    status: SwapStatus
+    updated_at: datetime
+    swap_details: SwapDetails

defuse/utils.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from decimal import ROUND_DOWN, Decimal
+
+from .models import TokenResponse
+
+
+def to_atomic(amount: int | float | str | Decimal, decimals: int) -> str:
+    """Convert a human-readable token amount to its atomic (smallest unit) string.
+
+    Uses :class:`~decimal.Decimal` internally to avoid floating-point errors.
+
+    Args:
+        amount: Human-readable amount, e.g. ``0.1`` or ``"0.1"``.
+        decimals: Number of decimals for the token (from :attr:`TokenResponse.decimals`).
+
+    Returns:
+        Atomic amount as a string, e.g. ``"100000000000000000"`` for 0.1 ETH.
+
+    Raises:
+        ValueError: If the amount is negative or has more decimal places than
+            the token supports.
+
+    Examples:
+        >>> to_atomic("0.1", 18)   # 0.1 ETH → wei
+        '100000000000000000'
+        >>> to_atomic(1, 24)       # 1 NEAR → yoctoNEAR
+        '1000000000000000000000000'
+    """
+    d = Decimal(str(amount))
+    if d < 0:
+        raise ValueError(f"Amount must be non-negative, got {amount!r}")
+
+    scaled = d * Decimal(10) ** decimals
+
+    if scaled != scaled.to_integral_value():
+        raise ValueError(
+            f"{amount!r} has more decimal places than the token supports ({decimals})"
+        )
+
+    return str(scaled.to_integral_value(rounding=ROUND_DOWN))
+
+
+def from_atomic(amount: int | str, decimals: int) -> Decimal:
+    """Convert an atomic (smallest unit) token amount to a human-readable :class:`~decimal.Decimal`.
+
+    Args:
+        amount: Atomic amount as returned by the API, e.g. ``"100000000000000000"``.
+        decimals: Number of decimals for the token.
+
+    Returns:
+        Human-readable amount, e.g. ``Decimal("0.1")`` for 0.1 ETH.
+
+    Examples:
+        >>> from_atomic("100000000000000000", 18)
+        Decimal('0.1')
+        >>> from_atomic("1000000000000000000000000", 24)
+        Decimal('1')
+    """
+    return Decimal(str(amount)) / Decimal(10) ** decimals
+
+
+def token_to_atomic(amount: int | float | str | Decimal, token: TokenResponse) -> str:
+    """Convert a human-readable amount to atomic units using a :class:`~defuse.models.TokenResponse`.
+
+    Convenience wrapper around :func:`to_atomic` that reads ``decimals`` directly
+    from the token object.
+
+    Args:
+        amount: Human-readable amount, e.g. ``0.1``.
+        token: Token metadata returned by :meth:`~defuse.client.IntentsClient.get_tokens`.
+
+    Returns:
+        Atomic amount string ready to pass as ``amount`` in a
+        :class:`~defuse.models.QuoteRequest`.
+
+    Examples:
+        >>> tokens = await client.get_tokens()
+        >>> eth = find_token(tokens, "eth", "ETH")
+        >>> token_to_atomic(0.1, eth)
+        '100000000000000000'
+    """
+    return to_atomic(amount, token.decimals)
+
+
+def token_from_atomic(amount: int | str, token: TokenResponse) -> Decimal:
+    """Convert an atomic amount to a human-readable :class:`~decimal.Decimal` using a :class:`~defuse.models.TokenResponse`.
+
+    Args:
+        amount: Atomic amount string as returned by the API.
+        token: Token metadata returned by :meth:`~defuse.client.IntentsClient.get_tokens`.
+
+    Returns:
+        Human-readable :class:`~decimal.Decimal`.
+    """
+    return from_atomic(amount, token.decimals)
+
+
+def pct_to_bps(percent: int | float | str | Decimal) -> int:
+    """Convert a percentage to basis points.
+
+    Args:
+        percent: Percentage value, e.g. ``1`` for 1% or ``0.5`` for 0.5%.
+
+    Returns:
+        Basis points as an integer, e.g. ``100`` for 1%.
+
+    Examples:
+        >>> pct_to_bps(1)
+        100
+        >>> pct_to_bps(0.5)
+        50
+    """
+    return int(Decimal(str(percent)) * 100)
+
+
+def bps_to_pct(bps: int) -> Decimal:
+    """Convert basis points to a percentage.
+
+    Args:
+        bps: Basis points, e.g. ``100`` for 1%.
+
+    Returns:
+        Percentage as a :class:`~decimal.Decimal`, e.g. ``Decimal("1")`` for 100 bps.
+
+    Examples:
+        >>> bps_to_pct(100)
+        Decimal('1')
+        >>> bps_to_pct(50)
+        Decimal('0.50')
+    """
+    return Decimal(bps) / 100
+
+
+def find_token(
+    tokens: list[TokenResponse],
+    blockchain: str,
+    symbol: str,
+) -> TokenResponse:
+    """Look up a token by blockchain and symbol from a token list.
+
+    Args:
+        tokens: Token list returned by :meth:`~defuse.client.IntentsClient.get_tokens`.
+        blockchain: The chain to search on, e.g. ``"eth"``, ``"arb"``, ``"sol"``.
+        symbol: Token symbol, e.g. ``"ETH"``, ``"USDC"``. Case-insensitive.
+
+    Returns:
+        The matching :class:`~defuse.models.TokenResponse`.
+
+    Raises:
+        LookupError: If no token matches the given blockchain and symbol.
+
+    Examples:
+        >>> tokens = await client.get_tokens()
+        >>> eth = find_token(tokens, "eth", "ETH")
+        >>> eth.asset_id
+        'nep141:eth.omft.near'
+    """
+    match = next(
+        (t for t in tokens if t.blockchain == blockchain and t.symbol.upper() == symbol.upper()),
+        None,
+    )
+    if match is None:
+        raise LookupError(f"No token found for {symbol!r} on {blockchain!r}")
+    return match

defuse_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: defuse-py
+Version: 0.1.0
+Summary: Async Python wrapper for the NEAR Intents 1Click Swap API
+Project-URL: Homepage, https://github.com/er/defuse.py
+Project-URL: Repository, https://github.com/er/defuse.py
+License: MIT License
+        
+        Copyright (c) 2026 er
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# defuse.py
+
+An async Python wrapper for the [NEAR Intents 1Click Swap API](https://1click.chaindefuser.com).
+
+```
+pip install defuse-py
+```
+
+## Requirements
+
+- Python 3.10+
+- `httpx`
+- `pydantic`
+
+## Quickstart
+
+```python
+import asyncio
+from defuse import IntentsClient, find_token
+
+async def main():
+    async with IntentsClient() as client:
+        tokens = await client.get_tokens()
+        eth = find_token(tokens, "eth", "ETH")
+        print(eth.asset_id)  # nep141:eth.omft.near
+
+asyncio.run(main())
+```
+
+## Swap flow
+
+```python
+import asyncio
+from datetime import datetime, timedelta, timezone
+from defuse import (
+    IntentsClient,
+    QuoteRequest,
+    SwapType,
+    DepositType,
+    RecipientType,
+    RefundType,
+    SwapStatus,
+    find_token,
+    token_to_atomic,
+)
+
+async def main():
+    async with IntentsClient(jwt_token="your-jwt-token") as client:
+        tokens = await client.get_tokens()
+        eth  = find_token(tokens, "eth", "ETH")
+        usdc = find_token(tokens, "arb", "USDC")
+
+        # 1. Get a quote
+        response = await client.get_quote(QuoteRequest(
+            dry=False,
+            swap_type=SwapType.EXACT_INPUT,
+            slippage_tolerance=100,          # 1% — use pct_to_bps(1) for clarity
+            origin_asset=eth.asset_id,
+            destination_asset=usdc.asset_id,
+            deposit_type=DepositType.ORIGIN_CHAIN,
+            amount=token_to_atomic("0.01", eth),
+            refund_to="0xYourAddress",
+            refund_type=RefundType.ORIGIN_CHAIN,
+            recipient="0xYourAddress",
+            recipient_type=RecipientType.DESTINATION_CHAIN,
+            deadline=datetime.now(timezone.utc) + timedelta(hours=1),
+        ))
+
+        quote = response.quote
+        print(f"Send {quote.amount_in_formatted} ETH to {quote.deposit_address}")
+        if quote.deposit_memo:
+            print(f"Memo (required): {quote.deposit_memo}")
+
+        # 2. Send funds to quote.deposit_address, then poll for status
+        while True:
+            status = await client.get_status(quote.deposit_address, quote.deposit_memo)
+            print(status.status)
+            if status.status in {SwapStatus.SUCCESS, SwapStatus.REFUNDED, SwapStatus.FAILED}:
+                break
+            await asyncio.sleep(10)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Most endpoints require a JWT token. Pass it when constructing the client:
+
+```python
+client = IntentsClient(jwt_token="your-jwt-token")
+```
+
+## API reference
+
+### `IntentsClient`
+
+| Method | Description |
+|---|---|
+| `get_tokens()` | List all supported tokens |
+| `get_quote(request)` | Request a swap quote |
+| `get_status(deposit_address, deposit_memo?)` | Check swap status |
+| `get_any_input_withdrawals(deposit_address, ...)` | Get withdrawals for an `ANY_INPUT` quote |
+| `submit_deposit(request)` | Notify the service a deposit has been sent |
+
+### Utilities
+
+| Function | Description |
+|---|---|
+| `find_token(tokens, blockchain, symbol)` | Look up a token by chain and symbol |
+| `to_atomic(amount, decimals)` | Convert `0.1` → `"100000000000000000"` |
+| `from_atomic(amount, decimals)` | Convert `"100000000000000000"` → `Decimal("0.1")` |
+| `token_to_atomic(amount, token)` | `to_atomic` using a `TokenResponse` |
+| `token_from_atomic(amount, token)` | `from_atomic` using a `TokenResponse` |
+| `pct_to_bps(percent)` | Convert `1` (%) → `100` (bps) |
+| `bps_to_pct(bps)` | Convert `100` (bps) → `Decimal("1")` (%) |
+
+### Swap types
+
+| Value | Behaviour |
+|---|---|
+| `EXACT_INPUT` | Specify input amount, receive calculated output |
+| `EXACT_OUTPUT` | Specify output amount, deposit calculated input |
+| `FLEX_INPUT` | Variable input with slippage bounds |
+| `ANY_INPUT` | Multiple partial deposits over time |
+
+### Swap statuses
+
+`KNOWN_DEPOSIT_TX` → `PENDING_DEPOSIT` → `PROCESSING` → `SUCCESS`
+
+Terminal states: `SUCCESS`, `REFUNDED`, `FAILED`
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- [`list_tokens.py`](examples/list_tokens.py) — fetch and display all supported tokens
+- [`dry_quote.py`](examples/dry_quote.py) — preview a swap without creating a deposit address
+- [`swap.py`](examples/swap.py) — full swap lifecycle with status polling
+- [`submit_deposit.py`](examples/submit_deposit.py) — notify the service after sending funds
+- [`any_input_withdrawals.py`](examples/any_input_withdrawals.py) — fetch `ANY_INPUT` withdrawals
+
+## License
+
+MIT

defuse_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+defuse/__init__.py,sha256=1Pxi2rb55oufs9nqLXbaWYR8PQdDEb8lRbMNq608BDE,1095
+defuse/client.py,sha256=mg1zfKUtAeqxX8OTDB8Iga7tQ7qzMgSDPhOwWCUg2pQ,7040
+defuse/enums.py,sha256=RKUuJz_Pj5o1GKF_yA27LWnZQy_qXBBSnwTjJJKnDpY,825
+defuse/exceptions.py,sha256=i3saOVsjB29plEswP-h9-A1eBroFUpcFXoNn0m-89s4,484
+defuse/models.py,sha256=_1Vq0E6I9obdVox35kZJVYxfk5Y0VVcMxhY743rOWFk,4573
+defuse/utils.py,sha256=97Zwy6rsgRHVluEmg9qm04cxm-bYjKkMZvddcRQpVXA,5070
+defuse_py-0.1.0.dist-info/METADATA,sha256=rELrr7JVfd8dIBrL4a_kU8TjIIrFi7qpBE8vFp6M9Hg,6173
+defuse_py-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+defuse_py-0.1.0.dist-info/licenses/LICENSE,sha256=BfbU7PJPyRC29_p0Le5zNX6Ui-UXrl2EACs57O4cNxQ,1059
+defuse_py-0.1.0.dist-info/RECORD,,

defuse_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

defuse_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 er
+
+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.