bitcoinvn 0.1.0__tar.gz

bitcoinvn-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Dependencies
+node_modules/
+.pnp.*
+.yarn/
+.pnpm-store/
+
+# Build
+dist/
+build/
+*.tsbuildinfo
+*.egg-info/
+.eggs/
+wheels/
+
+# Tests and coverage
+coverage/
+.nyc_output/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# GitBook / HonKit
+_book/
+
+# OS and editors
+.DS_Store
+Thumbs.db
+.idea/
+*.swp

bitcoinvn-0.1.0/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.

bitcoinvn-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,161 @@
+# 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/examples/check.py

@@ -0,0 +1,16 @@
+"""Read a public ticker. Does not create an order."""
+
+import os
+
+from bitcoinvn import BitcoinVn
+
+
+def main() -> None:
+    api_key = os.environ.get("BITCOINVN_API_KEY")
+    with BitcoinVn(api_key) as client:
+        ticker = client.get_ticker("BTC", "USDT")
+        print(ticker["rate"], ticker["volume24h"])
+
+
+if __name__ == "__main__":
+    main()

bitcoinvn-0.1.0/pydoc-markdown.yml

@@ -0,0 +1,13 @@
+loaders:
+  - type: python
+    search_path: [src]
+processors:
+  - type: filter
+    documented_only: true
+    skip_empty_modules: true
+  - type: smart
+  - type: crossref
+renderer:
+  type: markdown
+  filename: ../../docs/bitcoinvn/python/bitcoinvn.md
+  render_module_header: true

bitcoinvn-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bitcoinvn"
+version = "0.1.0"
+description = "Python client for the BitcoinVN exchange API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "ISC"
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.urls]
+Repository = "https://github.com/TysikGG/api-kit"
+Documentation = "https://bitcoinvn.io/api/doc.json"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-httpx>=0.30",
+  "ruff>=0.8",
+  "pydoc-markdown>=4.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bitcoinvn"]
+
+[tool.pytest.ini_options]
+markers = [
+  "live: calls the real BitcoinVN API and needs BITCOINVN_API_KEY",
+]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

bitcoinvn-0.1.0/src/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"