# Look up provision NFTs

`POST /dex/provisions/nft` · Lithos client API · Lithos Dex

Source: https://lithosprotocol.org/docs/api/lookup-ld-provision-nfts

Which of up to 100 tokens own a provision on a listed LithosDex pool, of either kind. A deposit's NFT has the id of the pool box the deposit spent, so a token is checked against that box first; a pool creator's NFT is named by the pool's genesis. The pool's provisions are read once for every token naming it. Each token comes back once, with `provisionNft` false when it owns none. When it owns one, the answer carries the pool, the provision, its share of the reserves now and how it was minted. A `redeemed` token owned a provision since closed. Answers hold for one block: a second request at the same tip reads nothing from the node. Open, so it can check tokens held anywhere.

## Request body

`LDNftLookupRequest`, application/json.

- `tokenIds` (string[], required)

## Responses

### 200: One entry per distinct token id, in lower case

`LDNftLookupList`

- `nfts` (LDNftLookup[], required)
  - `tokenId` (string, required)
  - `provisionNft` (boolean, required): Whether this token owns a provision on a listed pool
  - `pool` (LDPoolSummary): One LithosDex pool as the index last read it. Amounts are decimal strings in base units.
    - `poolNFT` (string, required)
    - `kind` (string, required, one of n2t, t2t): `n2t` is ERG against a token, `t2t` token against token
    - `utxoId` (string, required): The pool box the index read
    - `inclusionHeight` (integer · int32, required)
    - `tokenX` (LDPoolToken, required): One side of a pool. A verified token's name, ticker and decimals come from the client's verified list; any other token's from the node's token index, where whoever minted the token chose them. 
      - `tokenId` (string, required): Token id, or `ERG` for the X side of an ERG/token pool
      - `name` (string)
      - `ticker` (string): Short symbol. Verified tokens and ERG only.
      - `decimals` (integer · int32)
      - `verified` (boolean, required)
    - `tokenY` (LDPoolToken, required): One side of a pool. A verified token's name, ticker and decimals come from the client's verified list; any other token's from the node's token index, where whoever minted the token chose them. 
    - `reservesX` (string, required)
    - `reservesY` (string, required)
    - `pendingX` (string, required): Fees awaiting a flush to the vault
    - `pendingY` (string, required)
    - `supply` (string, required): Shares issued
    - `feeParams` (LDFeeParams, required): Fee numerators over `feeDenom`. `dexFeeNum` stays in the pool; `ergFeeNum` / `tokenFeeNum` are set aside for liquidity providers. 
      - `dexFeeNum` (integer · int64, required)
      - `ergFeeNum` (integer · int64, required)
      - `tokenFeeNum` (integer · int64, required)
      - `feeDenom` (integer · int64, required): Denominator of every numerator above
    - `provTokensLeft` (string, required): Deposits the pool can still take, one provision token each
    - `price` (number · double): Units of Y per unit of X at display decimals. Absent when either side's decimals are unknown.
    - `verified` (boolean, required): Whether the client's verified list names this pool
    - `genesisChecked` (boolean, required): Whether this pool's genesis was checked. False for verified pools, which are checked by hand, and while the node could not be read. 
    - `problems` (string[], required): Genesis facts this pool breaks. Any one can let the pool be drained.
    - `warnings` (string[], required): Risks short of that, such as too little ERG to survive storage rent.
  - `provision` (LDProvision): A liquidity provision box, with both what it has earned and what it can currently be paid. 
    - `boxId` (string, required): Provision box id. Changes on every claim and resize.
    - `ownerNFT` (string, required): Token that owns this provision. Unchanged by claims and resizes.
    - `shares` (string, required): LP shares this provision represents. Decimal string.
    - `entryX` (string, required): Accumulator this provision last settled at. Decimal string.
    - `entryY` (string, required): Token side of the same. Decimal string.
    - `value` (string, required): nanoERG held by the provision box. Decimal string.
    - `createdHeight` (integer · int32, required)
    - `shareOfSupply` (number · double, required)
    - `accruedX` (string, required): ERG earned according to the pool, including fees not yet flushed. This is the figure to show a provider as "earned". Decimal string. 
    - `accruedY` (string, required): Token side of the same. Decimal string.
    - `claimableX` (string, required): ERG that can be paid out now. Never negative. Decimal string.
    - `claimableY` (string, required): Token side of the same. Decimal string.
    - `unflushedX` (string, required): accruedX less claimableX — what a flush would release. Decimal string.
    - `unflushedY` (string, required): Token side of the same. Decimal string.
    - `canClaim` (boolean, required): Whether a claim would be accepted right now.
    - `awaitingFlush` (boolean, required): True when nothing can be claimed until the next flush. Normal after a deposit or resize; not an error. 
    - `redeemOrderBoxId` (string): Present when an outstanding redeem order holds this provision's `ownerNFT`. The provision cannot be claimed, resized or redeemed directly until that order fills or is cancelled. 
  - `amountX` (string): The provision's share of the pool's X reserve now. nanoERG for an ERG/token pool.
  - `amountY` (string): The provision's share of the pool's Y reserve now
  - `redeemed` (boolean): The token owned a provision on this pool that has since been closed
  - `minted` (LDNftMint): How a provision NFT was minted: by a deposit, or by its pool's genesis for the pool's creator
    - `height` (integer, required)
    - `shares` (string, required): Shares the provision was created with
    - `amountX` (string, required): What went in on the X side, nanoERG for an ERG/token pool. For a genesis, the whole reserve, a millionth of which stays locked
    - `amountY` (string, required)
    - `genesis` (boolean, required)
  - `lastClaimedHeight` (integer): The block that last recreated the provision with moved entries, by a claim or a resize. Absent while it has never been claimed. A refresh keeps the entries but recreates the box, so after one this is the refresh's block. 
  - `refreshBountyNanoErg` (string): Token/token provisions only: what a refresh may take from the provision box's ERG now
  - `refreshableHeight` (integer): The first block anyone may refresh the provision box, renewing its age before storage rent

### 400: The request is malformed, names more than 100 tokens, or has an id that is not 64 hex characters.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### 503: The pool index is still building, the node is unavailable, or a pool has more provisions than one scan reads. Never returns a partial answer.

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

### default: Error

`ApiError`

- `error` (integer, required): Error code
- `reason` (string, required): Error message explaining the reason of the error
- `detail` (string, required): Detailed error description

## Example request

```bash
curl -X POST "http://localhost:9000/dex/provisions/nft" \
  -H "Content-Type: application/json" \
  -d '{ "tokenIds": [ "88c297f99da7172f6aa20efbead69aa40e2b7734a1873d66ca1db6b19d214db6" ] }'
```

## Example response

```json
{
  "nfts": [
    {
      "tokenId": "string",
      "provisionNft": true,
      "pool": {
        "poolNFT": "string",
        "kind": "n2t",
        "utxoId": "string",
        "inclusionHeight": 0,
        "tokenX": {
          "tokenId": "c1980d829988229516430a47a5eca376060b6ce859616db0936e78ab25cb6de7",
          "name": "LIT",
          "ticker": "LIT",
          "decimals": 9,
          "verified": true
        },
        "tokenY": {
          "tokenId": "c1980d829988229516430a47a5eca376060b6ce859616db0936e78ab25cb6de7",
          "name": "LIT",
          "ticker": "LIT",
          "decimals": 9,
          "verified": true
        },
        "reservesX": "string",
        "reservesY": "string",
        "pendingX": "string",
        "pendingY": "string",
        "supply": "string",
        "feeParams": {
          "dexFeeNum": 9985,
          "ergFeeNum": 15,
          "tokenFeeNum": 15,
          "feeDenom": 10000
        },
        "provTokensLeft": "string",
        "price": 0.1,
        "verified": true,
        "genesisChecked": true,
        "problems": [
          "string"
        ],
        "warnings": [
          "string"
        ]
      },
      "provision": {
        "boxId": "ce00d6e0f4fd3390c0519bb0d24824e1e6b06978163f4845a7cf2c1c7d8f1b65",
        "ownerNFT": "a1f4c2e8b7d93052416fbc8e07d21935a8c4f60b2e91d7385c06a4b1f2e83d97",
        "shares": "12500000000",
        "entryX": "18400000000000000000000000",
        "entryY": "552000000000000000000000",
        "value": "600000000",
        "createdHeight": 1284400,
        "shareOfSupply": 0.0125,
        "accruedX": "292750000",
        "accruedY": "8900000",
        "claimableX": "253000000",
        "claimableY": "7690000",
        "unflushedX": "39750000",
        "unflushedY": "1210000",
        "canClaim": true,
        "awaitingFlush": false,
        "redeemOrderBoxId": "9b41d2f07ce83a5164e2d09fb7a3c1586e04d9b2f71ac8356e0b4d1c7f29a3e5"
      },
      "amountX": "string",
      "amountY": "string",
      "redeemed": true,
      "minted": {
        "height": 0,
        "shares": "string",
        "amountX": "string",
        "amountY": "string",
        "genesis": true
      },
      "lastClaimedHeight": 0,
      "refreshBountyNanoErg": "string",
      "refreshableHeight": 0
    }
  ]
}
```