rango-py

A typed, batteries-included Python client for the Rango Exchange Basic API — a universal cross-chain DEX & bridge aggregator spanning EVM, Solana, Cosmos, Tron, UTXO, Starknet and more. Sync and async, built on httpx and pydantic v2.

Requirements

• Python 3.9+
• A Rango API key — every Rango API request requires one. It is sent as the apiKey query parameter. Get a free API key from the Rango dashboard (see the API docs). The client will not work without it; requests without a key return 401.

Installation

pip install rango-py

The package installs as rango-py; you import it as rango.

Quickstart

from rango import RangoClient

with RangoClient(api_key="YOUR_API_KEY") as client:
    # Supported blockchains, tokens and swappers
    meta = client.get_meta()
    print(len(meta.blockchains), "blockchains supported")

    # Best route: 1 BNB on BSC -> USDC on Avalanche C-Chain
    quote = client.get_quote(
        from_asset="BSC.BNB",
        to_asset="AVAX_CCHAIN--0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e",
        amount="1000000000000000000",
        slippage=1.0,
    )
    print("result:", quote.result_type, "->", quote.route.output_amount if quote.route else None)

    # Create the signable transaction for the swap
    swap = client.get_swap(
        from_asset="BSC.BNB",
        to_asset="AVAX_CCHAIN--0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e",
        amount="1000000000000000000",
        from_address="0xYourAddress",
        to_address="0xYourAddress",
        slippage=1.0,
    )
    request_id = swap.request_id   # save this to track status
    tx = swap.tx                   # the transaction to sign and broadcast

Tracking transaction status

After you broadcast the swap transaction on-chain, poll for its cross-chain status using the request_id from the swap response and the transaction hash:

status = client.poll_status(
    request_id=request_id,
    tx_id="0xYourSourceTxHash",
)
print(status.status)  # e.g. "success"

poll_status blocks until a terminal state (success or failed) or raises StatusTimeoutError. While the status is running (or null) it keeps polling. For a single check use client.get_status(...).

Async

import asyncio
from rango import AsyncRangoClient

async def main():
    async with AsyncRangoClient(api_key="YOUR_API_KEY") as client:
        meta = await client.get_meta()
        print(len(meta.blockchains), "blockchains supported")

asyncio.run(main())

Asset format

Rango identifies assets as BLOCKCHAIN.SYMBOL for native/symbol tokens (e.g. BSC.BNB, ETH.USDT) or BLOCKCHAIN--ADDRESS for tokens addressed by contract (e.g. AVAX_CCHAIN--0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e).

Caching metadata

The /basic/meta payload is large and changes slowly. Enable an in-process TTL cache so repeated get_meta() calls reuse a recent response:

client = RangoClient(api_key="YOUR_API_KEY", meta_cache_ttl=300)  # cache for 5 minutes

With meta_cache_ttl set, get_meta() returns the cached value until it expires. Pass force_refresh=True to bypass the cache for a single call.

Configuration

RangoClient / AsyncRangoClient accept:

Argument	Default	Description
api_key	— (required)	Your Rango API key, sent as the apiKey param.
base_url	https://api.rango.exchange	API base URL.
timeout	30.0	Request timeout in seconds.
meta_cache_ttl	None	Seconds to cache get_meta(). None disables.
client	None	A pre-configured httpx.Client / AsyncClient.

Error handling

from rango import RangoClient, RangoAPIError

with RangoClient(api_key="YOUR_API_KEY") as client:
    try:
        client.get_meta()
    except RangoAPIError as exc:
        print(exc.status_code, exc.message)

• RangoError — base class for everything raised by this library.
• RangoAPIError — non-2xx API response; carries status_code, message, response_body.
• StatusTimeoutError — poll_status did not reach a terminal state in time; carries last_status.

License

MIT

This is an unofficial, community-maintained client and is not affiliated with Rango Exchange. See the official Rango documentation for the authoritative API reference.