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

# liquidityMetadataByToken

> Returns liquidity metadata for a given token. Includes liquidity lock data for up to 100 pairs that the token is in.

<div data-generated>
  ## GraphQL

  ```
  type Query {
    # Requires a Growth or Enterprise plan.
    liquidityMetadataByToken(
      tokenAddress: String!
      networkId: Int!
    ): LiquidityMetadataByToken!
  }

  enum LiquidityLockProtocol {
    BASECAMP_V1
    UNCX_V2
    UNCX_V3
    BURN
    BITBOND
    METEORA_DAMM_V2
    DOPPLER
    O1_EXCHANGE
    MINARA
    PONS_V2
    METAPLEX_GENESIS
    PINKSALE
    TEAM_FINANCE
    LAUNCH_FAIR
    BAGS
    RAYDIUM_LOCK
    LETSCASH
    PAIR
    LAUNCH_HOOK
    LUNCH_FUN
    LAUNCH_TAX_HOOK
    PEACH
    FOCI
    LIFT
    LONG_SUPPLY
    TOLLY
  }

  type LiquidityLockBreakdownForToken {
    lockProtocol: LiquidityLockProtocol!
    amountLockedUsd: String!
    amountLockedTokens: String!
    amountLockedTokensShifted: String!
  }

  type LiquidityMetadataByToken {
    tokenAddress: String!
    networkId: Int!
    totalLiquidityUsd: String!
    lockedLiquidityUsd: String!
    totalTokenLiquidity: String!
    totalTokenLiquidityShifted: String!
    lockedTokenLiquidity: String!
    lockedTokenLiquidityShifted: String!
    lockedLiquidityPercentage: Float!
    lockBreakdown: [LiquidityLockBreakdownForToken]!
  }
  ```
</div>

### Example

<a href="/explore" target="_blank" rel="noopener noreferrer">Test this query in the Explorer →</a>

```graphql theme={null}
{
  liquidityMetadataByToken(
    tokenAddress: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
    networkId: 1
  ) {
    tokenAddress
    networkId
    totalLiquidityUsd
    lockedLiquidityUsd
    totalTokenLiquidity
    totalTokenLiquidityShifted
    lockedTokenLiquidity
    lockedTokenLiquidityShifted
    lockedLiquidityPercentage
    lockBreakdown {
      lockProtocol
      amountLockedUsd
      amountLockedTokens
      amountLockedTokensShifted
    }
  }
}
```

<Info>
  Lock tracking covers all major EVM networks and Solana, gated by the lock mechanism a pool uses: burned LP, locker vaults such as UNCX, PinkSale and Team Finance, Uniswap V4 launch-hook custody on Robinhood Chain and Base, and position-state locks on Meteora DAMM v2, Orca and Raydium CLMM. See the [coverage table](/api-reference/queries/liquiditylocksv2#coverage) for the full list. For per-pair lock state read from the chain right now, with vesting matured and per-holder attribution, use [`liquidityLocksV2`](/api-reference/queries/liquiditylocksv2) with `tokenAddress`.
</Info>

### Usage Guidelines

* Query using `tokenAddress` (contract address) and `networkId` (chain ID)
* `lockedLiquidityPercentage` is a value between 0 and 1 (e.g., 0.5 = 50% locked). Note that `lockedPercent` on [`liquidityLocksV2`](/api-reference/queries/liquiditylocksv2) is 0–100
* `lockBreakdown` shows how liquidity is distributed across different lock protocols
* Use `totalTokenLiquidityShifted` and `lockedTokenLiquidityShifted` for human-readable token amounts (adjusted for decimals)
* Liquidity data is aggregated across up to 100 pairs containing the token

### Troubleshooting Tips

<AccordionGroup>
  <Accordion title="When should I use liquidityMetadataByToken vs liquidityMetadata?">
    Use `liquidityMetadataByToken` when you want aggregated liquidity data across all pairs containing a token (up to 100 pairs), including total locked percentage and USD values. Use `liquidityMetadata` when you have a specific pair and want detailed lock info for that pool only.
  </Accordion>

  <Accordion title="What lock protocols are supported?">
    Burned LP (`BURN`) on Uniswap V2-style pools, Pump.fun graduated pools and Raydium V4 across every network; locker vaults (`UNCX_V2`, `UNCX_V3`, `PINKSALE`, `TEAM_FINANCE`); Uniswap V4 launch-hook custody on Robinhood Chain and Base (`DOPPLER`, `PONS_V2`, `O1_EXCHANGE`, `BAGS`, `LAUNCH_FAIR`, plus hooks attributed by name only); position-state locks on Meteora DAMM v2, Orca Whirlpools and Raydium CLMM; and `METAPLEX_GENESIS` vesting buckets. See [`LiquidityLockProtocol`](/api-reference/enums/liquiditylockprotocol) for each value and the [coverage table](/api-reference/queries/liquiditylocksv2#coverage) for the full list.
  </Accordion>

  <Accordion title="Why is lockedLiquidityPercentage 0?">
    Not all tokens have locked liquidity. Many tokens, especially older or larger ones like WETH, may have unlocked liquidity. A 0% locked percentage means the liquidity can be removed by LP providers. It also reads 0 when the pool's custodian is one Codex has not verified (a team multisig, an upgradeable lock contract, or a launchpad hook not yet registered), or when the "lock" is a token burn rather than a liquidity lock. Codex reports a lock only when it can prove it on chain. If a locker or launchpad you rely on is missing, [let us know](mailto:hello@codex.io?subject=Liquidity%20Lock%20Coverage) with the pool address.
  </Accordion>

  <Accordion title="What's the difference between totalTokenLiquidity and totalTokenLiquidityShifted?">
    `totalTokenLiquidity` is the raw token amount. `totalTokenLiquidityShifted` divides by the token's decimals for a human-readable value. For example, if a token has 18 decimals, 1000000000000000000 raw becomes 1.0 shifted.
  </Accordion>

  <Accordion title="Why might liquidity data be incomplete?">
    We track liquidity across up to 100 pairs per token. Tokens with more pairs may have partial data. Also, some lock protocols or DEXs may not be supported yet.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.