API reference

`debridge`

Typed Python client for the deBridge DLN cross-chain swap/order API.

`DebridgeAPIError`

Bases: DebridgeError

Raised when the deBridge API returns an error response.

The DLN API signals errors with a JSON body of the shape {"errorCode", "errorId", "errorMessage", "reqId"}. Crucially, errors are surfaced in two ways:

a non-2xx HTTP status (e.g. 400 INVALID_QUERY_PARAMETERS / UNKNOWN_ORDER), and
an HTTP 200 response whose body nonetheless carries an errorId (e.g. COMPLIANCE_ADDRESS_BLOCKED).

The client detects both, so callers should rely on catching this exception rather than inspecting the HTTP status code themselves.

Attributes:

Name	Type	Description
`error_id`		The API's `errorId` string (e.g. `"UNKNOWN_ORDER"`), or `None` if the response carried no error id.
`error_code`		The numeric `errorCode`, or `None`.
`message`		The `errorMessage` text, falling back to `"HTTP <status>"`.
`req_id`		The API's `reqId` (useful for support tickets), or `None`.
`status_code`		The HTTP status code of the response (may be `200`).

Example::

from debridge import DebridgeClient, DebridgeAPIError

with DebridgeClient() as client:
    try:
        client.get_order_status("0xnot-an-order")
    except DebridgeAPIError as exc:
        print(exc.error_id, exc.status_code)  # 'UNKNOWN_ORDER' 400

`DebridgeError`

Bases: Exception

Base class for all errors raised by this library.

Catch this to handle any failure originating from debridge (currently just :class:DebridgeAPIError). Network-level failures from the underlying httpx client propagate as httpx exceptions and are not wrapped.

`AsyncDebridgeClient`

Bases: _BaseClient

Asynchronous counterpart of :class:DebridgeClient.

Exposes the same endpoints as coroutines, backed by httpx.AsyncClient. Use it as an async context manager so the connection pool is closed for you; otherwise call :meth:aclose.

Example::

import asyncio
from debridge import AsyncDebridgeClient

async def main():
    async with AsyncDebridgeClient() as client:
        chains = await client.get_supported_chains()
        print(len(chains.chains))

asyncio.run(main())

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

Create an asynchronous client.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	DLN API base URL. Defaults to the public endpoint (:data:`debridge.constants.DEFAULT_BASE_URL`); a trailing slash is tolerated.	`DEFAULT_BASE_URL`
`timeout`	`float`	Per-request timeout in seconds, applied when this client creates its own `httpx.AsyncClient`. Ignored if `client` is given.	`30.0`
`client`	`Optional[AsyncClient]`	An existing `httpx.AsyncClient` to reuse. When supplied, the caller owns its lifecycle and :meth:`aclose` will not close it.	`None`

`aclose()` `async`

Close the underlying async HTTP client.

No-op when an external httpx.AsyncClient was injected via the constructor (the caller owns that client's lifecycle).

`aenter()` `async`

Enter the async runtime context and return this client.

`aexit(exc_type, exc, tb)` `async`

Exit the async runtime context, closing the client via :meth:aclose.

`get_supported_chains()` `async`

Fetch the chains the DLN currently supports.

Calls GET /supported-chains-info.

Returns:

Name	Type	Description
`A`	`SupportedChainsResponse`	class:`SupportedChainsResponse` listing every supported chain.

Raises:

Type	Description
`DebridgeAPIError`	If the API returns an error.

`get_token_list(chain_id)` `async`

Fetch the tradable token list for a chain.

Calls GET /token-list.

Parameters:

Name	Type	Description	Default
`chain_id`	`int`	deBridge chain id (an `int` or a :class:`debridge.constants.ChainId` member).	required

Returns:

Name	Type	Description
`A`	`TokenListResponse`	class:`TokenListResponse` mapping token address to metadata.

Raises:

Type	Description
`DebridgeAPIError`	If the API returns an error.

`create_order(*, src_chain_id, src_chain_token_in, src_chain_token_in_amount, dst_chain_id, dst_chain_token_out, dst_chain_token_out_recipient, sender_address, dst_chain_token_out_amount='auto', src_chain_order_authority_address=None, dst_chain_order_authority_address=None, referral_code=None, affiliate_fee_percent=None, affiliate_fee_recipient=None, prepend_operating_expenses=None, extra=None)` `async`

Quote and build a cross-chain order plus its source-chain transaction.

Async equivalent of :meth:DebridgeClient.create_order; see that method for full argument and return documentation and EVM/Solana examples.

Parameters:

Name	Type	Description	Default
`src_chain_id`	`int`	Source chain id (int or `ChainId`).	required
`src_chain_token_in`	`str`	Input token address on the source chain.	required
`src_chain_token_in_amount`	`str`	Input amount in the token's smallest unit.	required
`dst_chain_id`	`int`	Destination chain id (int or `ChainId`).	required
`dst_chain_token_out`	`str`	Output token address on the destination chain.	required
`dst_chain_token_out_recipient`	`str`	Address that receives the output.	required
`sender_address`	`str`	Address sending the source transaction.	required
`dst_chain_token_out_amount`	`str`	Desired output amount, or `"auto"`.	`'auto'`
`src_chain_order_authority_address`	`Optional[str]`	Source-chain order authority; defaults to `sender_address`.	`None`
`dst_chain_order_authority_address`	`Optional[str]`	Destination-chain order authority; defaults to `dst_chain_token_out_recipient`.	`None`
`referral_code`	`Optional[int]`	Optional integer referral code.	`None`
`affiliate_fee_percent`	`Optional[float]`	Optional affiliate fee percentage.	`None`
`affiliate_fee_recipient`	`Optional[str]`	Address that receives the affiliate fee.	`None`
`prepend_operating_expenses`	`Optional[bool]`	Add operating expenses on top of the input instead of deducting from the output.	`None`
`extra`	`Optional[Dict[str, Any]]`	Additional raw query params, merged last.	`None`

Returns:

Name	Type	Description
`A`	`CreateOrderResponse`	class:`CreateOrderResponse` with the quote, unsigned `tx`, and
	`CreateOrderResponse`	the resulting `order_id`.

Raises:

Type	Description
`DebridgeAPIError`	If the API rejects the request (including HTTP-200 compliance blocks).

`get_order_status(order_id)` `async`

Fetch the lightweight status of an order.

Calls GET /dln/order/{id}/status.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The order id (0x-hex).	required

Returns:

Name	Type	Description
`An`	`OrderStatus`	class:`OrderStatus` with the current `status` string.

Raises:

Type	Description
`DebridgeAPIError`	If the order is unknown or the id is malformed.

`get_order(order_id)` `async`

Fetch full order details, including the decoded order struct.

Calls GET /dln/order/{id}.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The order id (0x-hex).	required

Returns:

Name	Type	Description
`An`	`OrderDetails`	class:`OrderDetails` with status, external-call state, and the
	`OrderDetails`	on-chain :class:`debridge.models.OrderStruct`.

Raises:

Type	Description
`DebridgeAPIError`	If the order is unknown or the id is malformed.

`poll_status(order_id, *, interval=5.0, timeout=600.0)` `async`

Poll an order's status until it reaches a terminal state.

Async equivalent of :meth:DebridgeClient.poll_status; awaits :meth:get_order_status and sleeps via asyncio.sleep between checks.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The order id to poll.	required
`interval`	`float`	Seconds to wait between polls. `0` polls without sleeping (useful in tests).	`5.0`
`timeout`	`float`	Maximum total seconds to wait before giving up.	`600.0`

Returns:

Type	Description
`OrderStatus`	The terminal :class:`OrderStatus`.

Raises:

Type	Description
`TimeoutError`	If no terminal state is reached within `timeout`.
`DebridgeAPIError`	If a status request fails.

Example::

final = await client.poll_status(order.order_id, interval=5, timeout=600)
print(final.status)  # e.g. "Fulfilled"

`DebridgeClient`

Bases: _BaseClient

Synchronous client for the deBridge DLN API.

Wraps the public DLN endpoints (quotes, order creation, status) with typed requests and responses. Every method raises :class:DebridgeAPIError on an API error (including HTTP-200 error bodies such as compliance blocks).

Use it as a context manager so the underlying httpx connection pool is closed for you; otherwise call :meth:close when done.

Example::

from debridge import DebridgeClient
from debridge.constants import ChainId

with DebridgeClient() as client:
    chains = client.get_supported_chains()
    order = client.create_order(
        src_chain_id=ChainId.BASE,
        src_chain_token_in="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        src_chain_token_in_amount="10000000",
        dst_chain_id=ChainId.ARBITRUM,
        dst_chain_token_out="0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        dst_chain_token_out_recipient="0xYourRecipient",
        sender_address="0xYourSender",
    )
    final = client.poll_status(order.order_id)

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

Create a synchronous client.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	DLN API base URL. Defaults to the public endpoint (:data:`debridge.constants.DEFAULT_BASE_URL`); a trailing slash is tolerated. Point this at a compatible proxy if needed.	`DEFAULT_BASE_URL`
`timeout`	`float`	Per-request timeout in seconds, applied when this client creates its own `httpx.Client`. Ignored if `client` is given.	`30.0`
`client`	`Optional[Client]`	An existing `httpx.Client` to reuse. When supplied, the caller owns its lifecycle and :meth:`close` will not close it.	`None`

`close()`

Close the underlying HTTP client.

No-op when an external httpx.Client was injected via the constructor (the caller owns that client's lifecycle).

`enter()`

Enter the runtime context and return this client.

`exit(exc_type, exc, tb)`

Exit the runtime context, closing the client via :meth:close.

`get_supported_chains()`

Fetch the chains the DLN currently supports.

Calls GET /supported-chains-info.

Returns:

Name	Type	Description
`A`	`SupportedChainsResponse`	class:`SupportedChainsResponse` listing every supported chain.

Raises:

Type	Description
`DebridgeAPIError`	If the API returns an error.

`get_token_list(chain_id)`

Fetch the tradable token list for a chain.

Calls GET /token-list.

Parameters:

Name	Type	Description	Default
`chain_id`	`int`	deBridge chain id (an `int` or a :class:`debridge.constants.ChainId` member).	required

Returns:

Name	Type	Description
`A`	`TokenListResponse`	class:`TokenListResponse` mapping token address to metadata.

Raises:

Type	Description
`DebridgeAPIError`	If the API returns an error.

`create_order(*, src_chain_id, src_chain_token_in, src_chain_token_in_amount, dst_chain_id, dst_chain_token_out, dst_chain_token_out_recipient, sender_address, dst_chain_token_out_amount='auto', src_chain_order_authority_address=None, dst_chain_order_authority_address=None, referral_code=None, affiliate_fee_percent=None, affiliate_fee_recipient=None, prepend_operating_expenses=None, extra=None)`

Quote and build a cross-chain order plus its source-chain transaction.

Calls GET /dln/order/create-tx. Works for both EVM and Solana source chains; the returned tx carries to/value for EVM sources and only data for Solana (see :class:debridge.models.Transaction).

Parameters:

Name	Type	Description	Default
`src_chain_id`	`int`	Source chain id (int or `ChainId`).	required
`src_chain_token_in`	`str`	Input token address on the source chain (0x-hex for EVM, base58 mint for Solana; native sentinels in :mod:`debridge.constants`).	required
`src_chain_token_in_amount`	`str`	Input amount in the token's smallest unit.	required
`dst_chain_id`	`int`	Destination chain id (int or `ChainId`).	required
`dst_chain_token_out`	`str`	Output token address on the destination chain.	required
`dst_chain_token_out_recipient`	`str`	Address that receives the output.	required
`sender_address`	`str`	Address sending the source transaction.	required
`dst_chain_token_out_amount`	`str`	Desired output amount, or `"auto"` (default) to let the API quote the best available output.	`'auto'`
`src_chain_order_authority_address`	`Optional[str]`	Authority that can patch/cancel on the source chain. Defaults to `sender_address`.	`None`
`dst_chain_order_authority_address`	`Optional[str]`	Authority on the destination chain. Defaults to `dst_chain_token_out_recipient`.	`None`
`referral_code`	`Optional[int]`	Optional integer referral code.	`None`
`affiliate_fee_percent`	`Optional[float]`	Optional affiliate fee percentage to charge.	`None`
`affiliate_fee_recipient`	`Optional[str]`	Address that receives the affiliate fee.	`None`
`prepend_operating_expenses`	`Optional[bool]`	Whether to add operating expenses on top of the input amount instead of deducting them from the output.	`None`
`extra`	`Optional[Dict[str, Any]]`	Additional raw query params, merged last (escape hatch for params not yet modelled here).	`None`

Returns:

Name	Type	Description
`A`	`CreateOrderResponse`	class:`CreateOrderResponse` with the quote, the unsigned `tx`,
	`CreateOrderResponse`	and the resulting `order_id`.

Raises:

Type	Description
`DebridgeAPIError`	If the API rejects the request (e.g. unsupported chain, blocked address) — including HTTP-200 compliance blocks.

Example

EVM -> EVM (10 USDC on Base to USDC on Arbitrum)::

order = client.create_order(
    src_chain_id=ChainId.BASE,
    src_chain_token_in="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    src_chain_token_in_amount="10000000",
    dst_chain_id=ChainId.ARBITRUM,
    dst_chain_token_out="0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    dst_chain_token_out_recipient="0xRecipient",
    sender_address="0xSender",
)
print(order.tx.to, order.tx.value)  # EVM call to sign & send

EVM -> Solana (Base USDC to USDC on Solana)::

order = client.create_order(
    src_chain_id=ChainId.BASE,
    src_chain_token_in="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    src_chain_token_in_amount="10000000",
    dst_chain_id=ChainId.SOLANA,
    dst_chain_token_out="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    dst_chain_token_out_recipient="GZ1WYUw1...",  # base58 address
    sender_address="0xSender",
)
# Output recipient is on Solana; tx is still an EVM call (source
# is Base). For a Solana *source*, order.tx.to/value are None and
# order.tx.data is the serialized versioned tx as hex.

`get_order_status(order_id)`

Fetch the lightweight status of an order.

Calls GET /dln/order/{id}/status.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The order id (0x-hex), e.g. from :attr:`CreateOrderResponse.order_id`.	required

Returns:

Name	Type	Description
`An`	`OrderStatus`	class:`OrderStatus` with the current `status` string.

Raises:

Type	Description
`DebridgeAPIError`	If the order is unknown or the id is malformed.

`get_order(order_id)`

Fetch full order details, including the decoded order struct.

Calls GET /dln/order/{id}.

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The order id (0x-hex).	required

Returns:

Name	Type	Description
`An`	`OrderDetails`	class:`OrderDetails` with status, external-call state, and the
	`OrderDetails`	on-chain :class:`debridge.models.OrderStruct`.

Raises:

Type	Description
`DebridgeAPIError`	If the order is unknown or the id is malformed.

`poll_status(order_id, *, interval=5.0, timeout=600.0)`

Poll an order's status until it reaches a terminal state.

Repeatedly calls :meth:get_order_status, sleeping interval seconds between checks, until the status is in :data:debridge.constants.TERMINAL_STATUSES (e.g. "Fulfilled").

Parameters:

Name	Type	Description	Default
`order_id`	`str`	The order id to poll.	required
`interval`	`float`	Seconds to wait between polls. `0` polls without sleeping (useful in tests).	`5.0`
`timeout`	`float`	Maximum total seconds to wait before giving up.	`600.0`

Returns:

Type	Description
`OrderStatus`	The terminal :class:`OrderStatus`.

Raises:

Type	Description
`TimeoutError`	If no terminal state is reached within `timeout`.
`DebridgeAPIError`	If a status request fails.

Example::

# After broadcasting order.tx on the source chain:
final = client.poll_status(order.order_id, interval=5, timeout=600)
print(final.status)  # e.g. "Fulfilled"

`CreateOrderResponse`

Bases: _Model

Full response of GET /dln/order/create-tx.

Bundles the quote (:attr:estimation), the unsigned source-chain :attr:tx to broadcast, the resulting :attr:order_id, and fee details. The same shape is returned for EVM and Solana sources; only :attr:tx varies (see :class:Transaction).

Example::

order = client.create_order(...)
print(order.order_id)
print(order.estimation.dst_chain_token_out.amount)  # expected output
print(order.tx.to, order.tx.value, order.tx.data)   # tx to sign & send

`Estimation`

Bases: _Model

The quote portion of a create-order response: legs, costs, and slippage.

`OrderDetails`

Bases: _Model

Full order detail from GET /dln/order/{id} — status plus the order struct.

`OrderStatus`

Bases: _Model

Lightweight order status from GET /dln/order/{id}/status.

status is a string such as "Created", "Fulfilled", "SentUnlock", "ClaimedUnlock", "OrderCancelled" — see :data:debridge.constants.TERMINAL_STATUSES for the states treated as final.

`SupportedChain`

Bases: _Model

A single chain entry from GET /supported-chains-info.

Note that deBridge's internal chain_id differs from the chain's native id for non-EVM/L2 chains (e.g. Solana is 7565164). Use chain_id when talking to this API and original_chain_id to map back to the chain's canonical id.

`SupportedChainsResponse`

Bases: _Model

Response of GET /supported-chains-info — the list of supported chains.

`TokenInfo`

Bases: _Model

Metadata for one token, as returned by GET /token-list.

`TokenListResponse`

Bases: _Model

Response of GET /token-list — tokens keyed by their address.

`Transaction`

Bases: _Model

The transaction to broadcast on the source chain.

For EVM sources, to and value are present (an EVM call). For Solana sources the API returns only data (the serialized versioned transaction encoded as a hex string), and to/value are None. Inspect which fields are set to decide how to sign and broadcast.

API reference

debridge

DebridgeAPIError

DebridgeError

AsyncDebridgeClient

__init__(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)

aclose() async

__aenter__() async

__aexit__(exc_type, exc, tb) async

get_supported_chains() async

get_token_list(chain_id) async

get_order_status(order_id) async

get_order(order_id) async

poll_status(order_id, *, interval=5.0, timeout=600.0) async

DebridgeClient

__init__(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)

close()

__enter__()

__exit__(exc_type, exc, tb)

get_supported_chains()

get_token_list(chain_id)

get_order_status(order_id)

get_order(order_id)

poll_status(order_id, *, interval=5.0, timeout=600.0)

CreateOrderResponse

Estimation

OrderDetails

OrderStatus

SupportedChain

SupportedChainsResponse

TokenInfo

TokenListResponse

Transaction

`debridge`

`DebridgeAPIError`

`DebridgeError`

`AsyncDebridgeClient`

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

`aclose()` `async`

`aenter()` `async`

`aexit(exc_type, exc, tb)` `async`

`get_supported_chains()` `async`

`get_token_list(chain_id)` `async`

`get_order_status(order_id)` `async`

`get_order(order_id)` `async`

`poll_status(order_id, *, interval=5.0, timeout=600.0)` `async`

`DebridgeClient`

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

`close()`

`enter()`

`exit(exc_type, exc, tb)`

`get_supported_chains()`

`get_token_list(chain_id)`

`get_order_status(order_id)`

`get_order(order_id)`

`poll_status(order_id, *, interval=5.0, timeout=600.0)`

`CreateOrderResponse`

`Estimation`

`OrderDetails`

`OrderStatus`

`SupportedChain`

`SupportedChainsResponse`

`TokenInfo`

`TokenListResponse`

`Transaction`