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

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

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]!
}
```

### Example

[Test this query in the Explorer →](https://docs.codex.io/explore.md)

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

> [!NOTE]
>
> 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](https://docs.codex.io/api-reference/queries/liquiditylocksv2.md#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`](https://docs.codex.io/api-reference/queries/liquiditylocksv2) with `tokenAddress`.

### 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`](https://docs.codex.io/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

> [accordion] 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] 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`](https://docs.codex.io/api-reference/enums/liquiditylockprotocol) for each value and the [coverage table](https://docs.codex.io/api-reference/queries/liquiditylocksv2.md#coverage) for the full list.

> [accordion] 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] 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] 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.


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