API.md

SQL API

Types

• crypto_network: built-in chain identity and metadata.
• crypto_asset: native or contract-backed identity. Equality and hashing use network plus native/contract key, not symbol.
• crypto_amount: arbitrary-precision decimal plus asset.
• crypto_units: checked uint256 raw units plus asset.
• crypto_address: validated network-qualified address.
• uint256: unsigned 256-bit integer.
• crypto_asset_kind: native, erc20, erc721, erc1155, spl, trc20, bep20, or unknown.

Amounts

crypto_make(numeric, text) -> crypto_amount
crypto_amount(crypto_amount) -> numeric
crypto_asset(crypto_amount) -> crypto_asset
crypto_symbol(crypto_amount) -> text
crypto_network(crypto_amount) -> crypto_network
crypto_decimals(crypto_amount) -> integer
crypto_amount_value(crypto_amount) -> numeric
crypto_amount_asset(crypto_amount) -> crypto_asset
crypto_amount_symbol(crypto_amount) -> text
crypto_amount_network(crypto_amount) -> crypto_network
crypto_amount_decimals(crypto_amount) -> integer
crypto_compare(crypto_amount, crypto_amount) -> integer
crypto_abs(crypto_amount) -> crypto_amount
crypto_is_zero/crypto_is_positive/crypto_is_negative(crypto_amount) -> boolean
crypto_to_json(crypto_amount) -> jsonb
crypto_from_json(jsonb) -> crypto_amount

Input syntax is <amount> <asset>. Prefer the crypto_amount_* accessor aliases for untyped string literals; the shorter legacy names remain available for typed values. + and - require identical asset identities. * numeric, / numeric, and unary - preserve identity. Division and avg() use half-even rounding with at least 38 fractional digits; raw-unit conversion remains exact and rejects unrepresentable fractions.

sum(crypto_amount) and avg(crypto_amount) ignore nulls and reject mixed assets.

Units and uint256

crypto_from_units(uint256, text) -> crypto_amount
crypto_to_units(crypto_amount) -> uint256
crypto_normalize_units(uint256, text) -> crypto_amount
crypto_units_make(uint256, text) -> crypto_units
crypto_units_value(crypto_units) -> uint256
crypto_units_asset(crypto_units) -> crypto_asset
crypto_units_to_amount(crypto_units) -> crypto_amount
crypto_amount_to_units(crypto_amount) -> crypto_units
crypto_units_to_json(crypto_units) -> jsonb
crypto_units_from_json(jsonb) -> crypto_units

uint256 accepts unsigned decimal or 0x hex input. It supports +, -, *, /, %, <<, >>, &, |, and ^, all with checked range and zero-division behavior.

uint256_from_hex(text) -> uint256
uint256_to_hex(uint256) -> text
uint256_to_numeric(uint256) -> numeric
uint256_to_json(uint256) -> jsonb
uint256_from_json(jsonb) -> uint256

Integer, bigint, and numeric casts to uint256 are exact and reject negative or out-of-range values.

Networks, addresses, and assets

crypto_network_info(crypto_network) -> jsonb
crypto_network_family(crypto_network) -> text
crypto_chain_id(crypto_network) -> bigint
crypto_native_asset(crypto_network) -> text
crypto_networks() -> table

crypto_address_make(text, crypto_network) -> crypto_address
crypto_address_valid(text, crypto_network) -> boolean
crypto_address_network(crypto_address) -> crypto_network
crypto_address_normalize(crypto_address) -> text
crypto_address_payload(crypto_address) -> bytea
crypto_address_to_json(crypto_address) -> jsonb
crypto_address_from_json(jsonb) -> crypto_address

crypto_asset_info(crypto_asset) -> jsonb
crypto_asset_symbol(crypto_asset) -> text
crypto_asset_network(crypto_asset) -> crypto_network
crypto_asset_decimals(crypto_asset) -> integer
crypto_token_standard(crypto_asset) -> crypto_asset_kind
crypto_asset_to_json(crypto_asset) -> jsonb
crypto_asset_from_json(jsonb) -> crypto_asset

EVM, Bitcoin mainnet, Solana, TRON, Cardano mainnet, and Polkadot addresses are validated and canonicalized. Mixed-case EVM input must satisfy EIP-55. Bitcoin witness versions and program lengths, Cardano address headers and lengths, and Polkadot's SS58 prefix, 32-byte account id, and checksum are validated by their chain-specific rules.

crypto_assets is an append-only token registry with a globally unique (network, contract) key and an active-only unique (network, symbol) key. This permits a deprecated token contract to be replaced under the same ticker. crypto_register_asset validates the address/network relationship and records creator/time audit fields. crypto_deprecate_asset(symbol, network, reason) removes a registration from legacy symbol lookup while retaining its audited row. A trigger rejects changes to registered identity or metadata, and public table access is read-only.

Legacy SYMBOL@network input resolves only active rows. Contract-token output is a versioned v1|token|... snapshot. Input validates every snapshot against the matching active or deprecated registry row, preventing altered symbol, name, decimal, or kind metadata from masquerading as the same contract identity. Existing typed values remain readable after deprecation. The v0.2 registry accepts ERC-20 contracts on EVM-family networks; the wider asset-kind enum reserves stable names for later releases.

Indexing and JSON

crypto_amount, crypto_asset, crypto_units, crypto_address, and uint256 have default B-tree and hash operator classes. Every core value type has paired JSONB encoder/decoder functions, including crypto_to_json / crypto_from_json, crypto_units_to_json / crypto_units_from_json, and equivalent *_to_json / *_from_json pairs for assets, addresses, and uint256.

pg_money

crypto_fiat_amount(value, price) returns a numeric fiat amount. When money_with_currency and money_make(numeric,text) are present, crypto_enable_pg_money() installs:

crypto_to_money(crypto_amount, fiat_currency text, price numeric)
  -> money_with_currency

There is no implicit crypto-to-fiat cast.