Identifiers¶

Routes uses canonical asset keys to identify assets across chains and venues.

Asset identifiers¶

An asset is a specific spendable instance on a chain or venue — an ERC-20 contract on Ethereum, an SPL mint on Solana, or a native coin.

asset_key¶

Canonical identity for an asset.

• Deterministic and globally unique within Routes
• Stable: never changes, never reused
• Recommended for storage and configuration

Partner symbols¶

Organization-scoped aliases for asset keys.

• Registered via PUT /symbols
• Accepted anywhere asset_key is accepted in requests
• Opaque strings: 2–32 characters, [A-Za-z0-9._:-], must start and end with alphanumeric
• Case-insensitive for lookup, case-preserving for storage
• Bijective within your organization: each symbol maps to exactly one asset key, and each asset key maps to at most one symbol
• Input-only — responses always use canonical asset_key

Grammar¶

The asset_key grammar:

<kind> "." <namespace> [ ":" <locator> ( "_" <locator> )* ]

Three characters, three roles:

• . separates kind from namespace (appears exactly once)
• : separates namespace from locators (appears at most once)
• _ separates locators from each other

Parsing:

1. Split on . → kind
2. Split remainder on first : → namespace (before) and locator string (after)
3. Split locator string on _ → individual locators

To extract the terminal identifier (address, symbol, mint), split on the last _. If there is no _, the part after : is the only locator.

Normalization rules¶

Canonicalization is strict:

• kind and namespace MUST be lowercase
• venue labels MUST be lowercase
• hex locators MUST be lowercase
• case-sensitive encodings MUST preserve bytes exactly (e.g., base58)

If a component is case-insensitive, it will be canonicalized to lowercase.

Asset kinds¶

Canonical forms¶

EVM assets¶

Native token:

• native.evm:<chain_id>

ERC-20:

• erc20.evm:<chain_id>_<address>

Constraints:

• chain_id: base-10 integer
• address: lowercase 0x + 40 hex chars

Example:

erc20.evm:1_0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

Solana assets¶

Native SOL:

• native.solana

SPL token:

• spl.solana:<mint>

Constraints:

• mint: base58, case-sensitive

Example:

spl.solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

UTXO native assets¶

• native.btc
• native.zec
• native.bch

UTXO native assets do not use contract-style locators.

XRPL assets¶

Native XRP:

• native.xrpl

Issued tokens:

• issued.xrpl:<issuer_address>_<currency_hex>

Constraints:

• issuer_address: r-address (case-sensitive, base58)
• currency_hex: uppercase hex-encoded currency code (40 chars for non-standard codes)

Example (RLUSD):

issued.xrpl:rMxCKbEDwqr76QuheSUMo8s8yrJzPAfBYp_524C55534400000000000000000000000000000000

Synthetic assets¶

Balances that exist only inside a venue/accounting domain (not transferable as an on-chain token):

• syn.<venue>:<symbol>

Constraints:

• venue: lowercase
• symbol: lowercase unless the venue's symbol system is case-sensitive

Examples:

syn.binance:btc
syn.hyperliquid:spot-btc

Using identifiers in requests¶

Where an asset is required, send exactly one of:

• *_asset_key
• *_symbol

Rules:

• If both are provided for the same field -> 400 invalid_parameter
• If an asset_key is syntactically invalid -> 400 invalid_asset_key
• If a symbol is not registered for your organization -> 404 symbol_not_found

Different asset slots in the same request may use different identifier types. For example, from_symbol and to_asset_key is valid.

Recommendation:

• Store asset_key for anything persistent (whitelists, policies, supported assets)
• Use symbols for ergonomic request building

Common pitfalls¶

Solana mints are case-sensitive. Base58 is case-sensitive; do not lowercase SPL mints. Use GET /resolve to canonicalize identity.

EVM addresses are canonicalized to lowercase. Routes accepts mixed-case (EIP-55) addresses on input and stores/returns the canonical lowercase form.

Do not infer decimals. *_ui fields depend on the asset's decimals value. Always look up the asset via GET /assets before parsing or formatting UI amounts.

Synthetic assets are not on-chain. syn.* assets represent venue-local balances and cannot be treated as transferable tokens.

Symbols are case-insensitive. ETH and eth resolve to the same asset key. The stored casing is preserved but lookups ignore case.