> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glider.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# tRPC Asset Taxonomy API

> Canonical-underlying lookup for issuer products, derivative markets, and onchain representations.

The `assetTaxonomy.*` namespace resolves a user-facing query such as `TSLA`,
`NVDA`, or `AAVE` to a canonical underlying, then returns issuer products,
derivative markets, and explicit onchain token representations linked to that
underlying.

* Base endpoint: `POST /v1/trpc`
* Namespace: `assetTaxonomy.*`
* Auth: public
* Primary model:
  canonical underlying first, issuer products or explicit crypto token
  representations and derivative markets second, exact onchain assets third

## Procedures

* `assetTaxonomy.searchIssuedAssets`
  * Purpose: search canonical underlyings by symbol, provider identifier,
    issuer symbol, product name, or underlying name
  * Input:
    * required `query`, 1-128 characters
    * optional `limit`, 1-25, default `10`
    * optional `assetClass`, for example `equity` or `crypto`
  * Response:
    * `items[].underlying`: canonical symbol, name, asset class, instrument
      type, country, currency, exchange, issuer product count, issued onchain
      asset count, supported issuer product count, supported issued onchain
      asset count, token representation count, and derivative market counts
    * `items[].marketDataIdentifiers`: provider mappings such as Massive
      symbols
    * `items[].issuedProducts`: issuer-level products such as Ondo or xStocks
    * `items[].issuedProducts[].assets`: chain-scoped CAIP assets/contracts
    * `items[].derivativeMarkets`: perpetual/futures-style markets such as
      Hyperliquid or Ondo Perps markets for the same canonical underlying
    * `items[].tokenRepresentations`: explicit chain-scoped crypto token
      representations such as native assets, primary tokens, bridged tokens,
      wrapped tokens, or issuer representations

* `assetTaxonomy.getIssuedAssetsForUnderlying`
  * Purpose: load the same grouped issued-asset surface for one canonical
    underlying id
  * Input:
    * required `assetCanonicalId`, UUID
  * Response:
    * `item`, or `null` when the canonical underlying is not found

## Example Calls

Search for Tesla issued assets:

```bash theme={null}
curl --request POST \
  --url 'https://api.glider.fi/v1/trpc/assetTaxonomy.searchIssuedAssets' \
  --header 'content-type: application/json' \
  --data '{"json":{"query":"TSLA","assetClass":"equity","limit":5}}'
```

Load one canonical underlying:

```bash theme={null}
curl --request POST \
  --url 'https://api.glider.fi/v1/trpc/assetTaxonomy.getIssuedAssetsForUnderlying' \
  --header 'content-type: application/json' \
  --data '{"json":{"assetCanonicalId":"11111111-1111-4111-8111-111111111111"}}'
```

## Runtime Notes

* The response is intentionally grouped for asset-first UX. A UI should render
  one `TSLA` result, then show Ondo, xStocks, and future issuer products under
  that underlying. For crypto, a UI should render one canonical symbol such as
  `AAVE`, then show exact chain/token representations under it.
* Tokenized equities should stay grouped as:
  canonical stock underlying -> issuer product -> chain-scoped token assets.
  For example, `NVDA` may have Ondo and xStocks products under the same
  underlying, and the Ondo `NVDAon` product may link to multiple EVM/SVM assets.
  Do not seed tokenized stock contracts directly as flat canonical token
  representations when an issuer product is known.
* Derivative markets are separate from both issuer products and token
  representations. A canonical underlying such as `NVDA` can have spot issuer
  products and perpetual/futures markets side by side. A Hyperliquid `NVDA-PERP`
  market is a market instrument, not an onchain token asset.
* Ondo Global Markets rows are backfilled into the new model by the migration
  so existing tokenized equity data can resolve through the canonical layer.
* Market-data integrations should use `marketDataIdentifiers` instead of
  deriving provider symbols from issuer-specific product data.
* Crypto identity is not inferred from symbol at request time. Concrete tokens
  appear under canonical crypto symbols only when an explicit
  `core.asset_token_subject_links` relationship exists.
* Curated crypto seeds can attach `coingecko` identifiers to canonical assets.
  CoinGecko-style aggregate market data should live at the canonical crypto
  subject level, while trade actions continue to resolve to exact chain assets.
* The crypto seed can optionally fetch CoinGecko `/coins/{id}` platform
  contracts and link only already-known Postgres `assets` rows by explicit
  chain/address matches. It does not create executable assets from CoinGecko
  data because decimals and trade metadata must remain authoritative in
  Postgres.
* Platform-link relationship types are curated by Glider. Provider platform
  metadata identifies candidate chain/address matches, while the seed controls
  whether those matches are primary, bridged, wrapped, native, or issuer
  representations.