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

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

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

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

### Example

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

```graphql theme={null}
{
  liquidityLocks(
    pairAddress: "PAIR_ADDRESS"
    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`](https://docs.codex.io/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

> [accordion] 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] 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] 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] 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`](https://docs.codex.io/api-reference/queries/liquiditylocksv2) returns `lockedPercent` from a single current on-chain read instead.

> [accordion] 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`](https://docs.codex.io/api-reference/queries/liquiditylocksv2), which reads the locker's current registry, hook custody, or lock accounts directly.


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