### Start Auction (teleitem_start_auction)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Allows the NFT owner to start a new auction for their username. This involves configuring auction parameters like minimum bid, duration, and beneficiary.

```APIDOC
## POST /teleitem_start_auction

### Description
Allows the NFT owner to start a new auction for their username. This involves configuring auction parameters like minimum bid, duration, and beneficiary.

### Method
POST

### Endpoint
/teleitem_start_auction

### Parameters
#### Query Parameters
- **query_id** (int64) - Required - Unique query identifier
- **beneficiary** (slice) - Required - Address to receive auction proceeds
- **min_bid** (int) - Required - Minimum bid (must be >= 2 TON for standard, 0.06 TON for cheap)
- **max_bid** (int) - Optional - Instant-win price (0 = disabled)
- **bid_step** (int) - Required - Minimum bid increase % (e.g., 5)
- **extend_time** (int) - Optional - Extension on new bid in seconds (max 7 days)
- **duration** (int) - Required - Auction duration in seconds (max 365 days)

### Request Example
```json
{
  "query_id": 12345,
  "beneficiary": "<beneficiary_address>",
  "min_bid": 2000000000,
  "max_bid": 100000000000,
  "bid_step": 5,
  "extend_time": 900,
  "duration": 259200
}
```

### Response
#### Success Response (200)
- **query_id** (int64) - The query ID associated with the request.
- **status** (string) - Indicates success, typically 'ok'.

#### Response Example
```json
{
  "query_id": 12345,
  "status": "ok"
}
```

#### Error Codes
- **220** (err::forbidden_auction): Sender is not the owner.
- **223** (err::invalid_auction_config): Invalid auction parameters.
```

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

### Start NFT Auction using Func

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Allows an NFT owner to initiate a new auction for their username. It requires auction configuration parameters such as beneficiary, minimum bid, and duration. The function returns a cell representing the start auction message.

```func
// TL-B Schema
teleitem_msg_start_auction#487a8e81
    query_id:int64
    auction_config:^TeleitemAuctionConfig
= TeleitemMsg;

// Operation code
const int op::teleitem_start_auction = 0x487a8e81;

// Example: Owner starting a new auction
cell build_start_auction_message(
    int query_id,           // Unique query identifier
    slice beneficiary,      // Address to receive auction proceeds
    int min_bid,            // Minimum bid (must be >= 2 TON for standard, 0.06 TON for cheap)
    int max_bid,            // Instant-win price (0 = disabled)
    int bid_step,           // Minimum bid increase % (e.g., 5)
    int extend_time,        // Extension on new bid in seconds (max 7 days)
    int duration            // Auction duration in seconds (max 365 days)
) {
    cell auction_config = begin_cell()
        .store_slice(beneficiary)
        .store_grams(min_bid)        // e.g., 2000000000 (2 TON)
        .store_grams(max_bid)        // e.g., 100000000000 (100 TON)
        .store_uint(bid_step, 8)     // e.g., 5 (5%)
        .store_uint(extend_time, 32) // e.g., 900 (15 minutes)
        .store_uint(duration, 32)    // e.g., 259200 (3 days)
        .end_cell();

    return begin_cell()
        .store_uint(op::teleitem_start_auction, 32)
        .store_int(query_id, 64)
        .store_ref(auction_config)
        .end_cell();
}

// Response on success: op::teleitem_ok (0xa37a0983) with query_id
// Error codes:
// - err::forbidden_auction (220): Sender is not the owner
// - err::invalid_auction_config (223): Invalid auction parameters

```

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

### Teleitem Start Auction Message (Func)

Source: https://github.com/telegrammessenger/telemint/blob/main/README.md

Defines the message structure for starting a new auction on an NftItem. This message is accepted only from the owner of the NftItem and includes the query ID and the auction configuration.

```func
// Start new auction. Accepted only from the owner.
teleitem_msg_start_auction#487a8e81 query_id:int64 auction_config:^TeleitemAuctionConfig = TeleitemMsg;
```

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

### Get Full Domain

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the complete domain name, including the collection suffix. This method is only available for DNS-enabled NFTs.

```APIDOC
## GET /get_full_domain

### Description
Returns the complete domain name including the collection suffix (DNS-enabled variant only).

### Method
GET

### Endpoint
`/get_full_domain`

### Parameters
#### Query Parameters
- **nft_address** (string) - Required - The address of the NFT contract.

### Response
#### Success Response (200)
- **full_domain** (slice) - The complete domain name (e.g., "durov.t.me").

#### Response Example
```json
{
  "full_domain": "durov.t.me"
}
```
```

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

### Get Royalty Params

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the royalty configuration for secondary sales, including the numerator and denominator of the royalty percentage and the destination address for royalties.

```APIDOC
## GET /royalty_params

### Description
Returns the royalty configuration for secondary sales.

### Method
GET

### Endpoint
`/royalty_params`

### Parameters
#### Query Parameters
- **nft_address** (string) - Required - The address of the NFT contract.

### Response
#### Success Response (200)
- **numerator** (int) - The numerator of the royalty percentage.
- **denominator** (int) - The denominator of the royalty percentage.
- **destination** (slice) - The address receiving the royalties.

#### Response Example
```json
{
  "numerator": 5,
  "denominator": 100,
  "destination": "<royalty_address>"
}
```

*Royalty percentage = numerator / denominator (e.g., 5/100 = 5%).*
```

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

### Get Royalty Parameters

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the royalty configuration for secondary sales of the NFT. It returns the numerator and denominator of the royalty percentage, along with the address that will receive the royalties.

```func
// GET method signature
(int, int, slice) royalty_params() method_id;

// Returns:
// - int: numerator (royalty percentage numerator)
// - int: denominator (royalty percentage denominator)
// - slice: destination (address receiving royalties)

// Royalty percentage = numerator / denominator
// Example: numerator=5, denominator=100 = 5% royalty

// tonlib-cli> runmethod <nft_address> royalty_params
// Result: [5, 100, <royalty_address>]
```

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

### Deploy NFT Item with First Bid (telemint_msg_deploy) - FunC

Source: https://context7.com/telegrammessenger/telemint/llms.txt

This FunC code defines the TL-B schema and provides an example function to build a deployment message for a new NFT item, initiating an auction with the sender's bid. It includes parameters for signature, auction configuration, and optional royalty settings. The message must be cryptographically signed.

```func
// TL-B Schema for deployment message
telemint_unsigned_deploy$_
    subwallet_id:uint32       // Collection identifier
    valid_since:uint32        // Signature validity start (unix timestamp)
    valid_till:uint32         // Signature validity end (unix timestamp)
    token_name:TelemintText   // Username being auctioned (e.g., "premium")
    content:^Cell             // NFT metadata content
    auction_config:^TeleitemAuctionConfig  // Auction parameters
    royalty_params:(Maybe ^NftRoyaltyParams)  // Optional royalty override
= TelemintUnsignedDeploy;

telemint_msg_deploy#4637289a
    sig:bits512               // Ed25519 signature
    msg:TelemintUnsignedDeploy
= TelemintMsg;

// Operation code
const int op::telemint_msg_deploy = 0x4637289a;

// Example: Building a deploy message in FunC
cell build_deploy_message(
    slice signature,
    int subwallet_id,
    int valid_since,
    int valid_till,
    slice token_name,      // e.g., "durov"
    cell content,
    cell auction_config,
    cell royalty_params    // Can be null() for default royalties
) {
    return begin_cell()
        .store_uint(op::telemint_msg_deploy, 32)
        .store_slice(signature)           // 512 bits
        .store_uint(subwallet_id, 32)     // e.g., 1
        .store_uint(valid_since, 32)      // e.g., now() - 60
        .store_uint(valid_till, 32)       // e.g., now() + 3600
        .store_text(token_name)           // Length-prefixed string
        .store_ref(content)               // NFT metadata
        .store_ref(auction_config)        // Auction parameters
        .store_maybe_ref(royalty_params)  // Optional royalty override
        .end_cell();
}

// Auction config structure
// TeleitemAuctionConfig: beneficiary_address, initial_min_bid, max_bid,
//                        min_bid_step, min_extend_time, duration
cell build_auction_config(
    slice beneficiary_address,  // Address receiving auction proceeds
    int initial_min_bid,        // Minimum first bid in nanotons (e.g., 5000000000 = 5 TON)
    int max_bid,                // Instant-win price (0 = disabled)
    int min_bid_step,           // Minimum bid increase percentage (e.g., 5 = 5%)
    int min_extend_time,        // Auction extension on new bid (e.g., 900 = 15 min)
    int duration                // Total auction duration (e.g., 86400 = 24 hours)
) {
    return begin_cell()
        .store_slice(beneficiary_address)
        .store_grams(initial_min_bid)
        .store_grams(max_bid)
        .store_uint(min_bid_step, 8)
        .store_uint(min_extend_time, 32)
        .store_uint(duration, 32)
        .end_cell();
}

```

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

### Get Auction Config

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the configuration parameters of an auction, including beneficiary address, initial minimum bid, max bid (instant win), minimum bid step, minimum extension time, and original duration.

```APIDOC
## GET /get_telemint_auction_config

### Description
Returns the configuration parameters of an auction.

### Method
GET

### Endpoint
`/get_telemint_auction_config`

### Parameters
#### Query Parameters
- **nft_address** (string) - Required - The address of the NFT contract.

### Response
#### Success Response (200)
- **beneficiary_address** (slice) - The address that receives auction proceeds.
- **initial_min_bid** (int) - The starting minimum bid in nanotons.
- **max_bid** (int) - The instant-win price (0 if disabled).
- **min_bid_step** (int) - The minimum bid increase percentage.
- **min_extend_time** (int) - The number of seconds to extend the auction on a new bid.
- **duration** (int) - The original auction duration in seconds.

#### Response Example
```json
{
  "beneficiary_address": "<beneficiary>",
  "initial_min_bid": 2000000000,
  "max_bid": 0,
  "min_bid_step": 5,
  "min_extend_time": 900,
  "duration": 86400
}
```

*Note: Returns all zeros if no auction is active.*
```

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

### Teleitem Deploy Message Structure (Func)

Source: https://github.com/telegrammessenger/telemint/blob/main/README.md

Defines the structure for the Teleitem deploy message, accepted only from NftCollection. It includes sender address, bid amount, token information, NFT content, auction configuration, and royalty parameters for creating an NftItem and starting an auction.

```func
// Create NftItem and start an auction. Accepted only from NftCollection.
teleitem_msg_deploy#299a3e15 sender_address:MsgAddressInt bid:Grams token_info:^TelemintTokenInfo nft_content:^Cell
  auction_config:^TeleitemAuctionConfig royalty_params:^NftRoyaltyParams = TeleitemMsg;
```

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

### Get Telemint Auction Config

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Fetches the configuration parameters for an auction, such as the beneficiary address, initial minimum bid, maximum bid (instant-win price), minimum bid step percentage, minimum extension time, and original duration. Returns zeros if no auction is active.

```func
// GET method signature
(slice, int, int, int, int, int) get_telemint_auction_config() method_id;

// Returns:
// - slice: beneficiary_address (receives auction proceeds)
// - int: initial_min_bid (starting minimum bid in nanotons)
// - int: max_bid (instant-win price, 0 if disabled)
// - int: min_bid_step (minimum bid increase percentage)
// - int: min_extend_time (seconds to extend on new bid)
// - int: duration (original auction duration in seconds)

// Returns all zeros if no auction active (does not throw)

// Example query
// tonlib-cli> runmethod <nft_address> get_telemint_auction_config
// Result: [<beneficiary>, 2000000000, 0, 5, 900, 86400]
//         (beneficiary, 2 TON min, no max, 5% step, 15min extend, 24h duration)
```

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

### Get NFT Address by Index (get_nft_address_by_index)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Calculates the deterministic address of an NFT item using its index, which is derived from the hash of the token name. This allows for predictable address generation for each NFT within a collection.

```func
// GET method signature
slice get_nft_address_by_index(int index) method_id;

// Example: Get address for username "durov"
// int index = string_hash("durov");  // SHA256 of token name
// slice nft_address = get_nft_address_by_index(index);

// tonlib-cli> runmethod <collection_address> get_nft_address_by_index <index>
// Result: <nft_item_address>
```

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

### Get Full Domain (DNS-enabled NftItem)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

For DNS-enabled NftItems, this method returns the complete domain name, which includes the domain, token name, and a null terminator. This is useful for identifying the full address in DNS-like structures.

```func
// GET method signature (only in DNS-enabled NftItem)
slice get_full_domain() method_id;

// Returns: domain + token_name + null terminator
// Example: ".t.me" + "durov" + "\0" = "durov.t.me"

// tonlib-cli> runmethod <nft_address> get_full_domain
// Result: "durov.t.me"
```

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

### Telemint Deploy Message with Signature (Func)

Source: https://github.com/telegrammessenger/telemint/blob/main/README.md

Represents a signed deployment message for Telemint, including the signature and the unsigned deployment payload. This message is used to initiate the creation of an NftItem and start an auction, signed by the auction's private key.

```func
telemint_msg_deploy#4637289a  sig:bits512 msg:TelemintUnsignedDeploy = TelemintMsg;
```

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

### Get Token Name

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the username or token name associated with an NFT item.

```APIDOC
## GET /get_telemint_token_name

### Description
Returns the username/token name of this NFT item.

### Method
GET

### Endpoint
`/get_telemint_token_name`

### Parameters
#### Query Parameters
- **nft_address** (string) - Required - The address of the NFT contract.

### Response
#### Success Response (200)
- **token_name** (slice) - The token name (e.g., "durov").

#### Response Example
```json
{
  "token_name": "durov"
}
```
```

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

### Get Full Domain (get_full_domain)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Returns the DNS domain suffix associated with a DNS-enabled NFT collection. This is typically used for services like Telegram usernames, returning a suffix like ".t.me".

```func
// GET method signature (only in DNS-enabled collection)
slice get_full_domain() method_id;

// Returns the domain suffix as a length-prefixed string slice
// Example: "\x04.t.me" (4 bytes length + ".t.me")

// tonlib-cli> runmethod <collection_address> get_full_domain
// Result: ".t.me"
```

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

### Get Auction State

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the current state of an active auction, including the highest bidder, bid amount, bid timestamp, minimum next bid, and auction end time.

```APIDOC
## GET /get_telemint_auction_state

### Description
Returns the current state of an active auction.

### Method
GET

### Endpoint
`/get_telemint_auction_state`

### Parameters
#### Query Parameters
- **nft_address** (string) - Required - The address of the NFT contract.

### Response
#### Success Response (200)
- **bidder_address** (slice) - The address of the current highest bidder (null if no bids).
- **bid** (int) - The current highest bid in nanotons.
- **bid_ts** (int) - The timestamp of the highest bid.
- **min_bid** (int) - The minimum amount for the next bid in nanotons.
- **end_time** (int) - The auction end timestamp.

#### Response Example
```json
{
  "bidder_address": "<bidder_addr>",
  "bid": 5000000000,
  "bid_ts": 1699900000,
  "min_bid": 6000000000,
  "end_time": 1699950000
}
```

#### Error Response
- **err::no_auction** (219) - If no active auction exists.
```

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

### Get NFT Data (get_nft_data)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Returns NFT item information following the TON NFT standard. This method allows retrieval of essential NFT details including ownership, metadata, and collection information.

```APIDOC
## GET /get_nft_data

### Description
Returns NFT item information following the TON NFT standard. This method allows retrieval of essential NFT details including ownership, metadata, and collection information.

### Method
GET

### Endpoint
/get_nft_data

### Parameters
#### Query Parameters
- **nft_address** (string) - Required - The address of the NFT item.

### Request Example
```bash
tonlib-cli> runmethod <nft_address> get_nft_data
```

### Response
#### Success Response (200)
- **init** (int) - Indicates if the NFT is initialized (-1 if initialized, 0 if not).
- **item_index** (int) - SHA256 hash of the token name.
- **collection_address** (slice) - The address of the NFT collection.
- **owner_address** (slice) - The current owner's address (zero address if auction active with no owner yet).
- **individual_content** (cell) - The NFT metadata content.

#### Response Example
```json
{
  "init": -1,
  "item_index": "<sha256_hash>",
  "collection_address": "<collection_addr>",
  "owner_address": "<owner_addr>",
  "individual_content": "<content_cell>"
}
```
```

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

### Get Telemint Token Name

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the unique username or token name associated with an NFT item. The name is returned as a slice.

```func
// GET method signature
slice get_telemint_token_name() method_id;

// Returns the token name as a slice (e.g., "durov")

// Example query
// tonlib-cli> runmethod <nft_address> get_telemint_token_name
// Result: "durov"
```

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

### Get Collection Data (get_collection_data)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the NFT collection's metadata according to the TON NFT standard. It returns initialization status, collection content, and the owner address (which is the zero address for Telemint collections).

```func
// GET method signature
(int, cell, slice) get_collection_data() method_id;

// Returns:
// - int: -1 (collection is initialized)
// - cell: Collection content/metadata
// - slice: Owner address (returns zero_address for Telemint)

// Example: Querying via tonlib
// tonlib-cli> runmethod <collection_address> get_collection_data
// Result: [-1, <content_cell>, addr_none]
```

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

### Get NFT Data using TON RPC

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves essential NFT item information according to the TON NFT standard. This method returns the initialization status, item index, collection address, owner address, and individual content metadata.

```ton
// GET method signature
(int, int, slice, slice, cell) get_nft_data() method_id;

// Returns:
// - int: init (-1 if initialized, 0 if not)
// - int: item_index (SHA256 hash of token name)
// - slice: collection_address
// - slice: owner_address (zero if auction active with no owner yet)
// - cell: individual_content (NFT metadata)

// Example query via tonlib
// tonlib-cli> runmethod <nft_address> get_nft_data
// Result: [-1, <index>, <collection_addr>, <owner_addr>, <content_cell>]

```

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

### Get Telemint Auction State

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Retrieves the current state of an active auction, including the highest bidder, bid amount, bid timestamp, minimum next bid, and auction end time. Returns specific error codes if no auction is active.

```func
// GET method signature
(slice, int, int, int, int) get_telemint_auction_state() method_id;

// Returns:
// - slice: bidder_address (current highest bidder, null if no bids)
// - int: bid (current highest bid in nanotons)
// - int: bid_ts (timestamp of highest bid)
// - int: min_bid (minimum amount for next bid in nanotons)
// - int: end_time (auction end timestamp)

// Example query
// tonlib-cli> runmethod <nft_address> get_telemint_auction_state
// Result: [<bidder_addr>, 5000000000, 1699900000, 6000000000, 1699950000]
//         (bidder, 5 TON bid, bid time, min 6 TON next, ends at timestamp)

// Error: err::no_auction (219) if no active auction
```

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

### Telemint Unsigned Deploy Message Structure (Func)

Source: https://github.com/telegrammessenger/telemint/blob/main/README.md

Defines the structure for an unsigned deployment message in Telemint, used for creating an NftItem and initiating an auction. It includes parameters like wallet ID, validity periods, token name, content, auction configuration, and royalty parameters.

```func
// Create an NftItem and start an auction. Signed by auction's private key. Acts as a first bid in the auction.
telemint_unsigned_deploy$_ subwallet_id:uint32 valid_since:uint32 valid_till:uint32 token_name:TelemintText
  content:^Cell auction_config:^TeleitemAuctionConfig royalty_params:(Maybe ^NftRoyaltyParams) = TelemintUnsignedDeploy;
telemint_msg_deploy#4637289a  sig:bits512 msg:TelemintUnsignedDeploy = TelemintMsg;
```

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

### NftCollection - Deploy NFT Item with First Bid

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Initiates an auction for a new username NFT by deploying an NftItem contract and placing the sender's initial bid. Requires a cryptographically signed message with valid timestamps.

```APIDOC
## POST /nftCollection/deploy

### Description
Deploys a new NFT item representing a username and simultaneously initiates an auction with the sender's bid. The message must be cryptographically signed by the auction's private key and include valid timestamps.

### Method
POST

### Endpoint
`/nftCollection/deploy`

### Parameters
#### Request Body
- **signature** (bits512) - Required - Ed25519 signature for the deployment message.
- **msg** (TelemintUnsignedDeploy) - Required - The unsigned deployment message containing auction details.

### Request Body Structure (TelemintUnsignedDeploy)
```
telemint_unsigned_deploy$_
    subwallet_id:uint32       // Collection identifier
    valid_since:uint32        // Signature validity start (unix timestamp)
    valid_till:uint32         // Signature validity end (unix timestamp)
    token_name:TelemintText   // Username being auctioned (e.g., "premium")
    content:^Cell             // NFT metadata content
    auction_config:^TeleitemAuctionConfig  // Auction parameters
    royalty_params:(Maybe ^NftRoyaltyParams)  // Optional royalty override
= TelemintUnsignedDeploy;
```

### Request Example (Conceptual FunC build)
```func
cell build_deploy_message(
    slice signature,
    int subwallet_id,
    int valid_since,
    int valid_till,
    slice token_name,      // e.g., "durov"
    cell content,
    cell auction_config,
    cell royalty_params    // Can be null() for default royalties
) {
    return begin_cell()
        .store_uint(0x4637289a, 32) // op::telemint_msg_deploy
        .store_slice(signature)           // 512 bits
        .store_uint(subwallet_id, 32)     // e.g., 1
        .store_uint(valid_since, 32)      // e.g., now() - 60
        .store_uint(valid_till, 32)       // e.g., now() + 3600
        .store_text(token_name)           // Length-prefixed string
        .store_ref(content)               // NFT metadata
        .store_ref(auction_config)        // Auction parameters
        .store_maybe_ref(royalty_params)  // Optional royalty override
        .end_cell();
}
```

### Auction Configuration Structure (TeleitemAuctionConfig)
```
cell build_auction_config(
    slice beneficiary_address,  // Address receiving auction proceeds
    int initial_min_bid,        // Minimum first bid in nanotons (e.g., 5000000000 = 5 TON)
    int max_bid,                // Instant-win price (0 = disabled)
    int min_bid_step,           // Minimum bid increase percentage (e.g., 5 = 5%)
    int min_extend_time,        // Auction extension on new bid (e.g., 900 = 15 min)
    int duration                // Total auction duration (e.g., 86400 = 24 hours)
) {
    return begin_cell()
        .store_slice(beneficiary_address)
        .store_grams(initial_min_bid)
        .store_grams(max_bid)
        .store_uint(min_bid_step, 8)
        .store_uint(min_extend_time, 32)
        .store_uint(duration, 32)
        .end_cell();
}
```

### Response
#### Success Response (200)
- **transaction_id** (string) - The transaction ID for the deployment operation.
- **nft_address** (string) - The address of the newly deployed NFT item.

#### Response Example
```json
{
  "transaction_id": "<tx_hash>",
  "nft_address": "<nft_item_address>"
}
```
```

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

### Deploy NFT Item V2 with Restrictions

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Deploys an NFT item using the V2 schema, which includes support for sender address restrictions. This is particularly useful for collection variants that require additional bid controls.

```APIDOC
## POST /telemint/deploy/v2

### Description
Deploys an NFT item with enhanced features, including sender address restrictions. This endpoint is used for advanced auction controls.

### Method
POST

### Endpoint
/telemint/deploy/v2

### Parameters
#### Request Body
- **subwallet_id** (uint32) - Required - The subwallet ID for the deployment.
- **valid_since** (uint32) - Required - The timestamp from which the NFT is valid.
- **valid_till** (uint32) - Required - The timestamp until which the NFT is valid.
- **token_name** (TelemintText) - Required - The name of the token.
- **content** (^Cell) - Required - The content of the NFT as a Cell.
- **auction_config** (^TeleitemAuctionConfig) - Required - Configuration for the NFT auction.
- **royalty_params** ((Maybe ^NftRoyaltyParams)) - Optional - Royalty parameters for the NFT.
- **restrictions** ((Maybe ^TelemintRestrictions)) - Optional - Address restrictions for bidding. This can include `force_sender_address` and `rewrite_sender_address`.

### Request Example
```json
{
  "subwallet_id": 123,
  "valid_since": 1678886400,
  "valid_till": 1678972800,
  "token_name": "MyAwesomeNFT",
  "content": "<cell_content_here>",
  "auction_config": "<auction_config_here>",
  "restrictions": {
    "force_sender_address": "<sender_address_here>",
    "rewrite_sender_address": null
  }
}
```

### Response
#### Success Response (200)
- **deployment_message** (string) - The serialized deployment message (BOC).

#### Response Example
```json
{
  "deployment_message": "<boc_encoded_message_here>"
}
```
```

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

### Place Bid on NFT Item (Simple Transfer)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Describes how to place a bid on an NFT item after its initial deployment. Bids are submitted as simple TON transfers to the NFT item's address. The contract automatically validates bids against the current minimum bid and updates auction parameters.

```toncli
// To place a bid, send a simple transfer with empty body or op=0
// The transferred amount becomes the bid

// Example: Placing a 10 TON bid using tonlib
// tonlib-cli> sendfile <wallet_query_boc>
// Where wallet sends 10 TON to <nft_item_address> with empty body

// Bid validation rules:
// - bid >= current min_bid (starts at initial_min_bid)
// - New min_bid = max(bid + 1 TON, bid * (100 + min_bid_step) / 100)
// - Auction extends by min_extend_time if end_time is near
// - Previous bidder receives automatic refund (op::outbid_notification)

// Outbid notification message format
// op::outbid_notification = 0x557cea20
// Sent to previous bidder with their bid amount refunded
```

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

### Top Up Contract Balance

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Allows owners to add TON to the contract's balance to cover storage fees. This is done by sending a transfer with a specific comment.

```APIDOC
## POST /transfer (with comment)

### Description
Owners can add TON to the contract for storage fees.

### Method
POST

### Endpoint
`/transfer`

### Parameters
#### Request Body
- **recipient** (string) - Required - The address of the NFT contract.
- **amount** (integer) - Required - The amount of TON to transfer in nanoTON.
- **comment** (string) - Required - The comment must be `#topup`.

### Description of Action
- This operation is only accepted from the contract owner after the auction has ended.
- Sending TON with the comment `#topup` ensures the contract remains active by covering storage fees.
- Non-owners cannot use this to prevent accidental loss of funds.

#### Example Request Body
```json
{
  "recipient": "<nft_address>",
  "amount": 1000000000, 
  "comment": "#topup"
}
```
```

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

### Deploy NFT Item V2 with Restrictions (telemint_msg_deploy_v2)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Defines the TL-B schema for deploying NFT items with optional sender address restrictions. It includes structures for defining restrictions, unsigned deployment messages, and the final signed deployment message. The `build_restrictions` function demonstrates how to construct the restrictions cell.

```func
// TL-B Schema for V2 deployment with restrictions
telemint_restrictions$_
    force_sender_address:(Maybe MsgAddressInt)    // Required sender address
    rewrite_sender_address:(Maybe MsgAddressInt)  // Override bidder address
= TelemintRestrictions;

telemint_unsigned_deploy_v2$_
    subwallet_id:uint32
    valid_since:uint32
    valid_till:uint32
    token_name:TelemintText
    content:^Cell
    auction_config:^TeleitemAuctionConfig
    royalty_params:(Maybe ^NftRoyaltyParams)
    restrictions:(Maybe ^TelemintRestrictions)  // NEW: Address restrictions
= TelemintUnsignedDeployV2;

telemint_msg_deploy_v2#4637289b
    sig:bits512
    msg:TelemintUnsignedDeployV2
= TelemintMsgV2;

// Operation code
const int op::telemint_msg_deploy_v2 = 0x4637289b;

// Example: Building restrictions cell
cell build_restrictions(
    slice force_sender,    // Must be this address to bid (null = any)
    slice rewrite_sender   // Credit bid to this address instead (null = original sender)
) {
    builder b = begin_cell();
    if (null?(force_sender)) {
        b = b.store_uint(0, 1);  // No force_sender
    } else {
        b = b.store_uint(1, 1).store_slice(force_sender);
    }
    if (null?(rewrite_sender)) {
        b = b.store_uint(0, 1);  // No rewrite_sender
    } else {
        b = b.store_uint(1, 1).store_slice(rewrite_sender);
    }
    return b.end_cell();
}
```

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

### Top Up Contract Balance

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Allows the contract owner to add TON to the contract's balance for storage fees. This is done by sending a transfer with a specific comment, and is only accepted from the owner after the auction has ended to prevent accidental fund loss.

```func
// Send a transfer with comment "#topup"
// Only accepted from the contract owner (after auction ends)

// Example message body:
// op = 0 (simple transfer)
// body = "#topup" (7 bytes)

// This keeps the contract alive by covering storage fees
// Non-owners cannot top up to prevent accidental coin loss
```

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

### NFT Item Bidding

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Details on how to place bids on an NFT item after its initial deployment. Bids are processed as simple TON transfers.

```APIDOC
## POST /nft/bid

### Description
Places a bid on an NFT item. After deployment, bids are submitted as simple TON transfers to the NFT item's address. The contract automatically handles bid processing and validation during active auctions.

### Method
POST

### Endpoint
/nft/bid

### Parameters
#### Request Body
- **nft_item_address** (slice) - Required - The address of the NFT item to bid on.
- **bid_amount** (ton) - Required - The amount of TON to bid.
- **sender_wallet** (slice) - Required - The address of the sender's wallet.

### Request Example
```json
{
  "nft_item_address": "<nft_item_address_here>",
  "bid_amount": "10.5",
  "sender_wallet": "<sender_wallet_address_here>"
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message indicating the bid was processed.
- **transaction_id** (string) - The ID of the transaction used for bidding.

#### Response Example
```json
{
  "status": "Bid placed successfully.",
  "transaction_id": "<transaction_id_here>"
}
```

### Notes
- Bids must meet or exceed the current minimum bid.
- Placing a bid may extend the auction duration if the end time is near.
- If outbid, the previous bidder will receive an automatic refund notification (`op::outbid_notification`).
```

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

### Transfer NFT using Func (TON NFT Standard)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Implements the standard TON NFT transfer operation, used for transferring ownership after an auction concludes. It takes details like the new owner's address, response destination, forward amount, and payload, returning a cell for the transfer message.

```func
// TL-B Schema (TON NFT Standard)
ft_cmd_transfer#5fcc3d14
    query_id:uint64
new_owner:MsgAddress
response_destination:MsgAddress
custom_payload:(Maybe ^Cell)
forward_amount:Grams
forward_payload:(Either Cell ^Cell)
= NftCmd;

// Operation code
const int op::nft_cmd_transfer = 0x5fcc3d14;

// Example: Transferring NFT to new owner
cell build_transfer_message(
    int query_id,
    slice new_owner,              // New owner address
    slice response_destination,   // Address for excess TON refund
    cell custom_payload,          // Optional custom data (null for none)
    int forward_amount,           // TON to forward to new owner
    slice forward_payload         // Data to forward to new owner
) {
    return begin_cell()
        .store_uint(op::nft_cmd_transfer, 32)
        .store_uint(query_id, 64)
        .store_slice(new_owner)
        .store_slice(response_destination)
        .store_maybe_ref(custom_payload)
        .store_grams(forward_amount)
        .store_slice(forward_payload)
        .end_cell();
}

// New owner receives: op::ownership_assigned (0x05138d91)
// Response destination receives: op::excesses (0xd53276db)
// Error codes:
// - err::forbidden_transfer (216): Sender is not the owner
// - err::not_enough_funds (206): Insufficient balance for fees

```

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

### Telemint Data Structures (TL-B Schemas)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Defines the TL-B (Tagless Language) schemas for various data structures used in the Telemint contract, including auction bids, auction states, auction configurations, NFT royalty parameters, token information, NFT item data, and collection data. These schemas are crucial for serialization and deserialization of contract state and messages.

```tl-b
// Auction bid information
teleitem_last_bid
    bidder_address:MsgAddressInt
    bid:Grams
    bid_ts:uint32
= TeleitemLastBid;

// Auction state
teleitem_auction_state$
    last_bid:(Maybe ^TeleitemLastBid)
    min_bid:Grams
    end_time:uint32
= TeleitemAuctionState;

// Auction configuration
teleitem_auction_config$
    beneficiary_address:MsgAddressInt
    initial_min_bid:Grams
    max_bid:Grams
    min_bid_step:uint8
    min_extend_time:uint32
    duration:uint32
= TeleitemAuctionConfig;

// NFT royalty parameters
ft_royalty_params#_
    numerator:uint16
    denominator:uint16
    destination:MsgAddress
= NftRoyaltyParams;

// Token information
telemint_text$_ len:(## 8) text:(bits (len * 8)) = TelemintText;
telemint_token_info$_ name:TelemintText domain:TelemintText = TelemintTokenInfo;

// NFT item data structure
teleitem_config$_ item_index:bits256 collection_address:MsgAddressInt = TeleitemConfig;
teleitem_content$_ nft_content:^Cell dns:DNS_RecordSet token_info:^TelemintTokenInfo = TeleitemContent;
teleitem_state$_ owner_address:MsgAddressInt content:^TeleitemContent
    auction:(Maybe ^TeleitemAuction) royalty_params:^NftRoyaltyParams = TeleitemState;
teleitem_data$_ config:^TeleitemConfig state:(Maybe ^TeleitemState) = TeleitemData;

// Collection data structure
telemint_data$
    touched:Bool
    subwallet_id:uint32
    public_key:bits256
    collection_content:^Cell
    nft_item_code:^Cell
    full_domain:^TelemintText
    royalty_params:^NftRoyaltyParams
= TelemintData;

```

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

### DNS Resolve (dnsresolve)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Handles subdomain queries within a DNS-enabled collection. It resolves a given subdomain and category by returning the NFT item's address as the next DNS resolver, facilitating hierarchical DNS structures.

```func
// GET method signature (only in DNS-enabled collection)
(int, cell) dnsresolve(slice subdomain, int category) method_id;

// Parameters:
// - subdomain: Domain to resolve (e.g., "\0durov\0")
// - category: DNS record category (0 = all)

// Returns:
// - int: Number of bits resolved
// - cell: DNS record (dns_next_resolver pointing to NFT item)

// Example: Resolving "durov.t.me"
// Input subdomain: "\0durov\0" (null-terminated)
// Returns: (48, dns_next_resolver_cell pointing to durov NFT address)
```

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

### Cancel Auction (teleitem_cancel_auction)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Allows the NFT owner to cancel an auction before any bids are placed. This is useful if the owner changes their mind or if there was an error in setting up the auction.

```APIDOC
## POST /teleitem_cancel_auction

### Description
Allows the NFT owner to cancel an auction before any bids are placed. This is useful if the owner changes their mind or if there was an error in setting up the auction.

### Method
POST

### Endpoint
/teleitem_cancel_auction

### Parameters
#### Query Parameters
- **query_id** (int64) - Required - Unique query identifier

### Request Example
```json
{
  "query_id": 54321
}
```

### Response
#### Success Response (200)
- **query_id** (int64) - The query ID associated with the request.
- **status** (string) - Indicates success, typically 'ok'.

#### Response Example
```json
{
  "query_id": 54321,
  "status": "ok"
}
```

#### Error Codes
- **219** (err::no_auction): No active auction.
- **220** (err::forbidden_auction): Sender is not the owner.
- **221** (err::already_has_stakes): Cannot cancel - bids already placed.
```

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

### Transfer NFT (nft_cmd_transfer)

Source: https://context7.com/telegrammessenger/telemint/llms.txt

Standard TON NFT transfer operation for transferring ownership after auction completion or for direct transfers. This endpoint facilitates the secure transfer of NFT ownership.

```APIDOC
## POST /nft_cmd_transfer

### Description
Standard TON NFT transfer operation for transferring ownership after auction completion or for direct transfers. This endpoint facilitates the secure transfer of NFT ownership.

### Method
POST

### Endpoint
/nft_cmd_transfer

### Parameters
#### Query Parameters
- **query_id** (uint64) - Required - Unique query identifier
- **new_owner** (MsgAddress) - Required - The address of the new owner.
- **response_destination** (MsgAddress) - Required - Address for excess TON refund.
- **custom_payload** (Maybe ^Cell) - Optional - Custom data to include with the transfer.
- **forward_amount** (Grams) - Optional - TON to forward to the new owner (defaults to 0).
- **forward_payload** (Either Cell ^Cell) - Optional - Data to forward to the new owner.

### Request Example
```json
{
  "query_id": 98765,
  "new_owner": "<new_owner_address>",
  "response_destination": "<response_destination_address>",
  "custom_payload": null,
  "forward_amount": 1000000000,
  "forward_payload": "<forward_payload_data>"
}
```

### Response
#### Success Response (200)
- **query_id** (uint64) - The query ID associated with the request.
- **status** (string) - Indicates success, typically 'ok'.

#### Response Example
```json
{
  "query_id": 98765,
  "status": "ok"
}
```

#### Error Codes
- **216** (err::forbidden_transfer): Sender is not the owner.
- **206** (err::not_enough_funds): Insufficient balance for fees.
```