Chain Identifiers

How chains are identified in the Superbridge API

Every chain in the Superbridge API is represented with three identifiers. Any of them can be used when querying or submitting requests that accept chain filters.

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 by /v1/chains as id, and by token, route, transaction, and activity payloads as chainId. Used in request parameters like fromChainId, toChainId, and chainId.

{
  "id": "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 by /v1/chains as uid, and by token, route, transaction, and activity payloads as chainUid.

{
  "uid": "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 by /v1/chains as keys, and by token, route, transaction, and activity payloads as chainKeys. Used in request parameters like fromChainKey, toChainKey, and chainKey.

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

Usage in requests

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

The Chains endpoint uses shorter query names: id, uid, and key.