> ## 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. Reference for the liquidityLocks query in the Codex API: arguments, response fields, and usage.

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

  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>

<Warning>
  `liquidityLocks` is deprecated and retiring with the legacy event-derived lock pipeline. Use [`liquidityLocksV2`](/api-reference/queries/liquiditylocksv2), which reads lock state from the chain right now, matures vesting at read time, and returns `lockedPercent` directly.
</Warning>

### 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; see [`LiquidityLockProtocol`](/api-reference/enums/liquiditylockprotocol) for every value and what it covers
* `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`. Because this query is event-derived, expired or withdrawn locks can still appear in `items`, so the sum can overstate what is locked today. [`liquidityLocksV2`](/api-reference/queries/liquiditylocksv2) returns `lockedPercent` from a single current on-chain read instead.
  </Accordion>

  <Accordion title="Why does this query still show a lock that expired or was withdrawn?">
    `liquidityLocks` only knows about a lock from the transaction that created it and does not re-check it afterwards. Locks created before Codex indexed a protocol are also missing. Both are fixed in [`liquidityLocksV2`](/api-reference/queries/liquiditylocksv2), which reads the locker's current registry, hook custody, or lock accounts directly.
  </Accordion>
</AccordionGroup>


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