bitcoinvn 0.1.0__py3-none-any.whl

bitcoinvn/__init__.py

@@ -0,0 +1,57 @@
+"""Python client for the BitcoinVN exchange API.
+
+The production base URL is https://bitcoinvn.io. Official OpenAPI:
+https://bitcoinvn.io/api/doc.json
+
+Public reads do not need a key. Account calls send ``X-API-KEY`` when
+``api_key`` is set. Order creation always includes the JSON field ``referrer``.
+
+Examples:
+    from bitcoinvn import BitcoinVn
+
+    client = BitcoinVn()
+    ticker = client.get_ticker("BTC", "USDT")
+"""
+
+from bitcoinvn.client import REFERRER, BitcoinVn
+from bitcoinvn.errors import BitcoinVnError
+from bitcoinvn.types import (
+    AddressValidation,
+    Asset,
+    Balances,
+    BooleanConfiguration,
+    EnsResolution,
+    HealthStatus,
+    Info,
+    LedgerItem,
+    Order,
+    OrderStatus,
+    Pair,
+    Quote,
+    Ticker,
+    TransferMethod,
+    Vault,
+)
+
+__all__ = [
+    "REFERRER",
+    "AddressValidation",
+    "Asset",
+    "Balances",
+    "BitcoinVn",
+    "BitcoinVnError",
+    "BooleanConfiguration",
+    "EnsResolution",
+    "HealthStatus",
+    "Info",
+    "LedgerItem",
+    "Order",
+    "OrderStatus",
+    "Pair",
+    "Quote",
+    "Ticker",
+    "TransferMethod",
+    "Vault",
+]
+
+__version__ = "0.1.0"

bitcoinvn/client.py

@@ -0,0 +1,483 @@
+"""Synchronous client for the BitcoinVN exchange API."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from bitcoinvn.errors import BitcoinVnError
+from bitcoinvn.types import (
+    AddressValidation,
+    Balances,
+    BooleanConfiguration,
+    EnsResolution,
+    HealthStatus,
+    Info,
+    LedgerItem,
+    Order,
+    Pair,
+    Quote,
+    Ticker,
+    Vault,
+)
+
+DEFAULT_BASE_URL = "https://bitcoinvn.io"
+USER_AGENT = "bitcoinvn/0.1.0"
+REFERRER = "35b2eec68a1741ac"
+
+
+class BitcoinVn:
+    """Client for the BitcoinVN exchange API.
+
+    Public reads, quotes, and order creation do not need a key. Pass ``api_key``
+    to send ``X-API-KEY``. The key is created on the API keys page at
+    bitcoinvn.io. This client does not manage keys.
+
+    ``create_order`` always sends the JSON property ``referrer``. Callers cannot
+    pass or disable it. Other methods do not send that field.
+
+    Examples:
+        client = BitcoinVn()
+        ticker = client.get_ticker("BTC", "USDT")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout_ms: float | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        """Create a client.
+
+        Args:
+            api_key: Key sent as ``X-API-KEY``. A blank value sends no header.
+            base_url: Defaults to ``https://bitcoinvn.io``.
+            timeout_ms: Request timeout in milliseconds. Defaults to 30000.
+            client: Optional ``httpx.Client``. When set, this object does not
+                close it and ignores ``base_url`` and ``timeout_ms``.
+
+        Examples:
+            client = BitcoinVn(api_key)
+        """
+        key = api_key.strip() if api_key else ""
+        self._api_key = key or None
+        self._owns_client = client is None
+        if client is not None:
+            self._http = client
+            return
+        root = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        timeout = 30.0 if timeout_ms is None else timeout_ms / 1000
+        self._http = httpx.Client(
+            base_url=root,
+            timeout=timeout,
+            headers={
+                "Accept": "application/json, text/plain",
+                "User-Agent": USER_AGENT,
+            },
+        )
+
+    def close(self) -> None:
+        """Close the HTTP client when this object created it.
+
+        Examples:
+            client.close()
+        """
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> BitcoinVn:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def get_health(self) -> HealthStatus:
+        """``GET /api/health``.
+
+        Examples:
+            health = client.get_health()
+        """
+        return self._request("GET", "/api/health")
+
+    def get_info(self) -> Info:
+        """``GET /api/info``.
+
+        Use method ids exactly as returned. Check ``depositEnabled`` or
+        ``settleEnabled`` for the direction you need.
+
+        Examples:
+            info = client.get_info()
+        """
+        return self._request("GET", "/api/info")
+
+    def get_pair(self, deposit_method_id: str, settle_method_id: str) -> Pair:
+        """``GET /api/pairs/{depositMethodId}/{settleMethodId}``.
+
+        A successful response does not reserve liquidity. An API key applies
+        the account minimum to ``min``.
+
+        Examples:
+            pair = client.get_pair("btc", "xmr")
+        """
+        path = f"/api/pairs/{_segment(deposit_method_id)}/{_segment(settle_method_id)}"
+        return self._request("GET", path)
+
+    def get_ticker(self, base_asset_id: str, quote_asset_id: str) -> Ticker:
+        """``GET /api/ticker/{baseAssetId}/{quoteAssetId}``.
+
+        Asset ids are case-sensitive. ``rate`` is quote units per one base unit.
+
+        Examples:
+            ticker = client.get_ticker("BTC", "USDT")
+        """
+        path = f"/api/ticker/{_segment(base_asset_id)}/{_segment(quote_asset_id)}"
+        return self._request("GET", path)
+
+    def validate_address(
+        self,
+        transfer_method: str,
+        address: str,
+        *,
+        invoice_amount: float | None = None,
+    ) -> AddressValidation:
+        """``GET /api/addresses/validate``.
+
+        For Lightning, pass the BOLT11 invoice as ``address``.
+
+        Examples:
+            result = client.validate_address("btc", "bc1qexample")
+        """
+        return self._request(
+            "GET",
+            "/api/addresses/validate",
+            query={
+                "transferMethod": transfer_method,
+                "address": address,
+                "invoiceAmount": invoice_amount,
+            },
+        )
+
+    def create_quote(
+        self,
+        deposit_method: str,
+        settle_method: str,
+        *,
+        deposit_amount: float | None = None,
+        settle_amount: float | None = None,
+        markup_rate: float | None = None,
+    ) -> Quote:
+        """``POST /api/quotes``.
+
+        Send ``deposit_amount``, ``settle_amount``, or neither, but not both.
+        This creates a production quote and does not move funds.
+
+        Examples:
+            quote = client.create_quote("btc", "xmr", deposit_amount=0.01)
+        """
+        return self._request(
+            "POST",
+            "/api/quotes",
+            body=_omit_none(
+                {
+                    "depositMethod": deposit_method,
+                    "settleMethod": settle_method,
+                    "depositAmount": deposit_amount,
+                    "settleAmount": settle_amount,
+                    "markupRate": markup_rate,
+                }
+            ),
+        )
+
+    def list_orders(
+        self,
+        *,
+        page: int | None = None,
+        custom_order_id: str | None = None,
+    ) -> list[Order]:
+        """``GET /api/orders``. Requires ``X-API-KEY``. Pages contain 10 orders.
+
+        Examples:
+            orders = client.list_orders(page=1)
+        """
+        return self._request(
+            "GET",
+            "/api/orders",
+            query={"page": page, "customOrderId": custom_order_id},
+        )
+
+    def create_order(
+        self,
+        *,
+        quote: str | None = None,
+        deposit_method: str | None = None,
+        settle_method: str | None = None,
+        deposit_amount: float | None = None,
+        settle_amount: float | None = None,
+        custom_order_id: str | None = None,
+        webhook_url: str | None = None,
+        settle_data: Mapping[str, Any] | None = None,
+    ) -> Order:
+        """``POST /api/orders``. Creates a production order.
+
+        Pass ``quote``, or ``deposit_method`` and ``settle_method`` for a
+        variable-amount order. An amountless internal-balance quote can also
+        take ``deposit_amount`` or ``settle_amount``. The JSON body always
+        includes ``referrer``. Funding the order moves real funds.
+
+        Examples:
+            order = client.create_order(
+                quote="8120a8a8-8dd1-4168-80fc-c4d932ce5b93",
+                settle_data={"address": "4example"},
+            )
+        """
+        body = _omit_none(
+            {
+                "quote": quote,
+                "depositMethod": deposit_method,
+                "settleMethod": settle_method,
+                "depositAmount": deposit_amount,
+                "settleAmount": settle_amount,
+                "customOrderId": custom_order_id,
+                "webhookUrl": webhook_url,
+                "settleData": dict(settle_data) if settle_data is not None else None,
+            }
+        )
+        body["referrer"] = REFERRER
+        return self._request("POST", "/api/orders", body=body)
+
+    def get_order(self, order_id: str) -> Order:
+        """``GET /api/orders/{id}``. ``order_id`` is the 8-character short id.
+
+        Examples:
+            order = client.get_order("BV2MTZAF")
+        """
+        return self._request("GET", f"/api/orders/{_segment(order_id)}")
+
+    def submit_deposit(self, order_id: str, txid: str) -> Order:
+        """``POST /api/orders/{id}/deposit``.
+
+        Optional fast path after a supported on-chain deposit is broadcast and
+        the order is ``new``. Fiat, Lightning, internal-balance, and manual
+        deposits do not use this call.
+
+        Examples:
+            order = client.submit_deposit("BV2MTZAF", "0x0123456789abcdef")
+        """
+        return self._request(
+            "POST",
+            f"/api/orders/{_segment(order_id)}/deposit",
+            body={"txid": txid},
+        )
+
+    def update_settle_data(self, order_id: str, settle_data: Mapping[str, Any]) -> Order:
+        """``PUT /api/orders/{id}/settle-data``.
+
+        Requires a key with write access. The order must be ``settle_data_error``.
+
+        Examples:
+            order = client.update_settle_data("BV2MTZAF", {"address": "bc1qexample"})
+        """
+        return self._request(
+            "PUT",
+            f"/api/orders/{_segment(order_id)}/settle-data",
+            body=dict(settle_data),
+        )
+
+    def get_balances(self) -> Balances:
+        """``GET /api/balances``. Requires ``X-API-KEY``.
+
+        Examples:
+            balances = client.get_balances()
+        """
+        return self._request("GET", "/api/balances")
+
+    def list_balance_history(
+        self,
+        *,
+        asset_id: str | None = None,
+        page: int | None = None,
+    ) -> list[LedgerItem]:
+        """``GET /api/balances/history``. Requires ``X-API-KEY``.
+
+        Pages contain 25 rows.
+
+        Examples:
+            history = client.list_balance_history(asset_id="BTC", page=1)
+        """
+        return self._request(
+            "GET",
+            "/api/balances/history",
+            query={"assetId": asset_id, "page": page},
+        )
+
+    def list_staking_offers(self) -> list[Vault]:
+        """``GET /api/staking``.
+
+        Examples:
+            offers = client.list_staking_offers()
+        """
+        return self._request("GET", "/api/staking")
+
+    def set_auto_stake(self, offer_id: str, value: bool) -> BooleanConfiguration:
+        """``PUT /api/staking/{id}/auto-stake``. Requires write access.
+
+        Examples:
+            setting = client.set_auto_stake(
+                "8120a8a8-8dd1-4168-80fc-c4d932ce5b93",
+                True,
+            )
+        """
+        return self._request(
+            "PUT",
+            f"/api/staking/{_segment(offer_id)}/auto-stake",
+            body={"value": value},
+        )
+
+    def set_staking_notifications(self, offer_id: str, value: bool) -> BooleanConfiguration:
+        """``PUT /api/staking/{id}/notifications``. Requires write access.
+
+        Examples:
+            setting = client.set_staking_notifications(
+                "8120a8a8-8dd1-4168-80fc-c4d932ce5b93",
+                False,
+            )
+        """
+        return self._request(
+            "PUT",
+            f"/api/staking/{_segment(offer_id)}/notifications",
+            body={"value": value},
+        )
+
+    def resolve_address(self, transfer_method: str, name: str) -> EnsResolution:
+        """``GET /api/addresses/resolve``.
+
+        Resolves an ASCII ENS name. The token expires after 15 minutes.
+
+        Examples:
+            resolved = client.resolve_address("eth", "alice.eth")
+        """
+        return self._request(
+            "GET",
+            "/api/addresses/resolve",
+            query={"transferMethod": transfer_method, "name": name},
+        )
+
+    def get_guarantee_public_key(self) -> str:
+        """``GET /api/guarantee/public-key``.
+
+        Returns armored OpenPGP certificates.
+
+        Examples:
+            certificates = client.get_guarantee_public_key()
+        """
+        return self._request("GET", "/api/guarantee/public-key", text=True)
+
+    def get_order_guarantee(self, order_id: str) -> str:
+        """``GET /api/orders/{id}/guarantee``.
+
+        Returns the stored clear-signed letter. Access matches ``get_order``.
+
+        Examples:
+            letter = client.get_order_guarantee("BV2MTZAF")
+        """
+        return self._request("GET", f"/api/orders/{_segment(order_id)}/guarantee", text=True)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Mapping[str, Any] | None = None,
+        text: bool = False,
+    ) -> Any:
+        headers: dict[str, str] = {}
+        if self._api_key:
+            headers["X-API-KEY"] = self._api_key
+        params = _omit_none(dict(query)) if query is not None else None
+        try:
+            response = self._http.request(
+                method,
+                path,
+                params=params,
+                json=dict(body) if body is not None else None,
+                headers=headers or None,
+            )
+        except httpx.HTTPError as exc:
+            raise BitcoinVnError(str(exc), status=0, code=0, raw=str(exc)) from exc
+        return _decode(response, text=text)
+
+
+def _segment(value: str) -> str:
+    return quote(value, safe="")
+
+
+def _omit_none(values: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _retry_after(response: httpx.Response) -> int | None:
+    raw = response.headers.get("x-ratelimit-retry-after")
+    if raw is None or not str(raw).strip():
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+def _decode(response: httpx.Response, *, text: bool) -> Any:
+    retry_after = _retry_after(response)
+    if response.status_code >= 400:
+        raise _error_response(response, retry_after)
+    if text:
+        return response.text
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise BitcoinVnError(
+            "Response was not JSON",
+            status=response.status_code,
+            code=response.status_code,
+            raw=response.text,
+        ) from exc
+
+
+def _error_response(response: httpx.Response, retry_after: int | None) -> BitcoinVnError:
+    raw: Any
+    try:
+        raw = response.json()
+    except ValueError:
+        raw = response.text
+    error = raw.get("error") if isinstance(raw, dict) else None
+    if isinstance(error, dict):
+        message = error.get("message")
+        code = error.get("code")
+        text = message.strip() if isinstance(message, str) and message.strip() else ""
+        if not text:
+            text = f"HTTP {response.status_code}"
+        status_code = code if isinstance(code, int) else response.status_code
+        return BitcoinVnError(
+            text,
+            status=response.status_code,
+            code=status_code,
+            raw=raw,
+            details=error.get("details"),
+            retry_after=retry_after,
+        )
+    if isinstance(raw, str) and raw.strip():
+        message = raw.strip()
+    else:
+        message = f"HTTP {response.status_code}"
+    return BitcoinVnError(
+        message,
+        status=response.status_code,
+        code=response.status_code,
+        raw=raw,
+        retry_after=retry_after,
+    )

bitcoinvn/errors.py

@@ -0,0 +1,52 @@
+"""Errors returned by the BitcoinVN API and transport failures."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class BitcoinVnError(Exception):
+    """HTTP error envelope from BitcoinVN, or a transport failure.
+
+    Responses with status 4xx or 5xx use ``error.message`` and ``error.code``.
+    ``code`` equals the HTTP status. ``retry_after`` is set from the
+    ``X-RateLimit-Retry-After`` header when it is present. A transport failure
+    uses ``status`` 0 and ``code`` 0.
+
+    Examples:
+        try:
+            client.get_ticker("BTC", "USDT")
+        except BitcoinVnError as error:
+            if error.code == 404:
+                pass
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: int,
+        raw: Any = None,
+        details: Any = None,
+        retry_after: int | None = None,
+    ) -> None:
+        """Create an error.
+
+        Args:
+            message: Text from ``error.message``, or a transport message.
+            status: HTTP status, or 0 when the request was not sent.
+            code: API ``error.code``, or ``status`` when the body has no envelope.
+            raw: Original response body.
+            details: ``error.details`` when the API sent validation details.
+            retry_after: Seconds from ``X-RateLimit-Retry-After``.
+
+        Examples:
+            raise BitcoinVnError("Pair does not exist.", status=404, code=404)
+        """
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.raw = message if raw is None else raw
+        self.details = details
+        self.retry_after = retry_after

bitcoinvn/types.py

@@ -0,0 +1,238 @@
+"""Types for the BitcoinVN exchange API.
+
+Response dictionaries keep the JSON names from the OpenAPI spec.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+OrderStatus = Literal[
+    "new",
+    "pending",
+    "settle_data_error",
+    "on_hold",
+    "processing",
+    "completed",
+    "canceled",
+]
+
+
+class HealthStatus(TypedDict):
+    """Body of ``GET /api/health``."""
+
+    status: Literal["ok"]
+
+
+class AssetRequired(TypedDict):
+    """Required asset fields from ``GET /api/info``."""
+
+    id: str
+    name: str
+    exchangeFee: float
+    bridgeFee: float
+    tags: list[str]
+
+
+class Asset(AssetRequired, total=False):
+    """Asset record. ``sameAs`` is set when the asset aliases another asset."""
+
+    sameAs: str | None
+
+
+class SettleDataField(TypedDict):
+    """One external payout field on a transfer method."""
+
+    name: str
+    required: bool
+
+
+class TransferMethodRequired(TypedDict):
+    """Required transfer-method fields."""
+
+    enabled: bool
+    id: str
+    asset: str
+    decimals: int
+    depositEnabled: bool
+    settleEnabled: bool
+    internalBalance: bool
+    tags: list[str]
+
+
+class TransferMethod(TransferMethodRequired, total=False):
+    """Transfer method. Use ``id`` exactly as returned by ``GET /api/info``."""
+
+    settleDataFields: list[SettleDataField]
+    batched: bool
+    predictedSettleWaitTime: int
+    network: str | None
+    extraLabel: str | None
+    networkFee: float
+    depositFee: float
+    settleFee: float
+    exchangeFee: float
+    exchangeBalanceIndex: float
+    infoUrl: str | None
+    minOrderSize: float | None
+    maxOrderSize: float | None
+    invoice: bool
+    warning: str
+    tokenId: str | None
+    details: dict[str, Any] | None
+
+
+class Info(TypedDict):
+    """Public catalogs from ``GET /api/info``."""
+
+    assets: dict[str, Asset]
+    transferMethods: dict[str, TransferMethod]
+
+
+class PairRequired(TypedDict):
+    """Required pair fields."""
+
+    rate: float
+    min: float
+
+
+class Pair(PairRequired, total=False):
+    """Rate and deposit range. ``max`` below ``min`` means no valid range."""
+
+    max: float | None
+
+
+class Ticker(TypedDict):
+    """Public rate and 24-hour volume."""
+
+    rate: float
+    volume24h: float
+
+
+class AddressValidationRequired(TypedDict):
+    """Required address-validation field."""
+
+    valid: bool
+
+
+class AddressValidation(AddressValidationRequired, total=False):
+    """Result of ``GET /api/addresses/validate``."""
+
+    error: str | None
+
+
+class QuoteRequired(TypedDict):
+    """Required quote fields."""
+
+    depositMethod: str
+    settleMethod: str
+
+
+class Quote(QuoteRequired, total=False):
+    """Quote from ``POST /api/quotes`` or nested on an order."""
+
+    id: str
+    depositAmount: float | None
+    depositFee: float
+    settleAmount: float | None
+    settleFee: float
+    rate: float
+    rawRate: float
+    createdAt: str
+    expiresAt: str
+    accepted: bool
+    markupRate: float | None
+
+
+class OrderRequired(TypedDict):
+    """Required order fields."""
+
+    id: str
+    shortId: str
+    status: OrderStatus
+    depositMethod: str
+    depositAsset: str
+    depositFee: float
+    depositData: dict[str, Any]
+    settleMethod: str
+    settleAsset: str
+    settleFee: float
+    settleData: dict[str, Any]
+    depositMin: float
+    createdAt: str
+    expiresAt: str
+
+
+class Order(OrderRequired, total=False):
+    """Order object returned by the order endpoints and by order webhooks."""
+
+    customOrderId: str
+    depositAmount: float | None
+    depositConfsRequired: int | None
+    depositTxns: list[str]
+    settleAmount: float | None
+    settleTxns: list[str]
+    settleReceiptUrl: str
+    settleProof: dict[str, Any] | None
+    rate: float
+    depositMax: float
+    quote: Quote
+    adminMessage: str | None
+
+
+class LedgerItemRequired(TypedDict):
+    """Required ledger fields."""
+
+    id: str
+    asset: str
+    value: float
+    createdAt: str
+
+
+class LedgerItem(LedgerItemRequired, total=False):
+    """One balance-history row."""
+
+    note: str
+
+
+class VaultRequired(TypedDict):
+    """Required staking-offer fields."""
+
+    id: str
+    asset: str
+    distribution: float
+    supplyTarget: float
+    staked: float
+    latestApr: float
+    latestFullyDilutedApr: float
+
+
+class Vault(VaultRequired, total=False):
+    """Staking offer from ``GET /api/staking``."""
+
+    tvl: float
+    unstakingFee: float
+
+
+class BooleanConfiguration(TypedDict):
+    """Staking preference body."""
+
+    value: bool
+
+
+class EnsResolution(TypedDict):
+    """Signed ENS resolution. Times are Unix seconds."""
+
+    name: str
+    address: str
+    transferMethod: str
+    networkId: str
+    networkName: str
+    chainId: int
+    resolvedAt: int
+    expiresAt: int
+    ensResolutionToken: str
+
+
+# Available balances keyed by asset id.
+Balances = dict[str, float]

bitcoinvn-0.1.0.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: bitcoinvn
+Version: 0.1.0
+Summary: Python client for the BitcoinVN exchange API
+Project-URL: Repository, https://github.com/TysikGG/api-kit
+Project-URL: Documentation, https://bitcoinvn.io/api/doc.json
+License-Expression: ISC
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# bitcoinvn
+
+[![PyPI version](https://img.shields.io/pypi/v/bitcoinvn.svg)](https://pypi.org/project/bitcoinvn/)
+[![Python versions](https://img.shields.io/pypi/pyversions/bitcoinvn.svg)](https://pypi.org/project/bitcoinvn/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+Modern, typed Python client for the [BitcoinVN Exchange API](https://bitcoinvn.io/api/doc.json) — Vietnam's premier cryptocurrency exchange and instant swap platform. Built on [HTTPX](https://www.python-httpx.org).
+
+Official API documentation:
+- OpenAPI specification: <https://bitcoinvn.io/api/doc.json>
+- Exchange website: <https://bitcoinvn.io>
+
+---
+
+## Features
+
+- 📊 **Public Market Data** — Tickers, real-time exchange rates, pair metadata, and system status (no API key required).
+- 🔄 **Instant Swaps & Quotes** — Calculate competitive quotes for crypto-to-crypto and crypto-to-fiat trades.
+- 📦 **Order Management** — Create orders with support for crypto wallets, Lightning Network invoices, destination tags, bank wires, and cash pickups.
+- 💰 **Balances & History** — Inspect internal wallet balances, transaction ledgers, and attach deposit transaction IDs.
+- 📈 **Staking Vaults** — Discover staking opportunities, toggle auto-staking, and adjust notification alerts.
+- 🛡️ **Cryptographic Proofs** — Retrieve and verify BitcoinVN cryptographic guarantee letters and public keys.
+- ⚡ **Resilient** — Context manager support (`with BitcoinVn(...) as client:`), type annotations, and rate-limit handling (`retry_after` header).
+
+---
+
+## Installation
+
+```bash
+pip install bitcoinvn
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check queries the public market ticker for `BTC/USDT`. It does not require an API key and does not place orders or move funds.
+
+```python
+import os
+from bitcoinvn import BitcoinVn
+
+# Anonymous client for public market queries (or pass api_key)
+api_key = os.environ.get("BITCOINVN_API_KEY")
+
+with BitcoinVn(api_key) as client:
+    ticker = client.get_ticker("BTC", "USDT")
+    print(f"Rate: {ticker['rate']}, 24h Volume: {ticker['volume24h']}")
+```
+
+---
+
+## Usage Guide
+
+### 1. Authentication
+
+Public read operations (health, info, pairs, ticker, address validation) work without a key.
+
+For account-specific operations (viewing balances, order history, internal balance orders, staking), pass your API key:
+
+```python
+from bitcoinvn import BitcoinVn
+
+with BitcoinVn(api_key="your_api_key_here") as client:
+    balances = client.get_balances()
+    print(balances)
+```
+
+API keys can be generated in your account dashboard on [bitcoinvn.io](https://bitcoinvn.io).
+
+### 2. Market Pairs and Quotes
+
+Inspect supported trading pairs and request live price quotes:
+
+```python
+from bitcoinvn import BitcoinVn
+
+with BitcoinVn() as client:
+    # Fetch trading pair specifications and limits
+    pair = client.get_pair("btc", "usdt")
+    print(f"Min: {pair['minDeposit']}, Max: {pair['maxDeposit']}")
+
+    # Request an instant quote
+    quote = client.create_quote(
+        deposit_method="btc",
+        settle_method="usdt",
+        deposit_amount=0.05,
+    )
+    print(f"Expected settle amount: {quote['settleAmount']}")
+```
+
+### 3. Creating and Managing Orders
+
+Create an exchange order with specific settlement details:
+
+```python
+from bitcoinvn import BitcoinVn
+
+with BitcoinVn(api_key=os.environ.get("BITCOINVN_API_KEY")) as client:
+    # Create an order swapping BTC for USDT
+    order = client.create_order(
+        deposit_method="btc",
+        settle_method="usdt",
+        settle_amount=1000,
+        settle_data={"address": "0xYourUsdtAddressHere..."},
+    )
+    print(f"Order created: {order['shortId']}")
+    print(f"Send BTC deposit to: {order['depositAddress']}")
+
+    # Check order status
+    status = client.get_order(order["shortId"])
+    print(f"Order status: {status['status']}")
+```
+
+### 4. Account Balances and History
+
+Inspect your account's internal wallet balances and ledger transactions:
+
+```python
+with BitcoinVn(api_key=os.environ["BITCOINVN_API_KEY"]) as client:
+    # List balances
+    balances = client.get_balances()
+    print(balances)
+
+    # List ledger history
+    history = client.list_balance_history(limit=10)
+    for entry in history:
+        print(f"{entry['createdAt']}: {entry['amount']} {entry['asset']}")
+```
+
+---
+
+## Error Handling
+
+When the API returns a `4xx` or `5xx` error, the client raises a `BitcoinVnError` containing HTTP status code, API error message, and rate-limit backoff details:
+
+```python
+from bitcoinvn import BitcoinVn, BitcoinVnError
+
+with BitcoinVn() as client:
+    try:
+        client.get_ticker("INVALID", "PAIR")
+    except BitcoinVnError as err:
+        print(f"BitcoinVN error [{err.status_code}]: {err.message}")
+        if err.status_code == 429 and err.retry_after:
+            print(f"Rate limited. Retry after {err.retry_after} seconds.")
+```
+
+---
+
+## Partner Referrer ID
+
+In accordance with BitcoinVN's partner program, outgoing `POST /api/orders` requests automatically include the required referrer identifier in the payload.
+
+---
+
+## License
+
+[ISC](LICENSE) © api-kit contributors

bitcoinvn-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+bitcoinvn/__init__.py,sha256=HfBLwfyZSHo-EjMJt-J5As10Vzy0DeXGz3f6ATWs8Hc,1132
+bitcoinvn/client.py,sha256=1i2kPLNsOrAeo-3eBgHGnfBkVxGX784oOGG3k084Fs4,15039
+bitcoinvn/errors.py,sha256=Ye10Jtxi0R7kh0xWR0ChEKT7MdNhYqJsaYBac1bvV3c,1659
+bitcoinvn/types.py,sha256=U_v22vXfCyRGoIclJwNUrXkdPutZ_meojfvS-iR3JBQ,4785
+bitcoinvn-0.1.0.dist-info/METADATA,sha256=STq3mkWEfqvJI_PGeOlKVEMVwfl3n5M2xuvSdd4whwY,5558
+bitcoinvn-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bitcoinvn-0.1.0.dist-info/licenses/LICENSE,sha256=8S0uYmn_aeljwFudfBoV91HcIo79yab9s0yhMVsOHJ0,751
+bitcoinvn-0.1.0.dist-info/RECORD,,

bitcoinvn-0.1.0.dist-info/WHEEL

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

bitcoinvn-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 api-kit contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.