getListingMarkets

Fetch a page of the permissionless-listing market catalog — the data behind a pools list. Every parameter is optional: with none set the backend returns its default first page of 20 rows.

import { getListingMarkets, ListingMarketStatus } from "@symmio/trading-core";
 
const page = await getListingMarkets(config, {
  marketStatus: ListingMarketStatus.LISTED,
  sortBy: "tvl",
  orderBy: "desc",
  limit: 50,
});

The catalog spans every listing the backend knows about, at every lifecycle stage — including markets that are still awaiting a deposit, under review, rejected, or delisted. Pass marketStatus: ListingMarketStatus.LISTED to see only tradable ones. Rows come back newest-listed first unless sortBy is set.

The two halves of the signature are exported as GetListingMarketsParameters (the parameters object, every field optional) and GetListingMarketsReturnType (an alias of ListingMarketPage), so you can name them in your own wrappers:

import type { GetListingMarketsParameters, GetListingMarketsReturnType } from "@symmio/trading-core";
 
function listedOnly(parameters: GetListingMarketsParameters): Promise<GetListingMarketsReturnType> {
  return getListingMarkets(config, { ...parameters, marketStatus: ListingMarketStatus.LISTED });
}

Parameters

Unset parameters are omitted from the request rather than sent empty, which is what lets the backend apply its own defaults.

Sort keys

sortBy mirrors the backend’s sort_by enum verbatim. Translating it into the SDK’s camelCase would break silently the moment the backend adds a key, so the wire literal is the public type:

Filters

filters is a bag of inclusive [min, max] bounds; every key is optional and either end may be omitted for a one-sided bound. Each becomes a {field}__ge / {field}__le query parameter.

Money and rate keys (ListingValueRange, min / max as bigint at 18 decimals):

The timestamp key (ListingTimeRange, min / max as number in Unix seconds):

Returns

Every envelope field is defaulted on the way through — counts to 0, items to an empty array — because the backend declares them as defaulted rather than required.

Examples

The default first page

const page = await getListingMarkets(config);
 
page.total; // every listing the backend knows about
page.items.length; // at most 20 — the backend's default page size

Tradable markets, deepest pools first

import { getListingMarkets, ListingMarketStatus } from "@symmio/trading-core";
 
const page = await getListingMarkets(config, {
  marketStatus: ListingMarketStatus.LISTED,
  sortBy: "tvl",
  orderBy: "desc",
  limit: 25,
  offset: pageIndex * 25,
});

A filter with an 18-decimal bound

Market cap of at least $1M, and a headline APR of at least 10% (10 * 1e18, because a rate is already a percentage):

import { getListingMarkets, LISTING_VALUE_DECIMALS, ListingMarketStatus } from "@symmio/trading-core";
 
const ONE = 10n ** BigInt(LISTING_VALUE_DECIMALS);
 
const page = await getListingMarkets(config, {
  marketStatus: ListingMarketStatus.LISTED,
  filters: {
    marketCap: { min: 1_000_000n * ONE },
    apr: { min: 10n * ONE },
  },
  sortBy: "apr",
});

Solana-deposited tokens only

chainIds filters on the chain the token was deposited from, not the chain the market trades on:

import { getListingMarkets, ListingDepositChainId } from "@symmio/trading-core";
 
const page = await getListingMarkets(config, {
  chainIds: [ListingDepositChainId.SOLANA],
  search: "bonk",
});
 
// Rows on this chain carry a base58 `contractAddress`, not a 0x address.

Query options

import { getListingMarketsQueryOptions } from "@symmio/trading-core";
import { useQuery } from "@tanstack/react-query";
 
useQuery(getListingMarketsQueryOptions(config, { sortBy: "tvl", limit: 50 }));

GetListingMarketsOptions is the action’s parameters plus a query bag of TanStack overrides — which is exactly why the free-text parameter is called search. The factory folds config.getChainConfigKey(chainId) into the key, so a runtime config override pointed at a different listing deployment refetches instead of serving the previous one’s cache. getListingMarketsQueryKey builds the same key for cache matching and invalidation.

The rest of the factory’s types are exported too: GetListingMarketsData is what the query resolves to (the same ListingMarketPage), GetListingMarketsQueryKey is the key getListingMarketsQueryKey returns, and GetListingMarketsQueryOptions is the options bag the factory produces.

Because search, filtering, sorting and paging are all server-side, each distinct combination is its own cache entry — change one and the hook refetches rather than re-slicing a page you already hold.

Throws

• LISTING_NOT_CONFIGURED — a SymmError (kind: "config") when the chain has no listing backend configured. Gate with supportsListingService to hide Pools instead of erroring.
• FETCH_LISTING_MARKETS_FAILED — the request itself failed. Any axios failure — including a transport error with no response, which arrives with status: 0 and statusText: "Unknown" — becomes a SymmApiError carrying status, statusText, responseData, url and method. A non-axios throw becomes a plain SymmError (kind: "api"), with the original error as its cause when it was an Error.

Related

• resolveListingService — the availability check this read runs first.
• ListingMarket — the row shape and its value contract.
• useListingMarkets — the React hook.
• Pools — the slice overview.