Metadata-Version: 2.4
Name: rango-basic-sdk
Version: 0.0.7
Summary: Python bindings for Rango Exchange Basic API
Project-URL: Home, https://github.com/rango-exchange/rango-python-basic
Project-URL: Contact, https://t.me/rangoexchange
Project-URL: Documentation, https://docs.rango.exchange/
Author-email: Rango <hi@rango.exchange>
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Python SDK for Rango Exchange Basic API

Simple and Easy to use APIs for Rango Aggregation protocols for dApps and Wallets for single step cross-chain and on-chain swaps using the best route and all the available on-chain liquidity across all blockchain networks.

## Requirements

This package supports **Python 3.8** and newer.

## Installation

Install it with:

```bash
python -m pip install rango-basic-sdk
```

Alternatively, install from the source code with this command from the project root:

```bash
python -m pip install .
```

For an editable installation while developing:

```bash
python -m pip install -e .
```

## Usage

### Synchronous client

`Client` is the synchronous API. Close it when finished, or use a `with` block.

```python
from rango_basic_sdk import Client

with Client(api_key='c6381a79-2817-4602-83bf-6a641a409e32') as client:
    result = client.routing.quote(from_="BSC.BNB", to="AVAX_CCHAIN.USDT.E--0xc7198437980c041c805a1edcba50c1ce5db95118", amount=10000000000000000, slippage=3.5)
```

Endpoints are nested under attributes (see `client.py`):

- `client.balance` → `BalanceOperations`
- `client.metadata` → `MetadataOperations`
- `client.routing` → `RoutingOperations`
- `client.transaction` → `TransactionOperations`

### Asynchronous client

`AsyncClient` is the asynchronous API. Use `async with` and `await` each call.

```python
import asyncio
from rango_basic_sdk import AsyncClient

async def main() -> None:
    async with AsyncClient(api_key='c6381a79-2817-4602-83bf-6a641a409e32') as client:
        result = await client.routing.quote(from_="BSC.BNB", to="AVAX_CCHAIN.USDT.E--0xc7198437980c041c805a1edcba50c1ce5db95118", amount=10000000000000000, slippage=3.5)

asyncio.run(main())
```

## Authentication

The **Usage** section above and the **`examples/`** / **`docs/`** trees show authentication via **constructor keyword arguments**; This package also supports **environment-variable** credentials (using **`RANGO_BASIC`** prefix for env vars).

#### `apiKey` — API key (query parameter)

- This sdk uses **apiKey** auth: the credential is sent as the query parameter `apiKey`.
- Use constructor option `api_key`.
- Pass these as keyword arguments to `Client(...)` / `AsyncClient(...)`.
- Alternatively set environment variable `RANGO_BASIC_API_KEY`. Explicit constructor options override env when both are set.


For private or production authentication parameters, contact **Rango** via [hi@rango.exchange](mailto:hi@rango.exchange) or [https://t.me/rangoexchange](https://t.me/rangoexchange). See the [official API documentation](https://docs.rango.exchange/).

## API Endpoints Reference

For a complete list of all available SDK methods, including detailed parameter descriptions, return values, and code examples, see the **API Reference**:

[📖 View Full API Reference](docs/API_REFERENCE.md)


## Example Codes

The examples below show only the most commonly used endpoints to help you get started quickly.

For advanced usage and less common operations, consult the API Reference.


### Get Balance of a Token

Fetches the balance of a specific token address for the user's wallet


**Runnable source:** [`get_token_balance.py`](examples/quickstart/balance/get_token_balance.py)

```python
from rango_basic_sdk import Client, models

with Client(api_key='c6381a79-2817-4602-83bf-6a641a409e32') as client:
    result = client.balance.get_token_balance(wallet_address="0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88", blockchain=models.Blockchain.BSC, symbol="USDT", address="0x55d398326f99059ff775485246999027b3197955")
    print(result)
```

### Get the Best Quote for swapping

Get the best route to perform a cross-chain or same-chain swap


**Runnable source:** [`quote.py`](examples/quickstart/routing/quote.py)

```python
from rango_basic_sdk import Client

with Client(api_key='c6381a79-2817-4602-83bf-6a641a409e32') as client:
    result = client.routing.quote(from_="BSC.BNB", to="AVAX_CCHAIN.USDT.E--0xc7198437980c041c805a1edcba50c1ce5db95118", amount=10000000000000000, slippage=3.5)
    print(result)
```

### Create the Transaction (Swap)

Creates a transaction to be signed by user's wallet and broadcasted to the network


**Runnable source:** [`swap.py`](examples/quickstart/transaction/swap.py)

```python
from rango_basic_sdk import Client

with Client(api_key='c6381a79-2817-4602-83bf-6a641a409e32') as client:
    result = client.transaction.swap(from_="BSC.BNB", to="AVAX_CCHAIN.USDT.E--0xc7198437980c041c805a1edcba50c1ce5db95118", amount=10000000000000000, slippage=3.5, from_address="0x9F8cCdaFCc39F3c7D6EBf637c9151673CBc36b88", to_address="0x6f33bb1763eebead07cf8815a62fcd7b30311fa3", disable_estimate=False, infinite_approve=False)
    print(result)
```

### Check the Transaction Status

Checks the status of the transaction using the requestId from the swap endpoint and the broadcasted transaction hash (txId)


**Runnable source:** [`status.py`](examples/quickstart/transaction/status.py)

```python
from rango_basic_sdk import Client

with Client(api_key='c6381a79-2817-4602-83bf-6a641a409e32') as client:
    result = client.transaction.status(request_id="b3a12c6d-86b8-4c21-97e4-809151dd4036", tx_id="0xfa88b705a5b4049adac7caff50c887d9600ef023ef1a937f8f8b6f44e90042b5")
    print(result)
```



Additional samples for all endpoints live under the **[`examples/`](examples/)** folder.

## Advanced Examples

For more advanced walkthroughs, step-by-step guides and custom samples, check the **[Advanced Examples](examples/advanced/)** folder.

## HTTP debug logging

To print each HTTP request and response (method, URL, status, headers, and bodies) after the response is received, pass **`log_http_debug=True`** to `Client` or `AsyncClient`, and set the **`rango_basic_sdk.client`** logger to **DEBUG** so those messages are emitted.

Bodies are truncated after 16 KiB per direction. **Do not use this in production or with real secrets:** debug output can include credentials (e.g. `Authorization`, API keys, cookies).

```python
import logging

from rango_basic_sdk import Client

logging.getLogger("rango_basic_sdk.client").setLevel(logging.DEBUG)
if not logging.root.handlers:
    logging.basicConfig(level=logging.DEBUG)

with Client(log_http_debug=True) as client:
    # …
    pass
```

For `AsyncClient`, use the same logging setup and `AsyncClient(log_http_debug=True, ...)`.