> ## 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
  }

  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>
  We support lock info on UniV3, UniV4, RaydiumV4, PumpAMM, and token burns on Solana.
</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)
* `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?">
    We track liquidity locked via UNCX\_V2, UNCX\_V3, BASECAMP\_V1, BITBOND, METEORA\_DAMM\_V2, and BURN (burned LP tokens). Support includes UniV3, UniV4, RaydiumV4, PumpAMM, and Solana token burns.
  </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 simply means the liquidity can be removed by LP providers.
  </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>