Skip to content

API reference

squidrouter

squidrouter-py: a typed Python client for the Squid Router API.

Squid Router is an Axelar-powered aggregator for cross-chain swaps and bridging. This package provides synchronous (:class:SquidClient) and asynchronous (:class:AsyncSquidClient) clients built on httpx and pydantic.

Every request requires an integrator ID (free from the Squid integrator portal), sent by default in the x-integrator-id header.

AsyncSquidClient

Asynchronous client for the Squid Router v2 API.

The async counterpart to :class:~squidrouter.SquidClient, built on :class:httpx.AsyncClient. Every request requires an integrator ID, sent by default in the x-integrator-id header. Obtain a free integrator ID from the Squid integrator portal (https://docs.squidrouter.com).

Use it as an async context manager to ensure the connection pool is closed::

async with AsyncSquidClient(integrator_id="my-id") as client:
    chains = await client.get_chains()

Parameters:

Name Type Description Default
integrator_id str

The integrator ID issued by Squid. Required.

 required
base_url str

Base URL of the Squid API. Defaults to the v2 endpoint at https://apiplus.squidrouter.com.

 DEFAULT_BASE_URL
integrator_header str

Header name carrying the integrator ID. Defaults to x-integrator-id.

 DEFAULT_INTEGRATOR_HEADER
timeout float

Request timeout in seconds.

 DEFAULT_TIMEOUT
client Optional[AsyncClient]

An optional pre-configured :class:httpx.AsyncClient. When supplied, the caller owns its lifecycle and it will not be closed by this client.

 None

aclose() async

Close the underlying HTTP client if it is owned by this instance.

get_chains() async

Fetch the chains supported by Squid Router.

Returns:

Name Type Description
A ChainsResponse

class:~squidrouter.models.ChainsResponse listing supported
ChainsResponse

chains.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

get_tokens() async

Fetch the tokens supported by Squid Router.

Returns:

Name Type Description
A TokensResponse

class:~squidrouter.models.TokensResponse listing supported
TokensResponse

tokens.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

get_route(request) async

Request an optimal cross-chain route (quote) for a swap or bridge.

Parameters:

Name Type Description Default
request Union[RouteRequest, dict[str, Any]]

The route parameters, either a :class:~squidrouter.models.RouteRequest or a plain dict using the API's camelCase field names.

 required

Returns:

Name Type Description
A RouteResponse

class:~squidrouter.models.RouteResponse. Its request_id is
RouteResponse

populated from the x-request-id response header; together with
RouteResponse

route.quote_id it is required to track status.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

get_status(*, transaction_id, request_id=None, from_chain_id=None, to_chain_id=None, quote_id=None) async

Fetch the status of a cross-chain transaction.

Parameters:

Name Type Description Default
transaction_id str

The source-chain transaction hash.

 required
request_id Optional[str]

The x-request-id value returned by :meth:get_route.

 None
from_chain_id Optional[Union[int, str]]

The source chain ID.

 None
to_chain_id Optional[Union[int, str]]

The destination chain ID.

 None
quote_id Optional[str]

The route.quote_id from the route response. Required for Squid Intents transactions (enabled by default); omitting it can cause the transaction to fail.

 None

Returns:

Name Type Description
A StatusResponse

class:~squidrouter.models.StatusResponse.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

poll_status(*, transaction_id, request_id=None, from_chain_id=None, to_chain_id=None, quote_id=None, interval=5.0, timeout=600.0) async

Poll :meth:get_status until the transaction reaches a terminal state.

Terminal states are success, partial_success, needs_gas and not_found. A 404 (transaction not yet indexed) is treated as in-progress and retried.

Parameters:

Name Type Description Default
transaction_id str

The source-chain transaction hash.

 required
request_id Optional[str]

The x-request-id value returned by :meth:get_route.

 None
from_chain_id Optional[Union[int, str]]

The source chain ID.

 None
to_chain_id Optional[Union[int, str]]

The destination chain ID.

 None
quote_id Optional[str]

The route.quote_id from the route response.

 None
interval float

Seconds to wait between polls.

 5.0
timeout float

Maximum total seconds to poll before giving up.

 600.0

Returns:

Type Description
StatusResponse

The terminal :class:~squidrouter.models.StatusResponse.

Raises:

Type Description
StatusTimeoutError

If no terminal state is reached within timeout seconds.
SquidAPIError

For non-404 API errors.

SquidClient

Synchronous client for the Squid Router v2 API.

Squid is an Axelar-powered aggregator for cross-chain swaps and bridging. Every request requires an integrator ID, sent by default in the x-integrator-id header. Obtain a free integrator ID from the Squid integrator portal (https://docs.squidrouter.com).

The client may be used as a context manager to ensure the underlying connection pool is closed::

with SquidClient(integrator_id="my-id") as client:
    chains = client.get_chains()

Parameters:

Name Type Description Default
integrator_id str

The integrator ID issued by Squid. Required.

 required
base_url str

Base URL of the Squid API. Defaults to the v2 endpoint at https://apiplus.squidrouter.com.

 DEFAULT_BASE_URL
integrator_header str

Header name carrying the integrator ID. Defaults to x-integrator-id.

 DEFAULT_INTEGRATOR_HEADER
timeout float

Request timeout in seconds.

 DEFAULT_TIMEOUT
client Optional[Client]

An optional pre-configured :class:httpx.Client to use instead of creating one internally. When supplied, the caller owns its lifecycle and it will not be closed by this client.

 None

close()

Close the underlying HTTP client if it is owned by this instance.

get_chains()

Fetch the chains supported by Squid Router.

Returns:

Name Type Description
A ChainsResponse

class:~squidrouter.models.ChainsResponse listing supported
ChainsResponse

chains.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

get_tokens()

Fetch the tokens supported by Squid Router.

Returns:

Name Type Description
A TokensResponse

class:~squidrouter.models.TokensResponse listing supported
TokensResponse

tokens.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

get_route(request)

Request an optimal cross-chain route (quote) for a swap or bridge.

Parameters:

Name Type Description Default
request Union[RouteRequest, dict[str, Any]]

The route parameters, either a :class:~squidrouter.models.RouteRequest or a plain dict using the API's camelCase field names.

 required

Returns:

Name Type Description
A RouteResponse

class:~squidrouter.models.RouteResponse. Its request_id is
RouteResponse

populated from the x-request-id response header; together with
RouteResponse

route.quote_id it is required to track status.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

get_status(*, transaction_id, request_id=None, from_chain_id=None, to_chain_id=None, quote_id=None)

Fetch the status of a cross-chain transaction.

Parameters:

Name Type Description Default
transaction_id str

The source-chain transaction hash.

 required
request_id Optional[str]

The x-request-id value returned by :meth:get_route.

 None
from_chain_id Optional[Union[int, str]]

The source chain ID.

 None
to_chain_id Optional[Union[int, str]]

The destination chain ID.

 None
quote_id Optional[str]

The route.quote_id from the route response. Required for Squid Intents transactions (enabled by default); omitting it can cause the transaction to fail.

 None

Returns:

Name Type Description
A StatusResponse

class:~squidrouter.models.StatusResponse.

Raises:

Type Description
SquidAPIError

If the API returns an unsuccessful status.

poll_status(*, transaction_id, request_id=None, from_chain_id=None, to_chain_id=None, quote_id=None, interval=5.0, timeout=600.0)

Poll :meth:get_status until the transaction reaches a terminal state.

Terminal states are success, partial_success, needs_gas and not_found. A 404 (transaction not yet indexed) is treated as in-progress and retried.

Parameters:

Name Type Description Default
transaction_id str

The source-chain transaction hash.

 required
request_id Optional[str]

The x-request-id value returned by :meth:get_route.

 None
from_chain_id Optional[Union[int, str]]

The source chain ID.

 None
to_chain_id Optional[Union[int, str]]

The destination chain ID.

 None
quote_id Optional[str]

The route.quote_id from the route response.

 None
interval float

Seconds to wait between polls.

 5.0
timeout float

Maximum total seconds to poll before giving up.

 600.0

Returns:

Type Description
StatusResponse

The terminal :class:~squidrouter.models.StatusResponse.

Raises:

Type Description
StatusTimeoutError

If no terminal state is reached within timeout seconds.
SquidAPIError

For non-404 API errors.

SquidAPIError

Bases: SquidError

Raised when the Squid Router API returns an unsuccessful HTTP status.

Attributes:

Name Type Description
status_code

The HTTP status code returned by the API.
message

A human-readable error message, extracted from the response body when possible.
response_body

The decoded JSON body of the error response, or the raw text when the body is not valid JSON.
request_id

The value of the x-request-id response header, useful when reporting issues to Squid support.

SquidError

Bases: Exception

Base class for all errors raised by :mod:squidrouter.

StatusTimeoutError

Bases: SquidError

Raised when :meth:poll_status does not reach a terminal state in time.

Attributes:

Name Type Description
last_status

The most recent squidTransactionStatus value observed before the timeout, if any was retrieved.

Chain

Bases: SquidModel

A chain supported by Squid Router (GET /v2/chains).

Attributes:

Name Type Description
chain_id Optional[Union[int, str]]

The chain's identifier, sent as chainId. May be an int or string depending on the chain type.
chain_name Optional[str]

Human-readable chain name, sent as chainName.
chain_type Optional[str]

The chain family (e.g. evm, cosmos), sent as chainType.
network_name Optional[str]

The network name, sent as networkName.
rpc Optional[str]

The default RPC endpoint for the chain.

ChainsResponse

Bases: SquidModel

Response for GET /v2/chains.

Attributes:

Name Type Description
chains list[Chain]

The list of supported chains.

Estimate

Bases: SquidModel

Estimated outcome of a route.

Attributes:

Name Type Description
to_amount Optional[str]

Estimated amount received at the destination, as a string.
to_amount_min Optional[str]

Minimum guaranteed amount after slippage, as a string.
fee_costs Optional[list[dict[str, Any]]]

List of fee breakdown objects.
gas_costs Optional[list[dict[str, Any]]]

List of gas cost breakdown objects.
estimated_route_duration Optional[Union[int, float]]

Estimated route duration in seconds.

Route

Bases: SquidModel

A single cross-chain route returned by POST /v2/route.

Attributes:

Name Type Description
estimate Optional[Estimate]

The estimated outcome of executing this route.
transaction_request Optional[TransactionRequest]

The signable transaction for this route, sent by the API as transactionRequest. Absent for quote-only requests.
quote_id Optional[str]

Identifier for this quote, sent as quoteId. Must be passed to the status endpoint for Squid Intents transactions.
params Optional[dict[str, Any]]

Echo of the route parameters used to compute this route.

RouteRequest

Bases: BaseModel

Parameters for a cross-chain route request (POST /v2/route).

Attributes:

Name Type Description
from_chain str

Source chain ID (e.g. "56" for BNB Chain). Sent as fromChain.
from_token str

Source token contract address. Sent as fromToken.
from_amount str

Amount to swap, in the token's smallest unit (wei-style integer string). Sent as fromAmount.
to_chain str

Destination chain ID (e.g. "42161" for Arbitrum). Sent as toChain.
to_token str

Destination token contract address. Sent as toToken.
from_address str

Address initiating the swap. Sent as fromAddress.
to_address str

Address receiving the swapped tokens. Sent as toAddress.
slippage Optional[float]

Maximum acceptable slippage as a percentage (e.g. 1.0 for 1%). Optional.
slippage_config Optional[dict[str, Any]]

Advanced slippage configuration object, sent as slippageConfig when provided.
enable_boost Optional[bool]

Whether to enable Squid Boost for faster settlement. Sent as enableBoost.
quote_only Optional[bool]

When True, returns a quote without a signable transactionRequest. Sent as quoteOnly.

to_payload()

Serialize to the JSON body expected by POST /v2/route.

Returns:

Type Description
dict[str, Any]

A dict using the API's camelCase field names, omitting unset
dict[str, Any]

optional values.

RouteResponse

Bases: SquidModel

Top-level response for POST /v2/route.

Attributes:

Name Type Description
route Optional[Route]

The computed route, including estimate and transaction request.
request_id Optional[str]

The x-request-id response header value, populated by the client. Required (with quote_id) for status tracking.

StatusResponse

Bases: SquidModel

Response for GET /v2/status.

Attributes:

Name Type Description
squid_transaction_status Optional[str]

Overall status of the cross-chain transaction. Terminal values include success, partial_success, needs_gas and not_found. Sent as squidTransactionStatus.
status Optional[str]

A finer-grained status string, when provided by the API.
id Optional[str]

The transaction identifier echoed by the API.
from_chain Optional[dict[str, Any]]

Source-chain status object.
to_chain Optional[dict[str, Any]]

Destination-chain status object.

Token

Bases: SquidModel

A token supported by Squid Router (GET /v2/tokens).

Attributes:

Name Type Description
symbol Optional[str]

The token's ticker symbol.
name Optional[str]

The token's display name.
address Optional[str]

The token's contract address.
decimals Optional[int]

The token's decimal precision.
chain_id Optional[Union[int, str]]

The chain the token lives on, sent as chainId.
coingecko_id Optional[str]

The CoinGecko identifier, sent as coingeckoId.
logo_uri Optional[str]

A URI to the token logo, sent as logoURI.

TokensResponse

Bases: SquidModel

Response for GET /v2/tokens.

Attributes:

Name Type Description
tokens list[Token]

The list of supported tokens.

TransactionRequest

Bases: SquidModel

An on-chain transaction to execute a route.

Attributes:

Name Type Description
target Optional[str]

Contract address to send the transaction to. Some responses use targetAddress instead; both are accepted.
data Optional[str]

Calldata for the transaction.
value Optional[str]

Native token value to send, as a string.
gas_limit Optional[str]

Suggested gas limit, sent by the API as gasLimit.
gas_price Optional[str]

Suggested gas price, sent by the API as gasPrice.