### Fetch NFTs on Sale with Cursor

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Example of fetching NFTs on sale using a cursor for pagination. Requires an API key for authorization.

```bash
curl -X GET \
  'https://api.getgems.io/public-api/v1/nfts/on-sale/EQCA14o1-VWhS2efqoh_9M1b_A9DtKTuoqfmkn83AbJzwnPi?cursor=5.7%2C6813a6976428bb255010d739' \
  -H 'Authorization: Bearer MY_API_KEY'
```

--------------------------------

### Verify SBT Contract Example

Source: https://github.com/getgems-io/nft-contracts/blob/main/sbt.md

An example of an SBT contract written in C (TON's smart contract language). It includes functions for loading data, calculating SBT addresses, and handling internal messages, specifically the `ownership_proof` operation.

```cpp
int op::ownership_proof() asm "0x0524c7ae PUSHINT";

int equal_slices (slice a, slice b) asm "SDEQ";

_ load_data() {
    slice ds = get_data().begin_parse();

    return (
        ds~load_msg_addr(),    ;; collection_addr
        ds~load_ref()          ;; sbt_code
    );
}

slice calculate_sbt_address(slice collection_addr, cell sbt_item_code, int wc, int index) {
  cell data = begin_cell().store_uint(index, 64).store_slice(collection_addr).end_cell();
  cell state_init = begin_cell().store_uint(0, 2).store_dict(sbt_item_code).store_dict(data).store_uint(0, 1).end_cell();

  return begin_cell().store_uint(4, 3)
                     .store_int(wc, 8)
                     .store_uint(cell_hash(state_init), 256)
                     .end_cell()
                     .begin_parse();
}


() recv_internal(int balance, int msg_value, cell in_msg_full, slice in_msg) impure {
  slice cs = in_msg_full.begin_parse();
  int flags = cs~load_uint(4);

  slice sender_address = cs~load_msg_addr();

  int op = in_msg~load_uint(32);
  int query_id = in_msg~load_uint(64);

  if (op == op::ownership_proof()) {
    int id = in_msg~load_uint(256);

    (slice collection_addr, cell sbt_code) = load_data();
    throw_unless(403, equal_slices(sender_address, collection_addr.calculate_sbt_address(sbt_code, 0, id)));

    slice owner_addr = in_msg~load_msg_addr();
    cell payload = in_msg~load_ref();
    
    int revoked_at = in_msg~load_uint(64);
    throw_if(403, revoked_at > 0);
    
    int with_content = in_msg~load_uint(1);
    if (with_content != 0) {
        cell sbt_content = in_msg~load_ref();
    }
    
    ;;
    ;; sbt verified, do something
    ;;

    return ();
  }

  throw(0xffff);
}

```

--------------------------------

### NFT Creation Response (In Queue)

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/minting-api-en.md

Example JSON response indicating that the NFT creation request has been accepted and is in the queue. The NFT address and a URL to view it are provided.

```json
{
  "success": true,
  "response": {
    "status": "in_queue",
    "index": 260343653244928,
    "address": "EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ",
    "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
    "url": "https://testnet.getgems.io/collection/EQD008sUupO8AvdMte6OLiriOrsoSkCoi59REKIOgyZHDz32/EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ"
  }
}
```

--------------------------------

### NFT Creation Response (Ready)

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/minting-api-en.md

Example JSON response indicating that the NFT has been successfully created and is ready on the blockchain. It includes the NFT's address and a direct URL.

```json
{
  "success": true,
  "response": {
    "status": "ready",
    "index": 260343653244928,
    "address": "EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ",
    "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
    "url": "https://testnet.getgems.io/collection/EQD008sUupO8AvdMte6OLiriOrsoSkCoi59REKIOgyZHDz32/EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ"
  }
}
```

--------------------------------

### Create NFT

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/minting-api-en.md

Send a request to create a new NFT. In the response, you will receive the NFT address and a link to getgems. The NFT is not created instantly; the process runs in the background and takes from 6 seconds to several minutes. You can track the NFT creation status via a GET request.

```APIDOC
## POST /public-api/minting/{{collectionAddress}}

### Description
Initiates the creation of a new NFT within a specified collection.

### Method
POST

### Endpoint
`/public-api/minting/{{collectionAddress}}`

### Parameters
#### Request Body
- **requestId** (string, max 100 char) - Required - Unique request identifier used to prevent resubmission of the same request. Repeated requests with the same requestId will be ignored.
- **ownerAddress** (string) - Required - NFT owner’s address in UQ... or EQ... format.
- **name** (string) - Optional - The name of the NFT.
- **description** (string) - Optional - The description of the NFT.
- **image** (string) - Optional - URL of the NFT image.
- **attributes** (array) - Optional - An array of attributes for the NFT.
  - **trait_type** (string) - The type of the attribute (e.g., "Background").
  - **value** (string) - The value of the attribute (e.g., "Red").

### Request Example
```json
{
  "requestId": "1689451433227",
  "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
  "name": "Spotty",
  "description": "This is my cool nft collection",
  "image": "https://s.getgems.io/nft/b/c/62bd932a7b5f87901f3d8d19/image.png",
  "attributes": [
    {
      "trait_type": "Background",
      "value": "Red"
    }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **response** (object) - Contains the details of the minting process.
  - **status** (string) - The current status of the NFT minting process (e.g., "in_queue", "ready").
  - **index** (number) - The index of the NFT in the collection.
  - **address** (string) - The address of the created NFT.
  - **ownerAddress** (string) - The address of the NFT owner.
  - **url** (string) - A URL to view the NFT on getgems.

#### Response Example
```json
{
  "success": true,
  "response": {
    "status": "in_queue",
    "index": 260343653244928,
    "address": "EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ",
    "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
    "url": "https://testnet.getgems.io/collection/EQD008sUupO8AvdMte6OLiriOrsoSkCoi59REKIOgyZHDz32/EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ"
  }
}
```
```

--------------------------------

### Insufficient Funds Error

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/minting-api-en.md

Example JSON response for a 400 error indicating insufficient funds in the wallet to cover gas fees for NFT minting.

```json
{
  "name": "Logic Error",
  "status": 400,
  "errors": [
    {
      "message": "You need to top up your wallet"
    }
  ]
}
```

--------------------------------

### Example NFT Metadata JSON

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/metadata.md

This is a standard JSON structure for NFT metadata, including basic information, image, attributes, and custom buttons.

```json
{
  "name": "Magic Mushroom #57",
  "description": "Hand drawing brings the NFT an artistic value, while various accessories and materials bring uniqueness and significance in our rapidly changing world.",
  "image": "https://s.getgems.io/nft/c/62695cb92d780b7496caea3a/nft/56/629b9349e034e8e582cf6448.png",
  "attributes": [
    {
      "trait_type": "Material",
      "value": "Wool fabric"
    },
    {
      "trait_type": "Hat",
      "value": "Top hat"
    },
    {
      "trait_type": "Glasses",
      "value": "None"
    },
    {
      "trait_type": "Item",
      "value": "None"
    },
    {
      "trait_type": "Background",
      "value": "Dark"
    }
  ],
  "buttons": [
    {
      "label": "@mint",
      "uri": "https://t.me/mint?startapp"
    }
  ]
}
```

--------------------------------

### Check NFT Creation Status

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/minting-api-en.md

Send a GET request to check the status of an NFT creation request using the same requestId. Allow at least 6 seconds between status check requests.

```bash
curl -X 'GET' \
  'https://api.testnet.getgems.io/public-api/minting/{{collectionAddress}}/{{requestId}}' \
  -H 'accept: application/json' \
  -H 'Authorization: {{authorization}}'
```

--------------------------------

### Collection Metadata JSON Example

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/metadata.md

This JSON structure defines the metadata for an NFT collection. It includes fields for the collection's name, description, avatar image, cover image, and social media links.

```json
{
  "name": "Magic Mushrooms",
  "description": "Magic Mushrooms is an NFT collection of magic mushrooms created specially for Telegram and The Open Network.\n\nHand drawing brings the collection an artistic value, while various accessories and materials bring uniqueness and significance in our rapidly changing world.",
  "image": "https://s.getgems.io/nft/c/62695cb92d780b7496caea3a/avatar.png",
  "cover_image": "https://s.getgems.io/nft/c/62695cb92d780b7496caea3a/cover.png",
  "social_links": [
    "https://t.me/ton_magic_mushrooms"
  ]
}
```

--------------------------------

### Get NFTs on Sale in a Collection

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/read-api-en.md

Retrieves a list of NFTs currently listed for sale within a specified NFT collection. This endpoint is useful for displaying items available for purchase.

```APIDOC
## GET /v1/nfts/on-sale/{collectionAddress}

### Description
Retrieves a list of NFTs currently for sale in a specific collection.

### Method
GET

### Endpoint
/v1/nfts/on-sale/{collectionAddress}

### Parameters
#### Path Parameters
- **collectionAddress** (string) - Required - The unique address of the NFT collection.

#### Query Parameters
- **cursor** (string) - Optional - Used for pagination to retrieve the next set of results.

#### Request Body
This endpoint does not require a request body.

### Request Example
```bash
curl -X 'GET' \
  'https://api.getgems.io/public-api/v1/nfts/on-sale/EQCA14o1-VWhS2efqoh_9M1b_A9DtKTuoqfmkn83AbJzwnPi' \
  -H 'accept: application/json' \
  -H 'Authorization: <API KEY>'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **response** (object) - Contains the list of NFTs and pagination information.
  - **items** (array) - A list of NFT objects currently on sale.
    - **address** (string) - The unique address of the NFT item.
    - **collectionAddress** (string) - The address of the collection the NFT belongs to.
    - **ownerAddress** (string) - The current owner's address.
    - **actualOwnerAddress** (string) - The actual owner's address (can differ from ownerAddress in case of delegation).
    - **image** (string) - URL of the NFT's image.
    - **name** (string) - The name of the NFT.
    - **description** (string) - A description of the NFT.
    - **attributes** (array) - A list of attributes associated with the NFT.
    - **sale** (object) - Information about the NFT's sale.
      - **type** (string) - The type of sale (e.g., "Auction", "FixedPrice").
      - **currency** (string) - The currency used for the sale (e.g., "TON").
      - **minBid** (string) - The minimum bid amount for an auction.
      - **maxBid** (string) - The maximum bid amount for an auction.
      - **finishAt** (string) - The timestamp when the sale ends.
      - **lastBidAmount** (string) - The amount of the last bid.
      - **lastBidAddress** (string) - The address of the last bidder.
      - **lastBidAt** (string) - The timestamp of the last bid.
      - **marketplaceFee** (string) - The fee charged by the marketplace.
      - **marketplaceFeeAddress** (string) - The address where the marketplace fee is sent.
      - **royaltyAddress** (string) - The address where royalties are sent.
      - **royaltyPercent** (object) - Royalty percentage details.
      - **version** (string) - Sale version information.
  - **cursor** (string) - A cursor for fetching the next page of results.

#### Response Example
```json
{
  "success": true,
  "response": {
    "items": [
      {
        "address": "EQAtjj8TSTMlGcSV4noceB3D7_NrqQsRfWd6Wxo33NzfV7Yi",
        "collectionAddress": "EQCA14o1-VWhS2efqoh_9M1b_A9DtKTuoqfmkn83AbJzwnPi",
        "ownerAddress": "EQDO-o9ZgXFTS23bE_nG88PfB39-9X6IAtCrh6QB88V9j7YX",
        "actualOwnerAddress": "EQCY2l1vlXnfIl62sE-_AuGeUXA9i0Jp2zjwLMpXgpbTyj2O",
        "image": "https://i.getgems.io/NqiR1Ch-5m-h_5PpX6069a565wQqvizA6XuNsdGdriA/rs:fill:500:500:1/g:ce/czM6Ly9nZXRnZW1zLXMzL25mdC1jb250ZW50LWNhY2hlL2ltYWdlcy9FUUNBMTRvMS1WV2hTMmVmcW9oXzlNMWJfQTlEdEtUdW9xZm1rbjgzQWJKenduUGkvMjdhMzE1NzEzMGI0NDMyMQ.png",
        "name": "@notpixelroyale",
        "description": "The @notpixelroyale username on Telegram. Aliases: notpixelroyale.t.me, t.me/notpixelroyale",
        "attributes": [],
        "sale": {
          "type": "Auction",
          "currency": "TON",
          "minBid": "2200000000",
          "maxBid": null,
          "finishAt": "2025-08-18T01:01:05.000Z",
          "lastBidAmount": "2000000000",
          "lastBidAddress": "EQCch6yDUm-Ebhx5a2zmEI8U9igWvTkBS51RN99tXYbFJAA6",
          "lastBidAt": "2025-08-07T12:18:14.000Z",
          "marketplaceFee": "0",
          "marketplaceFeeAddress": "EQC-56PXuMBvlVIDLDiApWp0twKtiyJPQr-xrBwzvXGQgPYM",
          "royaltyAddress": "EQBAjaOyi2wGWlk-EDkSabqqnF-MrrwMadnwqrurKpkla9nE",
          "royaltyPercent": {
            "base": 100,
            "factor": 0
          },
          "version": "1b0132132afa3000,s:0:TON,m:c2de3029a60a7dd1"
        }
      }
    ],
    "cursor": "5.7%2C6813a6976428bb255010d739"
  }
}
```
```

--------------------------------

### buildNftAuctionV3R3DataCell / buildNftAuctionV2StateInit

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Serialises auction storage and builds the StateInit. The auction runs until `endTimestamp`; each new bid must exceed the previous by at least `minPercentStep` percent. `maxBid` can be set to enable a buy-now price.

```APIDOC
## buildNftAuctionV3R3DataCell / buildNftAuctionV2StateInit

### Description
Serialises auction storage and builds the StateInit. The auction runs until `endTimestamp`; each new bid must exceed the previous by at least `minPercentStep` percent. `maxBid` can be set to enable a buy-now price.

### Method Signature
```typescript
buildNftAuctionV3R3DataCell(auctionData: NftAuctionV3R3Data): Cell
buildNftAuctionV2StateInit(auctionData: NftAuctionV2Data): StateInit
```

### Parameters
#### `auctionData` Object
- **end** (boolean) - Required - Indicates if the auction has ended.
- **endTimestamp** (number) - Required - Timestamp when the auction ends.
- **minBid** (BN) - Required - The minimum opening bid amount.
- **maxBid** (BN) - Optional - The buy-now price. If set, enables a buy-now option.
- **minPercentStep** (number) - Required - The minimum percentage increase for each subsequent bid.
- **stepTimeSeconds** (number) - Required - The duration in seconds to extend the auction upon a last-minute bid.
- **nftAddress** (Address) - Required - The address of the NFT being auctioned.
- **nftOwnerAddress** (Address) - Required - The current owner's address of the NFT.
- **marketplaceAddress** (Address) - Required - The address of the marketplace.
- **marketplaceFeeAddress** (Address) - Required - The address to receive marketplace fees.
- **marketplaceFeeFactor** (number) - Required - The numerator for calculating the marketplace fee.
- **marketplaceFeeBase** (number) - Required - The denominator for calculating the marketplace fee.
- **royaltyAddress** (Address) - Required - The address to receive royalty payments.
- **royaltyFactor** (number) - Required - The numerator for calculating the royalty payment.
- **royaltyBase** (number) - Required - The denominator for calculating the royalty payment.
- **createdAtTimestamp** (number) - Required - Timestamp when the auction was created.

### Request Example
```typescript
import { Address } from 'ton'
import BN from 'bn.js'
import {
  buildNftAuctionV3R3DataCell,
} from './packages/contracts/nft-auction-v2/NftAuctionV2.data'

const auctionData = {
  end: false,
  endTimestamp: Math.floor(Date.now() / 1000) + 7 * 24 * 3600, // 7 days
  minBid: new BN('1000000000'),   // 1 TON minimum opening bid
  maxBid: new BN('100000000000'), // 100 TON buy-now price
  minPercentStep: 5,              // each bid must be at least 5 % higher
  stepTimeSeconds: 3600,          // extend auction by 1 h on last-minute bid
  nftAddress: Address.parse('EQD2Kivo-msu8dsQNiMkPHMoEfmNA3oU-ZQ_yWejbN9vXmVu'),
  nftOwnerAddress: Address.parse('UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm'),
  marketplaceAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
  marketplaceFeeAddress: Address.parse('EQCjk1hh952vWaE9bRguFkAhDAL5jj3xj9p0uPWrFBq_GEMS'),
  marketplaceFeeFactor: 5,
  marketplaceFeeBase: 100,        // 5 % marketplace fee
  royaltyAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
  royaltyFactor: 5,
  royaltyBase: 100,               // 5 % royalty
  createdAtTimestamp: Math.floor(Date.now() / 1000),
}

const dataCell = buildNftAuctionV3R3DataCell(auctionData)
// Use dataCell with NftAuctionV3R3CodeBoc in StateInit to deploy
```
```

--------------------------------

### Queue NFT for Minting API Request

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Submits a gasless mint request to the Getgems API. Ensure your wallet has sufficient TON for gas fees. Use the requestId for idempotency.

```bash
# Replace {{authorization}} with your API key from https://getgems.io/public-api
# Replace {{collectionAddress}} with your deployed collection address

curl -X POST \
  'https://api.testnet.getgems.io/public-api/minting/EQD008sUupO8AvdMte6OLiriOrsoSkCoi59REKIOgyZHDz32' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer MY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "requestId": "1689451433227",
    "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
    "name": "Spotty #1",
    "description": "First item in the Spotty collection",
    "image": "https://example.com/spotty/1.png",
    "attributes": [
      { "trait_type": "Background", "value": "Red" },
      { "trait_type": "Eyes", "value": "Laser" }
    ]
  }'

# Expected response (status: in_queue — NFT is queued, not yet on-chain)
# {
#   "success": true,
#   "response": {
#     "status": "in_queue",
#     "index": 260343653244928,
#     "address": "EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ",
#     "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
#     "url": "https://testnet.getgems.io/collection/EQD008s.../EQAiSecR..."
#   }
# }
```

--------------------------------

### Create NFT Request

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/minting-api-en.md

Send a POST request to create a new NFT. Ensure a unique requestId is used for each NFT. The response indicates if the NFT is queued for minting.

```bash
curl -X 'POST' \
  'https://api.testnet.getgems.io/public-api/minting/{{collectionAddress}}' \
  -H 'accept: application/json' \
  -H 'Authorization: {{authorization}}' \
  -H 'Content-Type: application/json' \
  -d '{ 
  "requestId": "1689451433227",
  "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
  "name": "Spotty",
  "description": "This is my cool nft collection",
  "image": "https://s.getgems.io/nft/b/c/62bd932a7b5f87901f3d8d19/image.png",
  "attributes": [
    {
      "trait_type": "Background",
      "value": "Red"
    }
  ]
}'
```

--------------------------------

### Batch Mint NFT Items

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Serializes a dictionary of mint instructions into a single message for batch minting. Reduces on-chain costs for large drops.

```typescript
import { Address } from 'ton'
import BN from 'bn.js'
import { Queries, CollectionMintItemInput } from './packages/contracts/nft-collection/NftCollection.data'

const items: CollectionMintItemInput[] = Array.from({ length: 5 }, (_, i) => ({
  index: i,
  passAmount: new BN('50000000'), // 0.05 TON per item
  ownerAddress: Address.parse('UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm'),
  content: `${i}.json`,
}))

const batchMsg = Queries.batchMint({ queryId: Date.now(), items })
// Send batchMsg to the collection contract with enough TON to cover all items

```

--------------------------------

### buildNftFixPriceSaleV4R1Data / buildNftFixPriceSaleV4R1DeployData

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Builds the storage cell and StateInit for a `nft-fixprice-sale-v4r1` contract. Supports both TON and Jetton pricing. The deployer address is temporarily set in storage; a deploy message signed with a random ephemeral key pair finalises the actual marketplace address.

```APIDOC
## buildNftFixPriceSaleV4R1Data / buildNftFixPriceSaleV4R1DeployData

### Description
Builds the storage cell and StateInit for a `nft-fixprice-sale-v4r1` contract. Supports both TON and Jetton pricing. The deployer address is temporarily set in storage; a deploy message signed with a random ephemeral key pair finalises the actual marketplace address.

### Method Signature
```typescript
buildNftFixPriceSaleV4R1DeployData({
  queryId: bigint,
  deployerAddress: Address,
  marketplaceAddress: Address,
  config: Omit<NftFixPriceSaleV4DR1Data, 'marketplaceAddress'>,
  jettonPrices: Dictionary<Address, NftFixPriceJettonPriceValue>,
  jettonWalletAddressResolver: (master: Address, addr: Address) => Promise<Address>
}): Promise<{ address: Address, stateInit: StateInit, message: Cell }>
```

### Parameters
#### `config` Object
- **isComplete** (boolean) - Required - Indicates if the configuration is complete.
- **createdAt** (number) - Required - Timestamp when the listing was created.
- **nftAddress** (Address) - Required - The address of the NFT being listed.
- **nftOwnerAddress** (Address) - Required - The current owner's address of the NFT.
- **fullTonPrice** (bigint) - Required - The full price in TON (nanotons).
- **marketplaceFeeAddress** (Address) - Required - The address to receive marketplace fees.
- **marketplaceFeePercent** (number) - Required - The percentage of the sale price for the marketplace fee.
- **royaltyAddress** (Address) - Required - The address to receive royalty payments.
- **royaltyPercent** (number) - Required - The percentage of the sale price for royalty payments.
- **soldAtTime** (number) - Required - Timestamp when the NFT was sold.
- **soldQueryId** (bigint) - Required - Query ID associated with the sale.

#### `jettonPrices` Object
- A dictionary mapping Jetton master addresses to their price configurations.

#### `jettonWalletAddressResolver` Function
- **master** (Address) - The master address of the Jetton.
- **addr** (Address) - The address to resolve.
- Returns a Promise resolving to the Jetton wallet address.

### Request Example
```typescript
import { Address, Dictionary } from '@ton/core'
import {
  buildNftFixPriceSaleV4R1DeployData,
  NftFixPriceSaleV4DR1Data,
} from './packages/contracts/nft-fixprice-sale-v4/NftFixPriceSaleV4.data'

async function createFixedPriceListing(client: any) {
  const config: Omit<NftFixPriceSaleV4DR1Data, 'marketplaceAddress'> = {
    isComplete: false,
    createdAt: Math.floor(Date.now() / 1000),
    nftAddress: Address.parse('EQD2Kivo-msu8dsQNiMkPHMoEfmNA3oU-ZQ_yWejbN9vXmVu'),
    nftOwnerAddress: Address.parse('UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm'),
    fullTonPrice: 5_000_000_000n, // 5 TON in nanotons
    marketplaceFeeAddress: Address.parse('EQCjk1hh952vWaE9bRguFkAhDAL5jj3xj9p0uPWrFBq_GEMS'),
    marketplaceFeePercent: 0.05,  // 5 %
    royaltyAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
    royaltyPercent: 0.05,         // 5 %
    soldAtTime: 0,
    soldQueryId: 0n,
  }

  const deployData = await buildNftFixPriceSaleV4R1DeployData({
    queryId: 1n,
    deployerAddress: Address.parse('EQ...deployer...'),
    marketplaceAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
    config,
    jettonPrices: {},
    jettonWalletAddressResolver: async (master, addr) => { throw new Error('unused') },
  })

  console.log('Sale contract address:', deployData.address.toString())
}
```
```

--------------------------------

### Place a buy offer on an NFT with NftOfferDataV1R3

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Deploys a time-limited buy-offer contract. The offer owner locks funds, and the trade executes if the NFT is transferred to the contract before the offer expires. The owner or marketplace can cancel the offer.

```typescript
import { Address } from 'ton'
import BN from 'bn.js'
import {
  buildNftOfferStateInit,
  buildNftOfferV1R3DataCell,
  NftOfferDataV1R3,
} from './packages/contracts/nft-offer/NftOfferData'

const offerConfig: NftOfferDataV1R3 = {
  isComplete: false,
  createdAt: Math.floor(Date.now() / 1000),
  finishAt: Math.floor(Date.now() / 1000) + 3 * 24 * 3600, // offer valid 3 days
  marketplaceAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
  nftAddress: Address.parse('EQD2Kivo-msu8dsQNiMkPHMoEfmNA3oU-ZQ_yWejbN9vXmVu'),
  offerOwnerAddress: Address.parse('UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm'),
  fullPrice: new BN('8000000000'), // 8 TON offer
  marketplaceFeeAddress: Address.parse('EQCjk1hh952vWaE9bRguFkAhDAL5jj3xj9p0uPWrFBq_GEMS'),
  marketplaceFactor: 5,
  marketplaceBase: 100,
  royaltyAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
  royaltyFactor: 5,
  royaltyBase: 100,
}

const { address, stateInit } = buildNftOfferStateInit(offerConfig)
console.log('Offer contract address:', address.toFriendly())
// Deploy stateInit and forward fullPrice + fees to the offer address

// Cancel offer (by owner or marketplace):
import { Queries } from './packages/contracts/nft-offer/NftOfferData'
const cancelMsg = Queries.cancelOfferInternalMessage({ message: 'Changed my mind' })
```

--------------------------------

### Retrieve NFTs On Sale

Source: https://github.com/getgems-io/nft-contracts/blob/main/docs/read-api-en.md

Use this endpoint to fetch a list of NFTs currently available for sale within a specific collection. Replace `<API KEY>` with your actual API key.

```bash
curl -X 'GET' \
  'https://api.getgems.io/public-api/v1/nfts/on-sale/EQCA14o1-VWhS2efqoh_9M1b_A9DtKTuoqfmkn83AbJzwnPi' \
  -H 'accept: application/json' \
  -H 'Authorization: <API KEY>'
```

```json
{
  "success": true,
  "response": {
    "items": [
      {
        "address": "EQAtjj8TSTMlGcSV4noceB3D7_NrqQsRfWd6Wxo33NzfV7Yi",
        "collectionAddress": "EQCA14o1-VWhS2efqoh_9M1b_A9DtKTuoqfmkn83AbJzwnPi",
        "ownerAddress": "EQDO-o9ZgXFTS23bE_nG88PfB39-9X6IAtCrh6QB88V9j7YX",
        "actualOwnerAddress": "EQCY2l1vlXnfIl62sE-_AuGeUXA9i0Jp2zjwLMpXgpbTyj2O",
        "image": "https://i.getgems.io/NqiR1Ch-5m-h_5PpX6069a565wQqvizA6XuNsdGdriA/rs:fill:500:500:1/g:ce/czM6Ly9nZXRnZW1zLXMzL25mdC1jb250ZW50LWNhY2hlL2ltYWdlcy9FUUNBMTRvMS1WV2hTMmVmcW9oXzlNMWJfQTlEdEtUdW9xZm1rbjgzQWJKenduUGkvMjdhMzE1NzEzMGI0NDMyMQ.png",
        "name": "@notpixelroyale",
        "description": "The @notpixelroyale username on Telegram. Aliases: notpixelroyale.t.me, t.me/notpixelroyale",
        "attributes": [],
        "sale": {
          "type": "Auction",
          "currency": "TON",
          "minBid": "2200000000",
          "maxBid": null,
          "finishAt": "2025-08-18T01:01:05.000Z",
          "lastBidAmount": "2000000000",
          "lastBidAddress": "EQCch6yDUm-Ebhx5a2zmEI8U9igWvTkBS51RN99tXYbFJAA6",
          "lastBidAt": "2025-08-07T12:18:14.000Z",
          "marketplaceFee": "0",
          "marketplaceFeeAddress": "EQC-56PXuMBvlVIDLDiApWp0twKtiyJPQr-xrBwzvXGQgPYM",
          "royaltyAddress": "EQBAjaOyi2wGWlk-EDkSabqqnF-MrrwMadnwqrurKpkla9nE",
          "royaltyPercent": {
            "base": 100,
            "factor": 0
          },
          "version": "1b0132132afa3000,s:0:TON,m:c2de3029a60a7dd1"
        }
      }
      // ... Other NFT objects
    ],
    "cursor": "5.7%2C6813a6976428bb255010d739"
  }
}
```

--------------------------------

### Deploy Fixed-Price Sale Contract v4r1

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Builds the storage cell and StateInit for a nft-fixprice-sale-v4r1 contract. Supports TON and Jetton pricing. The deployer address is temporarily set in storage; a deploy message signed with a random ephemeral key pair finalises the actual marketplace address.

```typescript
import { Address, Dictionary } from '@ton/core'
import {
  buildNftFixPriceSaleV4R1DeployData,
  buildJettonPriceDict,
  NftFixPriceSaleV4DR1Data,
} from './packages/contracts/nft-fixprice-sale-v4/NftFixPriceSaleV4.data'

async function createFixedPriceListing(client: any) {
  const config: Omit<NftFixPriceSaleV4DR1Data, 'marketplaceAddress'> = {
    isComplete: false,
    createdAt: Math.floor(Date.now() / 1000),
    nftAddress: Address.parse('EQD2Kivo-msu8dsQNiMkPHMoEfmNA3oU-ZQ_yWejbN9vXmVu'),
    nftOwnerAddress: Address.parse('UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm'),
    fullTonPrice: 5_000_000_000n, // 5 TON in nanotons
    marketplaceFeeAddress: Address.parse('EQCjk1hh952vWaE9bRguFkAhDAL5jj3xj9p0uPWrFBq_GEMS'),
    marketplaceFeePercent: 0.05,  // 5 %
    royaltyAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
    royaltyPercent: 0.05,         // 5 %
    soldAtTime: 0,
    soldQueryId: 0n,
  }

  const deployData = await buildNftFixPriceSaleV4R1DeployData({
    queryId: 1n,
    deployerAddress: Address.parse('EQ...deployer...'),
    marketplaceAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
    config,
    jettonPrices: {}, // TON-only listing — pass empty object
    jettonWalletAddressResolver: async (master, addr) => { throw new Error('unused') },
  })

  console.log('Sale contract address:', deployData.address.toString())
  // deployData.stateInit  — deploy as StateInit
  // deployData.message    — first message to activate the contract
}
```

--------------------------------

### Deploy NFT Auction Contract v3r3 / v4r1

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Serialises auction storage and builds the StateInit for an English auction. The auction runs until `endTimestamp`; each new bid must exceed the previous by at least `minPercentStep` percent. `maxBid` can be set to enable a buy-now price.

```typescript
import { Address } from 'ton'
import BN from 'bn.js'
import {
  buildNftAuctionV3R3DataCell,
  buildNftAuctionV2StateInit,
} from './packages/contracts/nft-auction-v2/NftAuctionV2.data'

const auctionData = {
  end: false,
  endTimestamp: Math.floor(Date.now() / 1000) + 7 * 24 * 3600, // 7 days
  minBid: new BN('1000000000'),   // 1 TON minimum opening bid
  maxBid: new BN('100000000000'), // 100 TON buy-now price
  minPercentStep: 5,              // each bid must be at least 5 % higher
  stepTimeSeconds: 3600,          // extend auction by 1 h on last-minute bid
  nftAddress: Address.parse('EQD2Kivo-msu8dsQNiMkPHMoEfmNA3oU-ZQ_yWejbN9vXmVu'),
  nftOwnerAddress: Address.parse('UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm'),
  marketplaceAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
  marketplaceFeeAddress: Address.parse('EQCjk1hh952vWaE9bRguFkAhDAL5jj3xj9p0uPWrFBq_GEMS'),
  marketplaceFeeFactor: 5,
  marketplaceFeeBase: 100,        // 5 % marketplace fee
  royaltyAddress: Address.parse('EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS'),
  royaltyFactor: 5,
  royaltyBase: 100,               // 5 % royalty
  createdAtTimestamp: Math.floor(Date.now() / 1000),
}

const dataCell = buildNftAuctionV3R3DataCell(auctionData)
// Use dataCell with NftAuctionV3R3CodeBoc in StateInit to deploy
```

--------------------------------

### Check NFT Minting Status API Request

Source: https://context7.com/getgems-io/nft-contracts/llms.txt

Polls the creation status of a previously submitted mint request. Recommended polling interval is at least 6 seconds. The NFT is live on-chain when the status is 'ready'.

```bash
curl -X GET \
  'https://api.testnet.getgems.io/public-api/minting/EQD008sUupO8AvdMte6OLiriOrsoSkCoi59REKIOgyZHDz32/1689451433227' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer MY_API_KEY'

# Response when on-chain:
# {
#   "success": true,
#   "response": {
#     "status": "ready",
#     "index": 260343653244928,
#     "address": "EQAiSecR8RXTt0-cPb5JrLD-BLVYxKd48A9ySHksrqAUXoVJ",
#     "ownerAddress": "UQB5HQfjevz9su4ZQGcDT_4IB0IUGh5PM2vAXPU2e4O6_YBm",
#     "url": "https://testnet.getgems.io/collection/EQD008s.../EQAiSecR..."
#   }
# }

# Error when wallet needs topping up:
# { "name": "Logic Error", "status": 400,
#   "errors": [{ "message": "You need to top up your wallet" }] }
```