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

# liquidityLocks

> Returns liquidity locks for a given pair.

<div data-generated>
  ## GraphQL

  ```
  type Query {
    # Requires a Growth or Enterprise plan.
    liquidityLocks(
      pairAddress: String
      tokenAddress: String
      networkId: Int!
      cursor: String
    ): LiquidityLockConnection
  }

  enum LiquidityLockProtocol {
    BASECAMP_V1
    UNCX_V2
    UNCX_V3
    BURN
    BITBOND
    METEORA_DAMM_V2
    DOPPLER
    O1_EXCHANGE
    PONS_V2
  }

  enum LiquidityProtocol {
    UNISWAP_V3
    UNISWAP_V2
    RAYDIUM_V4
    PUMP_V1
    USE_LIQUIDITY_PROTOCOL_V2
  }

  type LiquidityNftData {
    nftTokenId: String!
    nftPositionManagerAddress: String!
  }

  type LiquidityLock {
    pairAddress: String!
    networkId: Int!
    ownerAddress: String!
    lockerAddress: String!
    createdAt: Int!
    unlockAt: Int
    lockProtocol: LiquidityLockProtocol!
    liquidityProtocolV2: String!
    liquidityAmount: String!
    initialAmountToken0: String!
    initialAmountToken1: String!
    liquidityNftData: LiquidityNftData
  }

  type PairLiquidityData {
    pairId: String!
    pairAddress: String!
    networkId: Int!
    totalLiquidity: String!
  }

  type LiquidityLockConnection {
    items: [LiquidityLock!]!
    cursor: String
    pairLiquidityData: [PairLiquidityData!]!
  }
  ```
</div>

### Example

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

```graphql theme={null}
{
  liquidityLocks(
    pairAddress: "8WwcNqdZjCY5Pt7AkhupAFknV2txca9sq6YBkGzLbvdt"
    networkId: 1399811149
  ) {
    items {
      pairAddress
      networkId
      ownerAddress
      lockerAddress
      createdAt
      unlockAt
      lockProtocol
      liquidityProtocolV2
      liquidityAmount
      initialAmountToken0
      initialAmountToken1
    }
    pairLiquidityData {
      pairAddress
      networkId
      totalLiquidity
    }
  }
}
```

### Usage Guidelines

* Query by `pairAddress` to get all locks for a specific trading pair, or by `tokenAddress` to get locks across all pairs containing that token
* `networkId` is required — specify the chain (e.g., `1399811149` for Solana, `1` for Ethereum)
* Each lock includes `ownerAddress` (who created the lock), `lockerAddress` (the locker contract), and timing info (`createdAt`, `unlockAt`)
* `lockProtocol` indicates the locking mechanism: `BURN`, `UNCX_V2`, `UNCX_V3`, `BASECAMP_V1`, `BITBOND`, `METEORA_DAMM_V2`
* `pairLiquidityData` provides `totalLiquidity` for each pair — sum `liquidityAmount` from items to get total locked
* Use `cursor` for pagination when there are many lock records

### Troubleshooting Tips

<AccordionGroup>
  <Accordion title="What's the difference between liquidityLocks and liquidityMetadata?">
    `liquidityLocks` returns individual lock records with details like owner, unlock time, and amounts. `liquidityMetadata` returns aggregated lock data (total locked vs total liquidity) without individual lock details. Use `liquidityLocks` when you need to display a list of locks or check specific unlock dates.
  </Accordion>

  <Accordion title="What does unlockAt: null mean?">
    When `unlockAt` is null, the liquidity is permanently locked. This typically happens with `BURN` locks where LP tokens are sent to a burn address, or locks created without an expiration. These locks cannot be withdrawn.
  </Accordion>

  <Accordion title="What is liquidityNftData?">
    For concentrated liquidity pools (UniV3, Orca Whirlpool), liquidity positions are represented as NFTs. `liquidityNftData` contains the `nftTokenId` and `nftPositionManagerAddress` for these positions. It's null for traditional LP token locks.
  </Accordion>

  <Accordion title="How do I calculate locked percentage?">
    Sum the `liquidityAmount` from all items to get total locked liquidity, then divide by `totalLiquidity` from `pairLiquidityData`: `lockedPercentage = sumOfLiquidityAmounts / totalLiquidity * 100`.
  </Accordion>
</AccordionGroup>