Assets and networks

The global network and token registries: a network's coinType and slug, a token's contractAddress and decimals, and the kill switch.

V3 Custody maintains two global registries: networks and tokens. They define which blockchains and assets the platform understands, and addresses, policies, reports, and the webhook all reference them.

Network registry

A network is described by two keys:

Key	Meaning
`coinType`	a BIP-44/SLIP-0044 identifier, unique (TRON is 195, Ethereum is 60)
`slug`	the lowercase on-chain network name; referenced by `Address.network`, tokens, and webhook matching

The network segment in a Vault's schema adds networks to this registry by coinType (see Vaults and derivation).

GET /api/v1/networks returns the global registry (sorted by coinType ascending). The picker uses it when creating a Vault and registering tokens.
POST /api/v1/networks registers a network.

Token registry

A token is tied to a network and describes an asset:

{
  "id": "cmr3f41z20001psp7phmyapw3",
  "code": "usdt",
  "symbol": "USDT",
  "name": "Tether USD",
  "networkId": "cmr3f...",
  "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "decimals": 6,
  "enabled": true
}

Field	Meaning
`code`	a globally unique token code (immutable)
`symbol` / `name`	display values, mutable
`networkId`	the network the token belongs to
`contractAddress`	the contract address (required for non-native tokens; unique per network; immutable)
`decimals`	the token's scale (immutable)
`enabled`	the kill switch

Native coin: one per network. Non-native tokens must have a contractAddress, which the webhook uses to verify incoming deposits.
Uniqueness: code is unique globally, contractAddress is unique per network.
GET /api/v1/tokens lists tokens.
POST /api/v1/tokens registers a token (the network must come from the Networks registry, by networkCode).

Updates and the kill switch

PATCH /api/v1/tokens/{id} changes symbol, name, logoUri, and enabled. The code, contractAddress, and decimals fields are immutable.

enabled=false is the kill switch:

When `enabled=false`	Behavior
transfers of this token	rejected with `TOKEN_NOT_FOUND`
webhook	ignores events for the token
new policies and Vaults	can't reference it
existing data and ledger accounts	left untouched

How this connects to everything else

decimals defines the raw ↔ decimal conversion (see Amounts and precision).
contractAddress is used by the webhook to resolve the token (see Webhooks).
coinType determines the derivation path m/44/{coinType}/... (see Vaults and derivation).

Common mistakes

Symptom	Cause
token won't register	the network isn't in the Networks registry; an existing `networkCode` is required
non-native token without `contractAddress`	it's required for non-native tokens
duplicate `contractAddress`	it must be unique per network
transfer fails with `TOKEN_NOT_FOUND`	the token is disabled by the kill switch (`enabled=false`)
trying to change `decimals`/`code`	they're immutable; the only option is to recreate the token

Next steps

Vaults and derivation

coinType, networks, and the derivation path.

Amounts and precision

decimals and raw/decimal.

Webhooks

Resolving tokens by contractAddress.

API Reference

The network and token registries.

Was this page helpful?