bungee-py

Typed, async-friendly Python client for the current Bungee API — the cross-chain bridge and swap aggregator that succeeds Socket.

It targets the live, keyless public API at https://public-backend.bungee.exchange/api/v1 (not the legacy Socket Liquidity Layer API). No API key is required.

• Synchronous (BungeeClient) and asynchronous (AsyncBungeeClient) clients on httpx.
• Fully typed pydantic v2 models (forward-compatible: unknown fields are preserved).
• Quote a cross-chain swap, get a ready-to-broadcast transaction, and poll the bridge to completion.
• py.typed — ships type information for your own type checker.

Installation

pip install bungee-py

The package installs as bungee-py; you import it as bungee:

import bungee

Optional execution helpers (broadcasting transactions with web3) live behind an extra:

pip install "bungee-py[exec]"

Quickstart

from bungee import BungeeClient
from bungee.constants import ChainId, NATIVE_TOKEN_ADDRESS

with BungeeClient() as client:
    # 1. Quote bridging 0.01 ETH on Ethereum to USDC on Optimism.
    quote = client.get_quote(
        user_address="0xYourWallet",
        origin_chain_id=ChainId.ETHEREUM,
        destination_chain_id=ChainId.OPTIMISM,
        input_token=NATIVE_TOKEN_ADDRESS,                       # native ETH
        output_token="0x0b2c639c533813f4aa9d7837caf62653d097ff85",  # USDC on OP
        input_amount="10000000000000000",                      # 0.01 ETH (wei)
    )

    route = quote.auto_route            # the headline single-signature route
    print(route.output.amount)          # expected USDC out (smallest unit)
    print(route.tx_data.to, route.tx_data.value, route.tx_data.data)

    # 2. Sign & broadcast route.tx_data with your wallet of choice, then:
    final = client.poll_status(route.request_hash)
    print(final.is_success(), final.bungee_status_code)  # e.g. True 4 (SETTLED)

poll_status returns once the transfer is terminal. Terminality is judged from the integer bungeeStatusCode (FULFILLED/SETTLED = success; EXPIRED/CANCELLED/REFUND_PENDING/REFUNDED = unsuccessful), not from the destinationData.status string, which only ever reports PENDING or COMPLETED. Call final.is_success() to check the outcome.

Async

import asyncio
from bungee import AsyncBungeeClient

async def main():
    async with AsyncBungeeClient() as client:
        chains = await client.get_supported_chains()
        print(len(chains), "chains supported")

asyncio.run(main())

API

All methods unwrap Bungee's {success, statusCode, result, message} envelope and raise BungeeAPIError on any API error (including the per-IP rate limit, which the edge returns as HTTP 429).

Method	Endpoint	Returns
get_tokens(chain_id=None)	GET /tokens/list	TokenListResponse
get_supported_chains()	GET /supported-chains	list[SupportedChain]
get_quote(...)	GET /bungee/quote	QuoteResponse
build_tx(quote_id)	GET /bungee/build-tx	BuildTxResponse
get_status(request_hash)	GET /bungee/status	list[BridgeStatus]
poll_status(request_hash, ...)	GET /bungee/status (polled)	BridgeStatus

Auto vs. manual routes

get_quote returns a headline auto_route — a fully built, single-signature route whose tx_data you can broadcast directly. Pass enable_manual=True to also receive manual_routes (alternative bridges/DEXes); each manual route carries a quote_id but no tx_data — call build_tx(quote_id) to obtain its transaction.

quote = client.get_quote(..., enable_manual=True)
for route in quote.manual_routes or []:
    built = client.build_tx(route.quote_id)
    print(route.route_details.name, built.tx_data.to)

Errors

from bungee import BungeeClient, BungeeAPIError

with BungeeClient() as client:
    try:
        client.get_status("0xnot-a-real-hash")
    except BungeeAPIError as exc:
        print(exc.status_code, exc.message)

Development

pip install -e ".[dev]"
ruff check . && ruff format --check .
mypy
pytest -q                 # unit tests (respx-mocked, offline)
pytest -m integration     # live tests against the real Bungee API (keyless)

Disclaimer

This is an unofficial, community-maintained client and is not affiliated with Bungee or Socket. Always verify transactions before signing. Use at your own risk.

License

MIT