> For the complete documentation index, see [llms.txt](https://docs.metric.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metric.xyz/reference/api/metadata.md). # Metadata `GET /public/v1/evm/{chain_id}/metadata` Returns the funded pools on a chain together with their onchain metadata, token details, fiat prices and pool state. By default only pools with at least $10 of TVL are listed; pools whose TVL can't be computed are hidden too. Pass `minTvlFiat=0` to list every pool. Results are paginated. This is a public endpoint. Authentication is not required. ### Path parameters | Name | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chain_id` | integer | EVM chain ID, e.g. `1`. Must be one of the chains returned by `GET /public/v1/chains`. An unsupported chain returns `404 {"error": "Unknown chainId: 999999"}`; a non-numeric value returns `400`. | ### Query parameters All optional. Unknown parameters are ignored. | Name | Type | Default | Description | | ------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `count` | integer | `50` | Page size, maximum `500` (larger values are capped). `0` is treated as `1`. Page through with `offset` to get the full list. | | `offset` | integer | `0` | Index of the first pool to return. Use `nextOffset` from the previous page. An offset past the end returns an empty `data` array. | | `sortBy` | string | `tiered` | One of `tiered`, `tvl`, `created`, `volume`, `apr`, `apr7d` (case-insensitive). `volume` breaks ties by TVL. Any other value returns `400`. | | `sortOrder` | string | `desc` | `asc` or `desc`. Any other value returns `400`. | | `include24h` | boolean | `false` | `true` adds `tvlFiat` and `analytics24h` to every pool. Must be exactly `true` or `false`. | | `minTvlFiat` | number | `10` | Minimum pool TVL in USD. Pools whose TVL can't be computed are dropped while a floor is set. `0` disables the filter. | | `tier` | string | all | Comma-separated subset of `green`, `yellow`, `red`, e.g. `tier=green,yellow`. Any other value returns `400`. | | `lockedPricingOnly` | boolean | `false` | `true` keeps only pools whose Price Provider can never be changed (`lockedPricing: true`). | | `depositAllowlistEnabled` | boolean | `false` | `true` keeps only pools with deposit allowlisting enabled. | | `blacklistedOnly` | boolean | `false` | `true` returns only pools delisted by Metric (`tierQualification: "black"`). No default TVL floor applies. | | `addresses` | string | none | Comma-separated pool addresses, at most `500`. Returns only those pools. See [Look up specific pools](#look-up-specific-pools). | | `contract_version` | string | all | Keep only pools of this contract release, e.g. `v1`. An unknown or disabled release returns `404`. | | `fiat` | string | `USD` | Fiat currency for prices. Only `USD` is supported; any other value returns `400`. | The cross-chain endpoint `GET /public/v1/evm/metadata` takes the same parameters except `sortBy=created`, which is per-chain only, plus `chainIds` (comma-separated chain IDs, e.g. `chainIds=1,56`) to limit it to some chains. A non-numeric entry returns `400`; an unknown chain ID returns no rows. ### Pagination Read `nextOffset` from the response and pass it back as `offset` to fetch the next page. `nextOffset` is `null` on the last page. `total` is the full count across all pages. ### Look up specific pools If you already know which pools you want, for example the pools a wallet holds positions in, pass them in `addresses` instead of requesting each pool on its own or paging through the full list: ```bash curl "https://api.metric.xyz/public/v1/evm/1/metadata?include24h=true&addresses=0xF85AfbADeCC7F23Dd173ed706f07d9C7e2473e24" ``` * Up to `500` addresses, comma-separated. Case doesn't matter and duplicates are ignored. * Only the pools you name are returned. A pool that isn't listed (an unknown address, a pool delisted by Metric, or one created since the list was last refreshed) is left out rather than returning an error. * The default `$10` TVL floor doesn't apply, so a small pool you name is still returned. If you pass `minTvlFiat` yourself it applies, as do `tier`, `lockedPricingOnly` and `depositAllowlistEnabled`. * `sortBy`, `sortOrder`, `count` and `offset` work as on the full list, and `total` counts only the pools returned. The default `count` is `50`, so pass a larger `count` when naming more than 50 pools. * On the cross-chain endpoint, a pool address found on more than one chain returns one row per chain. Use `chainIds` to limit the chains searched. * A malformed address, an empty value, more than `500` addresses, or `addresses` together with `blacklistedOnly=true` returns `400`. ### Request ```bash curl "https://api.metric.xyz/public/v1/evm/1/metadata?count=1&sortBy=tvl&include24h=true" ``` ```bash curl "https://api.metric.xyz/public/v1/evm/1/metadata?count=50&offset=50" ``` ### Response `200 OK`: a `PaginatedMetadataResponse` envelope. ```json { "data": [ { "pair": "WETH/USDC", "chain": "ethereum", "contractVersion": "v1", "poolAddress": "0xF85AfbADeCC7F23Dd173ed706f07d9C7e2473e24", "priceProviderAddress": "0xa07A8Aa6D5311eCfc01C01eC9Eefd17b0A8A9445", "priceProviderDetails": { "providerType": "anchored", "oracle": "0x30a88bf894D1b806125a23ebf23D715496fD7102", "feedMode": "synthetic", "marginStep": "0", "minMargin": "5000000000000", "maxRefStaleness": "15", "maxSpreadMult": "1000000000000000000", "mutableParams": false, "source": "0x599b0027942fC98BadC121cB789fE0D4a11A0879", "confidenceParam": null, "baseMaxStaleness": "15", "quoteMaxStaleness": "15", "baseSpreadMult": "0", "quoteSpreadMult": "0" }, "token0": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "token1": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "token0Symbol": "WETH", "token1Symbol": "USDC", "token0Name": "WETH", "token1Name": "USDC", "token0Decimals": 18, "token1Decimals": 6, "token0LogoUrl": "https://cdn.metric.xyz/tokens/1/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.png", "token1LogoUrl": "https://cdn.metric.xyz/tokens/1/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.png", "token0BrandColor": "#101010", "token1BrandColor": "#0050b0", "token0FiatPrice": 2709.4, "token1FiatPrice": 0.999853, "tvlFiat": 115757.94, "creator": "0x80f0A7d148729CcEdb6cD07FBaAEfC5A16f33D4f", "admin": "0x80f0A7d148729CcEdb6cD07FBaAEfC5A16f33D4f", "adminUsername": "Carcosa", "verifiedAdmin": true, "adminFeeDestination": "0x53F0ACE6156DAF7F6b50B395F6DD66C9d2f50c8c", "spreadProtocolFeeE6": 150000, "spreadAdminFeeE6": 200000, "protocolNotionalFeeE8": 0, "adminNotionalFeeE8": 0, "analytics24h": { "fromTs": 1790422039, "toTs": 1790508439, "generatedAtTs": 1790508439, "fiatAvailable": true, "fiatCoveragePct": 100, "fiatStatus": "active", "fiatCurrency": "USD", "fromBlock": 26061325, "toBlock": 26068435, "swapTxCount": 493, "liquidityEventCount": 0, "liquidityAddEventCount": 0, "liquidityRemoveEventCount": 0, "transfers": 493, "token0": { "liquidityRaw": "24431277185857724312", "volumeRaw": "287082472219069397624", "inflowRaw": "144190709723083426314", "outflowRaw": "142891762495985971310", "netRaw": "1298947227097455004", "liquidityFiat": 66194.1, "volumeFiat": 777821.25, "inflowFiat": 390670.31, "outflowFiat": 387150.94, "netFiat": 3519.37 }, "token1": { "liquidityRaw": "49571124074", "volumeRaw": "773469090135", "inflowRaw": "385002290049", "outflowRaw": "388466800086", "netRaw": "-3464510037", "liquidityFiat": 49563.84, "volumeFiat": 773355.39, "inflowFiat": 384945.69, "outflowFiat": 388409.7, "netFiat": -3464 }, "pricingMode": "estimated_spot", "usdCoveragePct": 0, "aprBps": 843, "feesFiat": 26.89, "tvlFiat": 115757.94, "volumeFiat": 775588.32 }, "aprBps7d": 2805, "lockedPricing": true, "pauseLevel": 0, "priceProviderCooldownSecs": 18446744073709551615, "depositWhitelistingEnabled": false, "createdBlockNumber": 25984907, "createdTimestamp": 1789499963, "priceProviderSinceBlock": 25984907, "extensions": [ "0x599b0027942fC98BadC121cB789fE0D4a11A0879", "0xE4038fA09f0bB9963068afaF97BE0c045155090D", "0xEbc53e61078976118E384f110c262A263decB84B" ], "extensionDetails": { "stopLoss": { "phases": ["afterSwap"], "drawdownE6": "150000", "decayPerSecondE18": "1736111111111", "timelockSecs": "3600" }, "priceVelocity": { "phases": ["beforeSwap"], "maxChangePerBlockE18": "100000000000000000" } }, "classificationSummary": { "tierQualification": "red", "reasonCodes": ["stop_loss_mutable"] }, "poolFactoryAddress": "0x2a53833cc95548cf52c7b159110e22D3a9018f32", "poolDeployerAddress": "0x2E0A99A2E352043d1CA489cF45bf7B511BCcC738", "liquidityAdderAddress": "0x06Cb6C245Cd9219262442A7730D9484B3CfdD901", "dataProviderAddress": "0x83d66c5934b1525ee82e6E772c76c7acC778bBB7", "depositAllowlistAddress": "0x65FBa4Ee8f50772aB384f19e5520DdA420B1B47D", "oracleValueStopLossAddress": "0xE4038fA09f0bB9963068afaF97BE0c045155090D", "priceVelocityGuardAddress": "0xEbc53e61078976118E384f110c262A263decB84B", "quoterAddress": "0x3B9ea79f482094323d06064E637a7F4528560fcb", "priceProviderStatus": "healthy" } ], "total": 9, "nextOffset": 1 } ``` {% hint style="warning" %} `priceProviderCooldownSecs` can be `18446744073709551615` (2^64 − 1), which is larger than JavaScript's `Number.MAX_SAFE_INTEGER`. `JSON.parse` silently rounds it to `18446744073709552000`. Parse it as a BigInt, or treat any value ≥ 2^53 as "never". {% endhint %} ### Pool fields #### Identity | Field | Type | Description | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `pair` | string | Display pair, `token0Symbol/token1Symbol`. | | `chain` | string | Chain name as returned by `GET /public/v1/chains`. Casing varies by chain (`ethereum`, `BSC`, `Robinhood`); key on the chain ID, not this string. | | `contractVersion` | string | Contract release, currently `v1`. | | `poolAddress` | address | The pool. | | `createdBlockNumber` | integer | Block the pool was created in. | | `createdTimestamp` | integer | Unix seconds of that block. | #### Tokens | Field | Type | Description | | -------------------------------------- | -------------- | ------------------------------------------------------------- | | `token0`, `token1` | address | Pool tokens, in pool order. | | `token0Symbol`, `token1Symbol` | string | ERC-20 symbols. Optional. | | `token0Name`, `token1Name` | string | ERC-20 names. Optional. | | `token0Decimals`, `token1Decimals` | integer | ERC-20 decimals. Optional. | | `token0LogoUrl`, `token1LogoUrl` | string | Token logo URL. Optional. | | `token0BrandColor`, `token1BrandColor` | string | Hex color for UI use. Optional. | | `token0FiatPrice`, `token1FiatPrice` | number \| null | USD price. Always present; `null` when no price is available. | #### Price provider | Field | Type | Description | | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `priceProviderAddress` | address | The pool's active Price Provider. | | `priceProviderDetails` | object | Provider configuration. Optional: omitted when the provider wasn't deployed by a Metric provider factory, or its type isn't recognized. See below. | | `priceProviderStatus` | string | Current health of the pool's price, from the last price capture. See [Price provider status](#price-provider-status) below. | | `priceProviderSinceBlock` | integer | Block since which the current provider has been active. | | `priceProviderCooldownSecs` | integer | Cooldown on changing the pool's provider. `2^64 − 1` means it can never be changed (see the warning above). | | `lockedPricing` | boolean | `true` when the provider can never be changed. | | `priceProviderChange` | object | Pending provider change. Optional: present only while one exists. | `priceProviderDetails` for an **anchored** provider (`providerType: "anchored"`): `oracle`, `feedMode` (`single` or `synthetic`), `source`, `marginStep`, `minMargin`, `maxRefStaleness`, `maxSpreadMult`, `mutableParams`, `confidenceParam`, `baseMaxStaleness`, `quoteMaxStaleness`, `baseSpreadMult`, `quoteSpreadMult`. For a **regular** provider (`providerType: "regular"`): `oracle`, `marginStep`, `maxTimeDelta`, `confidenceParam`. Numeric values inside `priceProviderDetails` are decimal strings, and any of them may be `null`. `marginStep` is signed and can be negative. `source` is omitted when the provider has no custom source (reference mode). #### Price provider status | Value | Meaning | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `healthy` | The provider returned a usable price. | | `feed_down` | The feed has no valid price right now. | | `pool_refused` | The feed quoted, but the pool refuses to trade on that quote. | | `pool_paused` | The pool is paused and its price read otherwise succeeded. A paused pool whose feed is down shows `feed_down`; check `pauseLevel` to detect a pause. | | `unknown` | No recent reading for this pool. | Only `healthy` means the pool is quotable. For a live check before trading, use [bid and ask](/reference/api/retrieve-current-bid-and-ask.md). #### Curator and fees | Field | Type | Description | | ----------------------- | --------------- | ------------------------------------------------ | | `creator` | address | Address that created the pool. | | `admin` | address | Current pool admin (curator). Optional. | | `adminUsername` | string \| null | Curator's display name; `null` when none is set. | | `verifiedAdmin` | boolean | Whether the curator is verified by Metric. | | `adminFeeDestination` | address | Where curator fees are paid. | | `spreadProtocolFeeE6` | integer \| null | Protocol share of the spread, 1e6 = 100%. | | `spreadAdminFeeE6` | integer \| null | Curator share of the spread, 1e6 = 100%. | | `protocolNotionalFeeE8` | integer \| null | Protocol fee on notional, 1e8 = 100%. | | `adminNotionalFeeE8` | integer \| null | Curator fee on notional, 1e8 = 100%. | | `aprBps7d` | integer | Trailing 7-day LP APR in basis points. Optional. | The fee fields mirror the onchain `poolFeeConfig(pool)` on `MetricOmmPoolFactory`. For a pool not listed here (e.g. before it is funded), read that onchain. #### State and access | Field | Type | Description | | ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pauseLevel` | integer | `0` = active. Any other value blocks swaps. Optional. | | `curBinIdx` | integer | The pool's current active bin. Can be negative. A position is in range when it holds shares in this bin. Returned with or without `include24h`. Optional. | | `depositWhitelistingEnabled` | boolean | Deposits are restricted to an allowlist. | | `depositAllowlistProvider` | address | Allowlist that gates deposits. Optional: present only when `depositWhitelistingEnabled` is `true`. | #### Extensions and classification | Field | Type | Description | | ----------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `extensions` | address\[] | Every extension attached to the pool, including custom ones. | | `extensionDetails` | object | Parameters of the standard extensions the pool uses: `stopLoss` (`drawdownE6`, `decayPerSecondE18`, `timelockSecs`) and `priceVelocity` (`maxChangePerBlockE18`). Each lists the swap `phases` it runs in. Values are decimal strings or `null`. Optional. | | `classificationSummary.tierQualification` | string | `green`, `yellow` or `red`; `unclassified` when the pool hasn't been classified yet; `black` for a pool delisted by Metric (returned only with `blacklistedOnly=true`). | | `classificationSummary.reasonCodes` | string\[] | Why the pool is not green. Empty for green pools. See [Reason codes](#reason-codes) below. | #### Reason codes | Code | Meaning | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `bin_width_exceeded` | Bins are wider than 1%. | | `stop_loss_missing` | No StopLoss extension attached. | | `stop_loss_uninitialized` | A StopLoss is attached but not initialized. | | `stop_loss_mutable` | The StopLoss settings can still be changed. | | `stop_loss_drawdown_exceeded` | StopLoss drawdown is above 15%. | | `stop_loss_decay_exceeded` | StopLoss decay is above 15% per day. | | `app_missing` | The Price Provider is not an Anchored Price Provider. | | `app_mutable` | The Anchored Price Provider's parameters can be changed. | | `feed_staleness_exceeded` | A feed's staleness bound is above 15 seconds. | | `price_provider_mutable` | The pool's Price Provider can be changed. | | `curator_unverified` | The curator is not verified by Metric. | | `curator_not_creator` | The curator is not the pool's creator. | | `remove_liquidity_extension_present` | An extension runs when liquidity is removed. | | `anchored_feed_unmatched` | The Anchored Price Provider's feeds can't be confirmed to price the pool's own tokens. | | `multiplier_feed_miswired` | A Multiplier Oracle feed is bound to the wrong token or feed, uses an adapter that can't read the token, or skips the multiplier. | | `multiplier_token_unscaled` | A tokenized stock with an issuer multiplier is priced by an oracle other than the Multiplier Oracle. | | `reference_source_unrecognized`, `external_source_unreviewed` | Reserved. Not emitted yet. | `anchored_feed_unmatched` drops the pool one tier. `multiplier_feed_miswired` and `multiplier_token_unscaled` make it `red` whatever else it meets. See [Pool tiers](/use-metric/provide-and-manage-liquidity/pool-tiers.md#tokenized-stocks). #### Contract addresses `poolFactoryAddress`, `poolDeployerAddress`, `liquidityAdderAddress`, `dataProviderAddress`, `quoterAddress`, `depositAllowlistAddress`, `oracleValueStopLossAddress` and `priceVelocityGuardAddress` echo the deployment the pool belongs to. See [Deployments](/reference/supported-chains-and-deployments.md). #### 24h analytics (`include24h=true` only) | Field | Type | Description | | -------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `tvlFiat` | number | Pool TVL in USD (same value as `analytics24h.tvlFiat`). | | `analytics24h.fromTs` / `toTs` / `generatedAtTs` | integer | Window bounds and generation time, Unix seconds. | | `analytics24h.fromBlock` / `toBlock` | integer | Block range of the window. | | `analytics24h.swapTxCount`, `transfers` | integer | Swap and transfer counts in the window. | | `analytics24h.liquidityEventCount`, `liquidityAddEventCount`, `liquidityRemoveEventCount` | integer | Liquidity events in the window. | | `analytics24h.token0` / `token1` | object | Per token: `liquidityRaw`, `volumeRaw`, `inflowRaw`, `outflowRaw`, `netRaw` (raw token units, decimal strings) and the matching `…Fiat` values in USD. | | `analytics24h.volumeFiat`, `feesFiat`, `tvlFiat` | number \| null | 24h volume, 24h fees and current TVL, USD. | | `analytics24h.aprBps` | integer \| null | APR from the last 24h, basis points. | | `analytics24h.fiatAvailable`, `fiatStatus`, `fiatCurrency`, `fiatCoveragePct`, `pricingMode`, `usdCoveragePct` | mixed | How the fiat values were priced. | ### Omitted vs null Optional fields are omitted entirely when absent; they are not returned as `null`. These optional fields are: `token0Symbol`, `token0Name` and `token0Decimals` (and their `token1` counterparts), logo and color fields, `admin`, `aprBps7d`, `pauseLevel`, `priceProviderDetails`, `priceProviderDetails.source`, `priceProviderChange`, `depositAllowlistProvider`, `extensionDetails`, `curBinIdx`, and `tvlFiat` / `analytics24h` (only with `include24h=true`). These fields are always present and may be `null`: `token0FiatPrice`, `token1FiatPrice`, `adminUsername`, the four fee fields (`spreadProtocolFeeE6`, `spreadAdminFeeE6`, `protocolNotionalFeeE8`, `adminNotionalFeeE8`), every numeric value inside `priceProviderDetails` and `extensionDetails`, and the fiat values in `analytics24h` (`aprBps`, `feesFiat`, `tvlFiat`, `volumeFiat`, `fiatCoveragePct` and each token's `…Fiat` values). ### Errors | Status | When | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Non-numeric `chain_id`, unsupported `sortBy`, `sortOrder`, `tier` or `fiat`, negative `count`, or `include24h` other than `true`/`false`. | | `404` | `chain_id` is not served by the API (`{"error": "Unknown chainId: "}`), or `contract_version` is unknown or disabled. | Most error bodies are JSON `{"error": "…"}`. A query parameter that can't be parsed at all (e.g. `count=abc`, `include24h=yes`) returns a plain-text body instead, such as `Failed to deserialize query string: …`. Examples use the Ethereum WETH/USDC pool. Other pairs returned by this endpoint use the same conventions.