aioheleket

https://github.com/superfeda/aioheleket
Admin
Asynchronous Python library for the Heleket crypto payment API, enabling developers to create...
Tokens:15,110
Snippets:68
Trust Score:4.3
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install aioheleket with pip

Source: https://context7.com/superfeda/aioheleket/llms.txt

Install the library using pip.

```bash
pip install aioheleket
```

--------------------------------

### Install aioheleket with uv

Source: https://context7.com/superfeda/aioheleket/llms.txt

Install the library using uv.

```bash
uv pip install aioheleket
```

--------------------------------

### Install aioheleket

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Installation commands for the library using pip or uv.

```shell
pip install aioheleket
```

```shell
uv pip install aioheleket
```

--------------------------------

### Use HeleketClient as an Async Context Manager

Source: https://context7.com/superfeda/aioheleket/llms.txt

Utilize the async context manager for automatic session cleanup. This example demonstrates fetching and printing cryptocurrency balances.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency

async def main() -> None:
    async with HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    ) as client:
        finance_service = await client.finance_service()
        balance = await finance_service.balance()

        for bal in balance.merchant:
            print(f"{bal.currency_code}: {bal.crypto_balance} ({bal.usd_balance} USD)")
        # Session automatically closed on exit

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Get Merchant and User Balances

Source: https://context7.com/superfeda/aioheleket/llms.txt

Retrieves the balances for both the merchant and user wallets. Displays crypto and USD balances for merchant wallets, and crypto balances for user wallets.

```python
import asyncio
from aioheleket import HeleketClient

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    finance_service = await client.finance_service()

    balance = await finance_service.balance()

    print("=== Merchant Balance ===")
    for bal in balance.merchant:
        print(f"{bal.currency_code}:")
        print(f"  Crypto: {bal.crypto_balance}")
        print(f"  USD: {bal.usd_balance}")
        print(f"  Wallet UUID: {bal.uuid}")

    print("\n=== User Balance ===")
    for bal in balance.user:
        print(f"{bal.currency_code}: {bal.crypto_balance} (${bal.usd_balance})")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Get exchange rates

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Fetches current exchange rates for specific or all available currencies using the finance service.

```python
import asyncio

from aioheleket import HeleketClient, CryptoCurrency, FiatCurrency


async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    finance_service = await client.finance_service()
    
    print("--- BTC exchange rates for RUB, KZT, and TRX")
    target_currencies = (FiatCurrency.RUB, CryptoCurrency.TRX, FiatCurrency.KZT)
    btc_rate = await finance_service.exchange_rate(CryptoCurrency.BTC, target_currencies)
    for i, rate in enumerate(btc_rate, 1):
        print(f"{i}) {rate.to}: {rate.course}")
    
    print("\n--- All BTC exchange rates")
    all_btc_rates = await finance_service.exchange_rate(CryptoCurrency.BTC)
    for i, rate in enumerate(all_btc_rates, 1):  # output all rates for BTC
        print(f"{i}) {rate.to}: {rate.course}")

    await client.close_session()  # <!>


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Get Payment Service Information

Source: https://context7.com/superfeda/aioheleket/llms.txt

Retrieve information about available payment services, including their availability, minimum and maximum transaction limits, and commission details (percentage and fixed fee).

```python
import asyncio
from aioheleket import HeleketClient

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()

    services = await payment_service.services_info()
    for service in services:
        print(f"Currency: {service.currency} on {service.network}")
        print(f"  Available: {service.is_available}")
        print(f"  Min: {service.limit.min_amount}, Max: {service.limit.max_amount}")
        print(f"  Fee: {service.commission.percent}% + {service.commission.fee_amount}")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Get Cryptocurrency Exchange Rates

Source: https://context7.com/superfeda/aioheleket/llms.txt

Fetches current exchange rates for cryptocurrencies against various fiat and crypto currencies. Requires HeleketClient initialization with merchant ID and API key.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency, FiatCurrency

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    finance_service = await client.finance_service()

    # Get all BTC exchange rates
    btc_rates = await finance_service.exchange_rate(CryptoCurrency.BTC)
    print("BTC Exchange Rates:")
    for rate in btc_rates:
        print(f"  BTC -> {rate.to}: {rate.course}")

    # Get specific rates only
    target_currencies = (FiatCurrency.USD, FiatCurrency.EUR, CryptoCurrency.USDT)
    eth_rates = await finance_service.exchange_rate(CryptoCurrency.ETH, target_currencies)
    print("\nETH Selected Rates:")
    for rate in eth_rates:
        print(f"  ETH -> {rate.to}: {rate.course}")

    # Get USDT rates for fiat currencies
    usdt_fiat = await finance_service.exchange_rate(
        CryptoCurrency.USDT,
        (FiatCurrency.RUB, FiatCurrency.KZT, FiatCurrency.TRY)
    )
    for rate in usdt_fiat:
        print(f"1 USDT = {rate.course} {rate.to}")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### GET Payout Information

Source: https://context7.com/superfeda/aioheleket/llms.txt

Retrieves details about a specific payout using either a UUID or an order ID.

```APIDOC
## GET /payout_info

### Description
Retrieves information about an existing payout by its unique identifier.

### Parameters
#### Query Parameters
- **uuid** (string) - Optional - The unique identifier of the payout.
- **order_id** (string) - Optional - The merchant-defined order ID.

### Response
#### Success Response (200)
- **status** (string) - Current status of the payout.
- **is_final** (boolean) - Indicates if the payout status is final.
- **txid** (string) - Transaction ID on the blockchain.
- **address** (string) - Destination address.
- **balance** (string) - Remaining balance.
- **convert** (object) - Optional conversion details (from_currency, to_currency, rate).
```

--------------------------------

### aioheleket Enums Reference

Source: https://context7.com/superfeda/aioheleket/llms.txt

Provides available enums for type-safe API calls, including cryptocurrencies, fiat currencies, networks, lifetimes, priorities, and payment/payout statuses. Examples demonstrate usage for Lifetime and Priority enums.

```python
from aioheleket import (
    CryptoCurrency,    # USDT, BTC, ETH, LTC, TRX, SOL, TON, DOGE, etc.
    FiatCurrency,      # USD, EUR, RUB, KZT, TRY, etc.
    Network,           # TRON, ETH, BSC, POLYGON, BTC, LTC, SOL, TON, etc.
    Lifetime,          # MINUTE_5 to HOUR_12 (invoice lifetime in seconds)
    Priority,          # ECONOMY, RECOMMENDED, HIGH, HIGHEST
    PaymentStatus,     # PROCESS, CHECK, PAID, PAID_OVER, FAIL, CANCEL, etc.
    PayoutStatus,      # PROCESS, CHECK, PAID, FAIL, CANCEL, SYSTEM_FAIL
    StaticWalletStatus,# ACTIVE, BLOCKED, IN_ACTIVE, PAID, etc.
    CourseSource       # BINANCE, EXMO, KUCOIN, BINANCEP2P, GARANTEXIO
)

# Lifetime examples
Lifetime.MINUTE_5   # 300 seconds (minimum)
Lifetime.HOUR_1     # 3600 seconds (default)
Lifetime.HOUR_12    # 43200 seconds (maximum)

# Priority examples
Priority.ECONOMY      # Lower fees, slower
Priority.RECOMMENDED  # Balanced (default)
Priority.HIGH         # Higher fees, faster
Priority.HIGHEST      # Maximum speed
```

--------------------------------

### GET Payout History

Source: https://context7.com/superfeda/aioheleket/llms.txt

Retrieves a list of payouts with optional date range filtering.

```APIDOC
## GET /payout_history

### Description
Retrieves the history of payouts, optionally filtered by a date range.

### Parameters
#### Query Parameters
- **date_from** (datetime) - Optional - Start date for filtering.
- **date_to** (datetime) - Optional - End date for filtering.

### Response
#### Success Response (200)
- **paginate** (object) - Pagination metadata including total count.
- **items** (array) - List of payout objects containing uuid, amount, currency, status, is_final, and created_at.
```

--------------------------------

### Retrieve Payment History

Source: https://context7.com/superfeda/aioheleket/llms.txt

Get a list of past payments. Supports filtering by date range and pagination for handling large datasets. The response includes pagination details like total count and next cursor.

```python
import asyncio
from datetime import datetime
from aioheleket import HeleketClient

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()

    # Get all payment history
    history = await payment_service.payment_history()
    print(f"Total items: {history.paginate.count}")
    print(f"Has more pages: {history.paginate.hasPages}")
    print(f"Next cursor: {history.paginate.nextCursor}")

    for payment in history.items:
        print(f"Order: {payment.order_id}, Status: {payment.status}, Amount: {payment.amount}")

    # Get history with date filtering
    history_filtered = await payment_service.payment_history(
        date_from=datetime(2024, 1, 1),
        date_to=datetime(2024, 12, 31)
    )

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Initialize HeleketClient with async with

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Use the `async with` statement for proper client initialization and cleanup. Ensure you have the necessary payment API key.

```python
import asyncio

from aioheleket import HeleketClient, CryptoCurrency, FiatCurrency


async def main() -> None:
    async with HeleketClient(
            merchant_id="<merchant_id>", 
            payment_api_key="<payment_api_key>"
    ) as client:
        finance_service = await client.finance_service()
        ...


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Initialize HeleketClient without async with

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Instantiate the HeleketClient by providing merchant ID and relevant API keys. Remember to manually close the session when done.

```python
import asyncio

from aioheleket import HeleketClient


async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payout_api_key="<payout_api_key>",
        payment_api_key="<payment_api_key>"
    )
    ...

    await client.close_session()  # <!>


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Manage Discounts with PaymentService

Source: https://context7.com/superfeda/aioheleket/llms.txt

Set and list discounts for specific cryptocurrency and network combinations. A positive `discount_percent` applies a discount, while a negative value applies a surcharge. Use `discount_list()` to retrieve all currently set discounts.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency, Network

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()

    # Set a 5% discount for USDT on TRON
    discount = await payment_service.set_discount(
        currency=CryptoCurrency.USDT,
        network=Network.TRON,
        discount_percent=5  # Positive = discount, Negative = surcharge
    )
    print(f"Set discount: {discount.discount}% for {discount.currency}/{discount.network}")

    # Set a 3% surcharge for BTC
    surcharge = await payment_service.set_discount(
        currency=CryptoCurrency.BTC,
        network=Network.BTC,
        discount_percent=-3
    )

    # List all discounts
    discounts = await payment_service.discount_list()
    for d in discounts:
        print(f"{d.currency}/{d.network}: {d.discount}%")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Initialize HeleketClient

Source: https://context7.com/superfeda/aioheleket/llms.txt

Basic initialization requires merchant ID and API keys. Custom request configurations can be provided for timeout, retries, and connection limits.

```python
import asyncio
from aioheleket import HeleketClient, RequestConfig

async def main() -> None:
    # Basic initialization with both API keys
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>",  # Required for payment, wallet, finance services
        payout_api_key="<payout_api_key>"     # Required for payout service
    )

    # With custom request configuration
    client_with_config = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>",
        config=RequestConfig(
            timeout_s=30.0,           # Request timeout (default: 20.0)
            max_retries=4,            # Retry attempts (default: 2)
            retry_backoff_s=0.5,      # Backoff delay (default: 0.25)
            connector_limit=80,       # Total connections (default: 100)
            connector_limit_per_host=40,  # Per-host connections (default: 50)
            ttl_dns_cache=600         # DNS cache TTL (default: 300)
        )
    )

    # Use services...

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Create a static wallet

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Uses the static wallet service to generate a new wallet address for a specific currency and network.

```python
import asyncio

from aioheleket import HeleketClient, Network, CryptoCurrency


async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    wallet_service = await client.static_wallet_service()
    
    wallet = await wallet_service.create_wallet(
        currency=CryptoCurrency.USDT,
        network=Network.ETH,
        order_id="wal_usdt"
    )
    print(wallet.uuid, wallet.url)

    await client.close_session()  # <!>


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Create a payment invoice

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Initializes a HeleketClient and uses the payment service to generate a new invoice.

```python
import asyncio

from aioheleket import HeleketClient, CryptoCurrency, Network, Lifetime


async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()
    
    payment = await payment_service.create_invoice(
        currency=CryptoCurrency.USDT,
        network=Network.ETH,
        order_id="order_3331",
        amount="2",
        lifetime=Lifetime.HOUR_5
    )
    print(payment.url, payment.uuid, payment.address)

    await client.close_session()  # <!>


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Generate QR Code for Static Wallet

Source: https://context7.com/superfeda/aioheleket/llms.txt

Generates a QR code for a static wallet address. Requires creating a wallet first and then using its UUID to generate the QR code, which is then saved to a PNG file.

```python
import asyncio
import base64
from aioheleket import HeleketClient, CryptoCurrency, Network

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    wallet_service = await client.static_wallet_service()

    # Create wallet
    wallet = await wallet_service.create_wallet(
        currency=CryptoCurrency.ETH,
        network=Network.ETH,
        order_id="wallet_qr_demo"
    )

    # Generate QR code
    qr_base64 = await wallet_service.generate_qr_code(wallet.uuid)

    # Save to file
    with open("wallet_qr.png", "wb") as f:
        f.write(base64.b64decode(qr_base64))
    print(f"QR code saved for wallet {wallet.address}")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### POST Create Static Wallet

Source: https://context7.com/superfeda/aioheleket/llms.txt

Creates a static wallet address for receiving recurring payments.

```APIDOC
## POST /create_wallet

### Description
Generates a static wallet address for receiving recurring payments.

### Parameters
#### Request Body
- **currency** (CryptoCurrency) - Required - The cryptocurrency type.
- **network** (Network) - Required - The blockchain network.
- **order_id** (string) - Required - Merchant-defined order ID.
- **url_callback** (string) - Optional - Webhook URL for notifications.
- **from_referral_code** (string) - Optional - Referral code.

### Response
#### Success Response (200)
- **uuid** (string) - Unique identifier for the wallet.
- **wallet_uuid** (string) - Master wallet UUID.
- **address** (string) - The generated wallet address.
- **url** (string) - Payment URL.
```

--------------------------------

### Create Static Wallet

Source: https://context7.com/superfeda/aioheleket/llms.txt

Generates a static wallet address for receiving payments. Supports optional referral codes and webhook callbacks.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency, Network

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    wallet_service = await client.static_wallet_service()

    # Create static wallet for USDT on TRON
    wallet = await wallet_service.create_wallet(
        currency=CryptoCurrency.USDT,
        network=Network.TRON,
        order_id="user_wallet_001",
        url_callback="https://mysite.com/webhook/wallet"
    )
    print(f"Wallet UUID: {wallet.uuid}")
    print(f"Master wallet UUID: {wallet.wallet_uuid}")
    print(f"Address: {wallet.address}")
    print(f"Payment URL: {wallet.url}")

    # Create ETH wallet with referral code
    eth_wallet = await wallet_service.create_wallet(
        currency=CryptoCurrency.ETH,
        network=Network.ETH,
        order_id="user_wallet_eth_001",
        from_referral_code="REF123"
    )

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Create a new invoice using payment_service

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Access the payment service from the client to create a new invoice. Requires `payment_api_key`. Ensure to close the client session.

```python
import asyncio

from aioheleket import HeleketClient


async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()
    
    payment = await payment_service.create_invoice(
        amount="2",
        currency="USDT",
        network="ETH",
        order_id="orderid_2usdt",
        lifetime=5_000
    )
    print(payment)
    
    await client.close_session()  # <!>


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### View account balances

Source: https://github.com/superfeda/aioheleket/blob/master/README.md

Retrieves and prints user and merchant balances using the finance service.

```python
import asyncio

from aioheleket import HeleketClient


async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    finance_service = await client.finance_service()

    balance = await finance_service.balance()

    print("--- User balance")
    for i, balance_info in enumerate(balance.user, 1):
        print(f"{i}) {balance_info.currency_code}\nAmount: {balance_info.crypto_balance}\nAmount in USD: {balance_info.usd_balance}\nUUID: {balance_info.uuid}\n")

    print("\n--- Merchant balance")
    for i, balance_info in enumerate(balance.merchant, 1):
        print(f"{i}) {balance_info.currency_code}\nAmount: {balance_info.crypto_balance}\nAmount in USD: {balance_info.usd_balance}\nUUID: {balance_info.uuid}\n")

    await client.close_session()  # <!>


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Create Cryptocurrency Invoice

Source: https://context7.com/superfeda/aioheleket/llms.txt

Use this to create a new payment invoice for cryptocurrency. Supports basic and advanced options like callbacks, discounts, and currency restrictions. Ensure you have the HeleketClient initialized with your merchant credentials.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency, Network, Lifetime

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()

    # Basic payment creation
    payment = await payment_service.create_invoice(
        amount="10.50",
        currency=CryptoCurrency.USDT,
        network=Network.TRON,
        order_id="order_12345",
        lifetime=Lifetime.HOUR_1  # 3600 seconds
    )
    print(f"Payment URL: {payment.url}")
    print(f"UUID: {payment.uuid}")
    print(f"Address: {payment.address}")
    print(f"Expires at: {payment.expired_at}")

    # Advanced payment with callbacks and options
    payment_advanced = await payment_service.create_invoice(
        amount="100",
        currency=CryptoCurrency.USDT,
        network=Network.ETH,
        order_id="order_premium_001",
        lifetime=Lifetime.HOUR_5,
        url_callback="https://mysite.com/webhook/payment",
        url_success="https://mysite.com/payment/success",
        url_return="https://mysite.com/payment/cancel",
        is_payment_multiple=True,      # Allow partial payments
        subtract=50,                   # Client pays 50% of commission
        accuracy_payment_percent=2,    # Accept 98% of amount as paid
        discount_percent=5,            # 5% discount
        additional_data="Premium subscription",
        payer_email="customer@example.com"
    )
    print(f"Payer amount: {payment_advanced.payer_amount}")
    print(f"Discount: {payment_advanced.discount}")

    # Payment with currency restrictions
    payment_restricted = await payment_service.create_invoice(
        amount="50",
        currency=CryptoCurrency.USDT,
        order_id="order_restricted",
        currencies=[
            {"currency": "USDT", "network": "TRON"},
            {"currency": "USDT", "network": "ETH"},
            {"currency": "BTC"}
        ]
    )

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Create Cryptocurrency Payout with PayoutService

Source: https://context7.com/superfeda/aioheleket/llms.txt

Create a basic cryptocurrency payout using PayoutService. Specify amount, currency, network, order ID, and recipient address. The `is_subtract` parameter determines if the fee is deducted from the merchant's balance or the payout amount. Requires initialization of HeleketClient with payout API key.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency, Network, FiatCurrency, Priority

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payout_api_key="<payout_api_key>"
    )
    payout_service = await client.payout_service()

    # Basic payout in cryptocurrency
    payout = await payout_service.create_invoice(
        amount="100",
        currency=CryptoCurrency.USDT,
        network=Network.TRON,
        order_id="payout_001",
        address="TN3W4H6R8ciD4yYRbz9bq3dWQuT4k5Rq9t",
        is_subtract=True  # Fee from merchant balance
    )
    print(f"Payout UUID: {payout.uuid}")
    print(f"Status: {payout.status}")
    print(f"Merchant amount: {payout.merchant_amount}")
    print(f"Commission: {payout.commissions}")

    # Payout with fiat amount conversion
    payout_fiat = await payout_service.create_invoice(
        amount="500",
        currency=FiatCurrency.USD,
        to_currency=CryptoCurrency.LTC,
        network=Network.LTC,
        order_id="payout_fiat_001",
        address="ltc1qw508d6qejxtdg4y5r3zarvary0c5xw7kgmn4n9",
        is_subtract=False,  # Fee from payout amount
        url_callback="https://mysite.com/webhook/payout",
        priority=Priority.HIGH
    )

    # Payout with auto-conversion from USDT balance
    payout_convert = await payout_service.create_invoice(
        amount="200",
        currency=FiatCurrency.EUR,
        to_currency=CryptoCurrency.BTC,
        network=Network.BTC,
        order_id="payout_convert_001",
        address="bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        is_subtract=True,
        from_currency="USDT"  # Convert from USDT balance
    )

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### PaymentService.set_discount and discount_list

Source: https://context7.com/superfeda/aioheleket/llms.txt

Allows merchants to set discounts or surcharges for specific currency and network combinations. The `discount_list` endpoint retrieves all currently active discounts.

```APIDOC
## POST /payment/discount

### Description
Set a discount or surcharge for a specific payment method (currency and network).

### Method
POST

### Endpoint
/payment/discount

### Parameters
#### Request Body
- **currency** (string) - Required - The cryptocurrency for which to set the discount.
- **network** (string) - Required - The network on which the currency is supported.
- **discount_percent** (number) - Required - The discount percentage. Positive values represent discounts, negative values represent surcharges.

### Request Example
```json
{
  "currency": "USDT",
  "network": "TRON",
  "discount_percent": 5
}
```

### Response
#### Success Response (200)
- **currency** (string) - The currency for which the discount was set.
- **network** (string) - The network for which the discount was set.
- **discount** (string) - The applied discount percentage.

#### Response Example
```json
{
  "currency": "USDT",
  "network": "TRON",
  "discount": "5.0%"
}
```

## GET /payment/discounts

### Description
Retrieve a list of all currently active discounts and surcharges.

### Method
GET

### Endpoint
/payment/discounts

### Parameters
None

### Response
#### Success Response (200)
- **discounts** (array) - A list of active discounts.
  - **currency** (string) - The currency associated with the discount.
  - **network** (string) - The network associated with the discount.
  - **discount** (string) - The discount percentage.

#### Response Example
```json
[
  {
    "currency": "USDT",
    "network": "TRON",
    "discount": "5.0%"
  },
  {
    "currency": "BTC",
    "network": "BTC",
    "discount": "-3.0%"
  }
]
```
```

--------------------------------

### Generate QR Code using PaymentService

Source: https://context7.com/superfeda/aioheleket/llms.txt

Generate a QR code for a payment address after creating an invoice. The function returns a base64 encoded image string that can be decoded and saved to a file. Requires `payment_service.create_invoice` to be called first.

```python
import asyncio
import base64
from aioheleket import HeleketClient, CryptoCurrency, Network

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()

    # Create payment first
    payment = await payment_service.create_invoice(
        amount="25",
        currency=CryptoCurrency.USDT,
        network=Network.TRON,
        order_id="qr_order_001"
    )

    # Generate QR code (returns base64 encoded image)
    qr_base64 = await payment_service.generate_qr_code(payment.uuid)

    # Save QR code to file
    qr_data = base64.b64decode(qr_base64)
    with open("payment_qr.png", "wb") as f:
        f.write(qr_data)
    print("QR code saved to payment_qr.png")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Calculate Payout Details with PayoutService

Source: https://context7.com/superfeda/aioheleket/llms.txt

Calculate payout amounts and associated fees before creating a payout using PayoutService. This function helps in determining the commission, the amount to be deducted from the merchant's balance, and the final amount to be sent to the recipient. Supports both cryptocurrency and fiat conversions. Requires HeleketClient initialization.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency, FiatCurrency, Network, Priority

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payout_api_key="<payout_api_key>"
    )
    payout_service = await client.payout_service()

    # Calculate payout in crypto
    calc = await payout_service.calc(
        amount="100",
        currency=CryptoCurrency.USDT,
        network=Network.TRON,
        address="TN3W4H6R8ciD4yYRbz9bq3dWQuT4k5Rq9t",
        is_subtract=True,
        priority=Priority.RECOMMENDED
    )
    print(f"Commission: {calc.commission}")
    print(f"Amount from balance: {calc.merchant_amount}")
    print(f"Amount to recipient: {calc.payout_amount}")

    # Calculate with fiat conversion
    calc_fiat = await payout_service.calc(
        amount="1000",
        currency=FiatCurrency.USD,
        to_currency=CryptoCurrency.BTC,
        network=Network.BTC,
        address="bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
        is_subtract=False,
        priority=Priority.ECONOMY
    )

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### PayoutService Create Invoice

Source: https://context7.com/superfeda/aioheleket/llms.txt

Create a payout to withdraw funds to an external wallet address.

```APIDOC
## PayoutService.create_invoice

### Description
Create a payout to withdraw funds to an external wallet address. Supports cryptocurrency and fiat payouts with optional auto-conversion.

### Method
POST

### Endpoint
`/payout/invoice/create`

### Parameters
#### Request Body
- **amount** (string) - Required - The amount to be paid out.
- **currency** (CryptoCurrency or FiatCurrency) - Required - The currency of the payout amount.
- **network** (Network) - Required - The network for the payout.
- **order_id** (string) - Required - A unique identifier for the payout order.
- **address** (string) - Required - The external wallet address for the payout.
- **is_subtract** (boolean) - Required - If true, the fee is subtracted from the merchant balance. If false, it's subtracted from the payout amount.
- **to_currency** (CryptoCurrency or FiatCurrency) - Optional - The target currency for conversion if needed.
- **from_currency** (string) - Optional - The source currency balance to use for auto-conversion (e.g., "USDT").
- **url_callback** (string) - Optional - A URL to receive webhook notifications about the payout status.
- **priority** (Priority) - Optional - The priority of the payout (e.g., HIGH, RECOMMENDED, ECONOMY).

### Request Example
```json
{
  "amount": "100",
  "currency": "USDT",
  "network": "TRON",
  "order_id": "payout_001",
  "address": "TN3W4H6R8ciD4yYRbz9bq3dWQuT4k5Rq9t",
  "is_subtract": true
}
```

```json
{
  "amount": "500",
  "currency": "USD",
  "to_currency": "LTC",
  "network": "LTC",
  "order_id": "payout_fiat_001",
  "address": "ltc1qw508d6qejxtdg4y5r3zarvary0c5xw7kgmn4n9",
  "is_subtract": false,
  "url_callback": "https://mysite.com/webhook/payout",
  "priority": "HIGH"
}
```

```json
{
  "amount": "200",
  "currency": "EUR",
  "to_currency": "BTC",
  "network": "BTC",
  "order_id": "payout_convert_001",
  "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
  "is_subtract": true,
  "from_currency": "USDT"
}
```

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier for the created payout.
- **status** (string) - The current status of the payout.
- **merchant_amount** (string) - The amount remaining for the merchant after fees (if applicable).
- **commissions** (object) - Details about the commissions applied.

#### Response Example
```json
{
  "uuid": "some-payout-uuid",
  "status": "PENDING",
  "merchant_amount": "99.50",
  "commissions": {
    "fee": "0.50",
    "currency": "USDT"
  }
}
```
```

--------------------------------

### Retrieve Payout Information

Source: https://context7.com/superfeda/aioheleket/llms.txt

Fetches details for a specific payout using either a UUID or an order ID. Check the 'convert' attribute to see if currency conversion details are available.

```python
import asyncio
from aioheleket import HeleketClient

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payout_api_key="<payout_api_key>"
    )
    payout_service = await client.payout_service()

    # Get payout by UUID
    payout = await payout_service.payout_info(uuid="550e8400-e29b-41d4-a716-446655440000")
    print(f"Status: {payout.status}")
    print(f"Is final: {payout.is_final}")
    print(f"Transaction ID: {payout.txid}")
    print(f"Address: {payout.address}")
    print(f"Remaining balance: {payout.balance}")

    # Check for conversion info
    if payout.convert:
        print(f"Converted from {payout.convert.from_currency} to {payout.convert.to_currency}")
        print(f"Rate: {payout.convert.rate}")

    # Get by order ID
    payout_by_order = await payout_service.payout_info(order_id="payout_001")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### PaymentService.create_invoice

Source: https://context7.com/superfeda/aioheleket/llms.txt

Create a new payment invoice for cryptocurrency payments. Supports multiple currencies, networks, and advanced options like discounts and currency conversion.

```APIDOC
## POST /payment/create_invoice

### Description
Creates a new payment invoice for cryptocurrency payments. This endpoint supports various customization options including multiple currencies, networks, discounts, and currency conversion.

### Method
POST

### Endpoint
/payment/create_invoice

### Parameters
#### Query Parameters
- **amount** (string) - Required - The amount of the payment.
- **currency** (CryptoCurrency enum) - Required - The primary currency for the payment (e.g., USDT, BTC).
- **network** (Network enum) - Optional - The network for the cryptocurrency payment (e.g., TRON, ETH). Required if `currencies` is not provided and the currency is multi-network.
- **order_id** (string) - Required - Unique identifier for the order.
- **lifetime** (Lifetime enum) - Optional - The duration for which the invoice is valid (e.g., HOUR_1, HOUR_5).
- **url_callback** (string) - Optional - A URL to receive payment confirmation callbacks.
- **url_success** (string) - Optional - A URL to redirect the user upon successful payment.
- **url_return** (string) - Optional - A URL to redirect the user if they cancel the payment.
- **is_payment_multiple** (boolean) - Optional - Allows partial payments if set to true.
- **subtract** (number) - Optional - The percentage of commission to be paid by the client (e.g., 50 for 50%).
- **accuracy_payment_percent** (number) - Optional - The acceptable percentage of the amount to be considered as paid (e.g., 2 means 98% is acceptable).
- **discount_percent** (number) - Optional - A percentage discount applied to the payment amount.
- **additional_data** (string) - Optional - Any additional data to be associated with the payment.
- **payer_email** (string) - Optional - The email address of the payer.
- **currencies** (array of objects) - Optional - A list of specific currency and network combinations allowed for payment. Each object should have `currency` (string) and `network` (string) keys. Example: `[{"currency": "USDT", "network": "TRON"}, {"currency": "BTC"}]`

### Request Example
```json
{
  "amount": "10.50",
  "currency": "USDT",
  "network": "TRON",
  "order_id": "order_12345",
  "lifetime": "HOUR_1"
}
```

### Response
#### Success Response (200)
- **url** (string) - The URL for the payment invoice.
- **uuid** (string) - The unique identifier for the payment.
- **address** (string) - The cryptocurrency address for the payment.
- **expired_at** (string) - The timestamp when the invoice expires.
- **payer_amount** (string) - The amount the payer needs to pay, considering discounts and conversions.
- **discount** (string) - The amount of discount applied.

#### Response Example
```json
{
  "url": "https://pay.heleket.com/invoice/uuid",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "address": "0x123...",
  "expired_at": "2024-08-15T10:00:00Z",
  "payer_amount": "9.97",
  "discount": "0.53"
}
```
```

--------------------------------

### PayoutService Calculate Payout

Source: https://context7.com/superfeda/aioheleket/llms.txt

Calculate payout amounts and fees before creating a payout.

```APIDOC
## PayoutService.calc

### Description
Calculate payout amounts and associated fees before initiating a payout. This helps in understanding the cost and net amounts involved.

### Method
POST

### Endpoint
`/payout/calc`

### Parameters
#### Request Body
- **amount** (string) - Required - The base amount for the payout calculation.
- **currency** (CryptoCurrency or FiatCurrency) - Required - The currency of the payout amount.
- **network** (Network) - Required - The network for the payout.
- **address** (string) - Required - The destination wallet address.
- **is_subtract** (boolean) - Required - If true, the fee is subtracted from the merchant balance. If false, it's subtracted from the payout amount.
- **to_currency** (CryptoCurrency or FiatCurrency) - Optional - The target currency for conversion if needed.
- **priority** (Priority) - Optional - The priority level for the calculation (e.g., RECOMMENDED, ECONOMY).

### Request Example
```json
{
  "amount": "100",
  "currency": "USDT",
  "network": "TRON",
  "address": "TN3W4H6R8ciD4yYRbz9bq3dWQuT4k5Rq9t",
  "is_subtract": true,
  "priority": "RECOMMENDED"
}
```

```json
{
  "amount": "1000",
  "currency": "USD",
  "to_currency": "BTC",
  "network": "BTC",
  "address": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
  "is_subtract": false,
  "priority": "ECONOMY"
}
```

### Response
#### Success Response (200)
- **commission** (string) - The calculated fee for the payout.
- **merchant_amount** (string) - The amount that will be debited from the merchant's balance.
- **payout_amount** (string) - The net amount that will be sent to the recipient.

#### Response Example
```json
{
  "commission": "0.50",
  "merchant_amount": "100.00",
  "payout_amount": "99.50"
}
```
```

--------------------------------

### FinanceService.exchange_rate

Source: https://context7.com/superfeda/aioheleket/llms.txt

Retrieves current exchange rates for cryptocurrencies against specified fiat or other crypto currencies.

```APIDOC
## GET /finance/exchange_rate

### Description
Get current exchange rates for cryptocurrencies. This endpoint allows fetching rates for all available currencies or a specific subset.

### Method
GET

### Endpoint
/finance/exchange_rate

### Parameters
#### Query Parameters
- **crypto_currency** (CryptoCurrency) - Required - The base cryptocurrency for which to fetch exchange rates (e.g., BTC, ETH, USDT).
- **target_currencies** (tuple[Currency]) - Optional - A tuple of currencies (FiatCurrency or CryptoCurrency) for which to fetch exchange rates. If not provided, rates against all supported fiat currencies will be returned.

### Request Example
```python
# Example usage within the aioheleket library:
# Assuming 'finance_service' is an instance of FinanceService

# Get all BTC exchange rates
btc_rates = await finance_service.exchange_rate(CryptoCurrency.BTC)

# Get specific rates only for ETH
target_currencies = (FiatCurrency.USD, FiatCurrency.EUR, CryptoCurrency.USDT)
eth_rates = await finance_service.exchange_rate(CryptoCurrency.ETH, target_currencies)

# Get USDT rates for specific fiat currencies
usdt_fiat = await finance_service.exchange_rate(
    CryptoCurrency.USDT,
    (FiatCurrency.RUB, FiatCurrency.KZT, FiatCurrency.TRY)
)
```

### Response
#### Success Response (200)
- **rates** (list[ExchangeRate]) - A list of ExchangeRate objects, each containing the target currency and its exchange course.

#### Response Example
```json
[
  {
    "to": "USD",
    "course": 65000.50
  },
  {
    "to": "EUR",
    "course": 60000.75
  }
]
```
```

--------------------------------

### PaymentService.services_info

Source: https://context7.com/superfeda/aioheleket/llms.txt

Retrieves information about available payment services, including supported currencies, networks, availability status, transaction limits, and commission details.

```APIDOC
## GET /payment/services

### Description
Get information about available payment services, including their limits and commissions.

### Method
GET

### Endpoint
/payment/services

### Parameters
None

### Response
#### Success Response (200)
- **services** (array) - A list of available payment services.
  - **currency** (string) - The cryptocurrency supported.
  - **network** (string) - The network on which the currency is supported.
  - **is_available** (boolean) - Indicates if the service is currently available.
  - **limit** (object) - Transaction limits for the service.
    - **min_amount** (string) - The minimum transaction amount.
    - **max_amount** (string) - The maximum transaction amount.
  - **commission** (object) - Commission details for the service.
    - **percent** (string) - The percentage-based commission.
    - **fee_amount** (string) - The fixed fee amount.

#### Response Example
```json
[
  {
    "currency": "USDT",
    "network": "TRON",
    "is_available": true,
    "limit": {
      "min_amount": "1.00",
      "max_amount": "10000.00"
    },
    "commission": {
      "percent": "0.5",
      "fee_amount": "0.1"
    }
  }
]
```
```

--------------------------------

### Test and Resend Webhooks with PaymentService

Source: https://context7.com/superfeda/aioheleket/llms.txt

Use PaymentService to test webhook endpoints by sending a test notification. Resend webhooks for existing payments using either the order ID or UUID. Ensure the HeleketClient is initialized with merchant credentials.

```python
import asyncio
from aioheleket import HeleketClient, CryptoCurrency, Network, PaymentStatus

async def main() -> None:
    client = HeleketClient(
        merchant_id="<merchant_id>",
        payment_api_key="<payment_api_key>"
    )
    payment_service = await client.payment_service()

    # Test webhook endpoint
    result = await payment_service.test_webhook(
        url_callback="https://mysite.com/webhook/payment",
        currency=CryptoCurrency.USDT,
        network=Network.TRON,
        status=PaymentStatus.PAID,
        order_id="test_order_001"
    )
    print("Test webhook sent successfully")

    # Resend webhook for existing payment
    result = await payment_service.resend_webhook(order_id="order_12345")
    # Or by UUID
    result = await payment_service.resend_webhook(uuid="550e8400-e29b-41d4-a716-446655440000")

    await client.close_session()

if __name__ == "__main__":
    asyncio.run(main())
```
Tokens:
Raw