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

# liquidityMetadata

> Returns liquidity metadata for a given pair. Includes liquidity lock data. liquidityMetadata query reference: arguments and response fields.

## GraphQL

```
type Query {
  # Requires a Growth or Enterprise plan.
  liquidityMetadata(
    pairAddress: String!
    networkId: Int!
  ): LiquidityMetadata
}

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 LockBreakdown {
  lockProtocol: LiquidityLockProtocol!
  active: String!
  inactive: String!
}

type LockedLiquidityData {
  active: String!
  inactive: String!
  lockBreakdown: [LockBreakdown]!
}

type LiquidityData {
  active: String!
  inactive: String!
}

type LiquidityMetadata {
  lockedLiquidity: LockedLiquidityData!
  liquidity: LiquidityData!
}
```

> [!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 a `lockedPercent`, use [`liquidityLocksV2`](https://docs.codex.io/api-reference/queries/liquiditylocksv2).

### Example

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

```graphql theme={null}
{
  liquidityMetadata(
    pairAddress: "PAIR_ADDRESS"
    networkId: 1399811149
  ) {
    lockedLiquidity {
      active
      inactive
      lockBreakdown {
        lockProtocol
        active
        inactive
      }
    }
    liquidity {
      active
      inactive
    }
  }
}
```

### Usage Guidelines

* Provide `pairAddress` and `networkId` to get liquidity and lock metadata for a specific trading pair
* `liquidity` returns total `active` and `inactive` liquidity amounts in the pair
* `lockedLiquidity` shows how much liquidity is locked, with a `lockBreakdown` by protocol
* `lockProtocol` is a [`LiquidityLockProtocol`](https://docs.codex.io/api-reference/enums/liquiditylockprotocol) value, for example `BURN` (burned LP tokens), `UNCX_V2`, `UNCX_V3`, `PINKSALE`, `TEAM_FINANCE`, `METEORA_DAMM_V2`, `METAPLEX_GENESIS`, or a launch hook such as `DOPPLER`, `PONS_V2`, `O1_EXCHANGE`, `BAGS` and `LAUNCH_FAIR`
* For token-level aggregated lock data across all pairs, use `liquidityMetadataByToken` instead
* Active vs inactive liquidity: in concentrated liquidity pools (UniV3, Orca Whirlpool), liquidity outside the current price range is "inactive"

### Troubleshooting Tips

> [accordion] What's the difference between active and inactive liquidity?
>
> In concentrated liquidity pools, liquidity providers choose price ranges. `active` liquidity is within the current trading range and earns fees. `inactive` liquidity is outside the current range and doesn't participate in trades until the price moves into its range. For constant-product AMMs, all liquidity is typically "active".

> [accordion] What do the lock protocols mean?
>
> `BURN` means LP tokens were sent to a burn address (permanently locked). `UNCX_V2`/`UNCX_V3`, `PINKSALE` and `TEAM_FINANCE` are locker vaults that publish an unlock date per deposit. `DOPPLER`, `PONS_V2`, `O1_EXCHANGE`, `BAGS` and `LAUNCH_FAIR` are launchpads whose Uniswap V4 hook holds the pool position with no withdraw path. `METEORA_DAMM_V2` is a position-state lock on Solana, and `METAPLEX_GENESIS` is a vesting launch bucket. The [`LiquidityLockProtocol`](https://docs.codex.io/api-reference/enums/liquiditylockprotocol) page describes each value. Locked liquidity indicates developer commitment and reduces rug-pull risk.

> [accordion] When should I use liquidityMetadata vs liquidityMetadataByToken?
>
> Use `liquidityMetadata` when you have a specific pair and want detailed lock info for that pool. 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.

> [accordion] Why is lockBreakdown empty for some pairs?
>
> Not all pairs have locked liquidity. If no LP tokens have been burned or locked via a supported protocol, `lockBreakdown` will be an empty array. This is normal for many pairs — locked liquidity is a trust signal, not a requirement. It is also empty when the pool's custodian is one Codex has not verified (for example a team multisig or an unregistered launchpad hook): Codex reports a lock only when it can prove it on chain, so an unverified lock reads as unlocked. 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.


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