Chain Identifiers

How chains are identified in the Superbridge API

Every chain in the Superbridge API is represented with three identifiers. All three are returned in every payload that includes chain data, and any of them can be used when querying or submitting requests.

You can see the values returned for chains by checking out the /chains endpoint.

Chain ID

The native blockchain chain ID. This is the numeric identifier used by the chain itself (e.g. 1 for Ethereum, 10 for Optimism, 42161 for Arbitrum One).

Chain IDs are guaranteed to be static and will never change.

Returned as a string in the chainId field. Used in request parameters like fromChainId and toChainId.

{
  "chainId": "1"
}

Chain UID

A UUID assigned internally by Superbridge to uniquely identify a chain. Unlike Chain IDs, these are guaranteed to be globally unique across all chain types.

Some testnets and the occasional mainnet have conflicting chain IDs, making chainId alone insufficient for unique identification. The chainUid resolves this by providing a guaranteed unique identifier for every chain.

Chain UIDs are guaranteed to be static and will never change.

Returned as a string in the chainUid field.

{
  "chainUid": "9a3f7b2e-1d4c-4e8a-b6f5-0c2d9e8a7b3f"
}

Chain Key

A human-readable shorthand identifier for a chain (e.g. eth for Ethereum, base for Base, arb for Arbitrum One). A chain may have multiple keys, so this is returned as an array.

Chain keys are stable but additive. New keys may be added to a chain over time, but existing keys will never be removed.

Returned as an array of strings in the chainKeys field. Used in request parameters like fromChainKey and toChainKey.

{
  "chainKeys": ["eth", "ethereum"]
}

Usage in requests

When an endpoint accepts a chain parameter, you can use any of the three identifier types. For example, the Routes endpoint accepts both fromChainId/toChainId and fromChainKey/toChainKey.