API reference
across_protocol
Typed Python client for the Across Protocol bridge API.
AsyncAcrossClient
An asynchronous client for the Across Protocol bridge API.
This mirrors :class:across_protocol.AcrossClient; every request method is
a coroutine. The default base URL targets the public production API, which
requires no API key for the quoting endpoints exposed here.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
Base URL of the Across API. Defaults to the production host. |
DEFAULT_BASE_URL
|
timeout
|
float
|
Per-request timeout in seconds. |
DEFAULT_TIMEOUT
|
client
|
Optional[AsyncClient]
|
An optional pre-configured :class: |
None
|
Example
import asyncio async def quote() -> str: ... async with AsyncAcrossClient() as client: ... fees = await client.get_suggested_fees( ... input_token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", ... output_token="0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", ... origin_chain_id=1, ... destination_chain_id=137, ... amount=10_000_000, ... ) ... return fees.output_amount asyncio.run(quote()) # doctest: +SKIP
aclose()
async
Close the underlying HTTP client, unless it was supplied by the caller.
get_suggested_fees(*, input_token, output_token, origin_chain_id, destination_chain_id, amount, recipient=None)
async
Get a bridge quote (fees, output amount, limits) for a transfer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_token
|
str
|
Input token address on the origin chain. |
required |
output_token
|
str
|
Output token address on the destination chain. |
required |
origin_chain_id
|
int
|
Chain ID the deposit originates from. |
required |
destination_chain_id
|
int
|
Chain ID the funds are bridged to. |
required |
amount
|
Union[int, str]
|
Input amount in the token's smallest unit (int or decimal string). |
required |
recipient
|
Optional[str]
|
Optional recipient address used for a more precise gas estimate. |
None
|
Returns:
| Type | Description |
|---|---|
SuggestedFees
|
The suggested fees and resulting output amount for the transfer. |
Raises:
| Type | Description |
|---|---|
AcrossAPIError
|
If the API returns a non-success response. |
Example
async with AsyncAcrossClient() as client: # doctest: +SKIP ... quote = await client.get_suggested_fees( ... input_token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", ... output_token="0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", ... origin_chain_id=1, ... destination_chain_id=137, ... amount=10_000_000, ... )
get_available_routes(*, origin_chain_id=None, destination_chain_id=None, origin_token=None, destination_token=None)
async
List supported token routes, optionally filtered.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
origin_chain_id
|
Optional[int]
|
Restrict results to this origin chain. |
None
|
destination_chain_id
|
Optional[int]
|
Restrict results to this destination chain. |
None
|
origin_token
|
Optional[str]
|
Restrict results to this origin token address. |
None
|
destination_token
|
Optional[str]
|
Restrict results to this destination token address. |
None
|
Returns:
| Type | Description |
|---|---|
list[AvailableRoute]
|
The supported routes matching the given filters. |
Raises:
| Type | Description |
|---|---|
AcrossAPIError
|
If the API returns a non-success response. |
get_limits(*, input_token, output_token, origin_chain_id, destination_chain_id)
async
Get transfer limits and fee details for a route.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_token
|
str
|
Input token address on the origin chain. |
required |
output_token
|
str
|
Output token address on the destination chain. |
required |
origin_chain_id
|
int
|
Chain ID the deposit originates from. |
required |
destination_chain_id
|
int
|
Chain ID the funds are bridged to. |
required |
Returns:
| Type | Description |
|---|---|
Limits
|
The minimum/maximum deposit amounts and fee details for the route. |
Raises:
| Type | Description |
|---|---|
AcrossAPIError
|
If the API returns a non-success response. |
get_deposit_status(*, origin_chain_id=None, deposit_id=None, deposit_tx_ref=None)
async
Get the lifecycle status of a deposit.
Identify the deposit either by deposit_tx_ref (the origin-chain
deposit transaction hash) or by both origin_chain_id and deposit_id.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
origin_chain_id
|
Optional[int]
|
Chain ID the deposit originated on. |
None
|
deposit_id
|
Optional[Union[int, str]]
|
On-chain deposit ID. |
None
|
deposit_tx_ref
|
Optional[str]
|
Origin-chain deposit transaction hash. |
None
|
Returns:
| Type | Description |
|---|---|
DepositStatus
|
The current status of the deposit. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If neither identifier combination is provided. |
AcrossAPIError
|
If the API returns a non-success response. |
wait_for_deposit(*, origin_chain_id=None, deposit_id=None, deposit_tx_ref=None, poll_interval=DEFAULT_POLL_INTERVAL, timeout=None)
async
Poll a deposit's status until it reaches a terminal state.
A deposit is terminal once its status is filled, refunded, or
expired.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
origin_chain_id
|
Optional[int]
|
Chain ID the deposit originated on. |
None
|
deposit_id
|
Optional[Union[int, str]]
|
On-chain deposit ID. |
None
|
deposit_tx_ref
|
Optional[str]
|
Origin-chain deposit transaction hash. |
None
|
poll_interval
|
float
|
Seconds to wait between status checks. |
DEFAULT_POLL_INTERVAL
|
timeout
|
Optional[float]
|
Maximum seconds to wait before giving up. |
None
|
Returns:
| Type | Description |
|---|---|
DepositStatus
|
The terminal deposit status. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If neither identifier combination is provided. |
TimeoutError
|
If the deposit does not reach a terminal state in time. |
AcrossAPIError
|
If the API returns a non-success response. |
AcrossClient
A synchronous client for the Across Protocol bridge API.
The default base URL targets the public production API, which requires no API key for the quoting endpoints exposed here.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
base_url
|
str
|
Base URL of the Across API. Defaults to the production host. |
DEFAULT_BASE_URL
|
timeout
|
float
|
Per-request timeout in seconds. |
DEFAULT_TIMEOUT
|
client
|
Optional[Client]
|
An optional pre-configured :class: |
None
|
Example
with AcrossClient() as client: ... fees = client.get_suggested_fees( ... input_token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", ... output_token="0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", ... origin_chain_id=1, ... destination_chain_id=137, ... amount=10_000_000, ... ) ... print(fees.output_amount)
close()
Close the underlying HTTP client, unless it was supplied by the caller.
get_suggested_fees(*, input_token, output_token, origin_chain_id, destination_chain_id, amount, recipient=None)
Get a bridge quote (fees, output amount, limits) for a transfer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_token
|
str
|
Input token address on the origin chain. |
required |
output_token
|
str
|
Output token address on the destination chain. |
required |
origin_chain_id
|
int
|
Chain ID the deposit originates from. |
required |
destination_chain_id
|
int
|
Chain ID the funds are bridged to. |
required |
amount
|
Union[int, str]
|
Input amount in the token's smallest unit (int or decimal string). |
required |
recipient
|
Optional[str]
|
Optional recipient address used for a more precise gas estimate. |
None
|
Returns:
| Type | Description |
|---|---|
SuggestedFees
|
The suggested fees and resulting output amount for the transfer. |
Raises:
| Type | Description |
|---|---|
AcrossAPIError
|
If the API returns a non-success response. |
Example
with AcrossClient() as client: ... quote = client.get_suggested_fees( ... input_token="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", ... output_token="0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", ... origin_chain_id=1, ... destination_chain_id=137, ... amount=10_000_000, ... ) ... print(quote.total_relay_fee.total)
get_available_routes(*, origin_chain_id=None, destination_chain_id=None, origin_token=None, destination_token=None)
List supported token routes, optionally filtered.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
origin_chain_id
|
Optional[int]
|
Restrict results to this origin chain. |
None
|
destination_chain_id
|
Optional[int]
|
Restrict results to this destination chain. |
None
|
origin_token
|
Optional[str]
|
Restrict results to this origin token address. |
None
|
destination_token
|
Optional[str]
|
Restrict results to this destination token address. |
None
|
Returns:
| Type | Description |
|---|---|
list[AvailableRoute]
|
The supported routes matching the given filters. |
Raises:
| Type | Description |
|---|---|
AcrossAPIError
|
If the API returns a non-success response. |
get_limits(*, input_token, output_token, origin_chain_id, destination_chain_id)
Get transfer limits and fee details for a route.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_token
|
str
|
Input token address on the origin chain. |
required |
output_token
|
str
|
Output token address on the destination chain. |
required |
origin_chain_id
|
int
|
Chain ID the deposit originates from. |
required |
destination_chain_id
|
int
|
Chain ID the funds are bridged to. |
required |
Returns:
| Type | Description |
|---|---|
Limits
|
The minimum/maximum deposit amounts and fee details for the route. |
Raises:
| Type | Description |
|---|---|
AcrossAPIError
|
If the API returns a non-success response. |
get_deposit_status(*, origin_chain_id=None, deposit_id=None, deposit_tx_ref=None)
Get the lifecycle status of a deposit.
Identify the deposit either by deposit_tx_ref (the origin-chain
deposit transaction hash) or by both origin_chain_id and deposit_id.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
origin_chain_id
|
Optional[int]
|
Chain ID the deposit originated on. |
None
|
deposit_id
|
Optional[Union[int, str]]
|
On-chain deposit ID. |
None
|
deposit_tx_ref
|
Optional[str]
|
Origin-chain deposit transaction hash. |
None
|
Returns:
| Type | Description |
|---|---|
DepositStatus
|
The current status of the deposit. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If neither identifier combination is provided. |
AcrossAPIError
|
If the API returns a non-success response. |
wait_for_deposit(*, origin_chain_id=None, deposit_id=None, deposit_tx_ref=None, poll_interval=DEFAULT_POLL_INTERVAL, timeout=None)
Poll a deposit's status until it reaches a terminal state.
A deposit is terminal once its status is filled, refunded, or
expired.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
origin_chain_id
|
Optional[int]
|
Chain ID the deposit originated on. |
None
|
deposit_id
|
Optional[Union[int, str]]
|
On-chain deposit ID. |
None
|
deposit_tx_ref
|
Optional[str]
|
Origin-chain deposit transaction hash. |
None
|
poll_interval
|
float
|
Seconds to wait between status checks. |
DEFAULT_POLL_INTERVAL
|
timeout
|
Optional[float]
|
Maximum seconds to wait before giving up. |
None
|
Returns:
| Type | Description |
|---|---|
DepositStatus
|
The terminal deposit status. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If neither identifier combination is provided. |
TimeoutError
|
If the deposit does not reach a terminal state in time. |
AcrossAPIError
|
If the API returns a non-success response. |
AcrossAPIError
Bases: AcrossError
Raised when the Across API returns a non-success HTTP response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable description of the failure. |
required |
status_code
|
Optional[int]
|
The HTTP status code returned by the API, if available. |
None
|
response_body
|
Optional[Any]
|
The parsed JSON body (or raw text) of the error response. |
None
|
AcrossError
Bases: Exception
Base class for all errors raised by this library.
AvailableRoute
Bases: _ApiModel
A supported bridging route returned by GET /available-routes.
DepositStatus
Bases: _ApiModel
Lifecycle state of a deposit returned by GET /deposit/status.
The status field is one of pending, filled, expired, or
refunded. Use :attr:is_terminal to check whether it will change again.
is_terminal
property
Whether the deposit has reached a final state (filled/refunded/expired).
DepositStatusPagination
Bases: _ApiModel
Index of this fill within a multi-fill deposit.
FeeBreakdown
Bases: _ApiModel
A single fee component, expressed as a percentage and an absolute total.
GasFeeDetails
Bases: _ApiModel
Gas cost breakdown nested inside a /limits response.
Limits
Bases: _ApiModel
Transfer limits for a route returned by GET /limits.
RelayerFeeDetails
Bases: _ApiModel
Relayer fee breakdown nested inside a /limits response.
Reserves
Bases: _ApiModel
Liquidity reserve figures nested inside a /limits response.
SuggestedFees
Bases: _ApiModel
A bridge quote returned by GET /suggested-fees.
This is the headline quote: it contains the fees a relayer will charge, the resulting output amount, transfer limits, and the contract addresses needed to submit the deposit on-chain.
TokenInfo
Bases: _ApiModel
Metadata describing a token on a specific chain.
TransferLimits
Bases: _ApiModel
Per-route deposit size limits, all in the input token's smallest unit.