sdk.ton.dns — DNS & Domains - Teleton Agent Documentation

Quick Example

Check availability and resolve a domain

import type { PluginSDK } from "@teleton-agent/sdk";

// Check if a domain is available
const check = await sdk.ton.dns.check("myproject.ton");

if (check.available) {
  console.log("Domain is available! Starting auction...");
  const auction = await sdk.ton.dns.startAuction("myproject.ton");
  console.log(`Auction started with initial bid: ${auction.bidAmount} TON`);
} else {
  console.log(`Taken by: ${check.owner}`);
  console.log(`NFT: ${check.nftAddress}`);
}

// Resolve an existing domain
const resolved = await sdk.ton.dns.resolve("foundation.ton");
if (resolved) {
  console.log(`Wallet: ${resolved.walletAddress}`);
  console.log(`Owner: ${resolved.owner}`);
}

Methods

Method	Returns	Description
`check(domain)`	`Promise<DnsCheckResult>`	Check domain availability, price, and auction status.
`resolve(domain)`	`Promise<DnsResolveResult \| null>`	Resolve a .ton domain to a wallet address. Returns `null` if not found.
`getAuctions(limit?)`	`Promise<DnsAuction[]>`	List active DNS auctions.
`startAuction(domain)`	`Promise<DnsAuctionResult>`	Start a new auction for an unclaimed domain.
`bid(domain, amount)`	`Promise<DnsBidResult>`	Place a bid on an active auction.
`link(domain, address)`	`Promise<void>`	Link a domain you own to a wallet address.
`unlink(domain)`	`Promise<void>`	Remove the wallet link from a domain you own.
`setSiteRecord(domain, adnlAddress)`	`Promise<void>`	Set the TON Site (ADNL) record for a .ton domain you own.

check(domain)

Check whether a .ton domain is available, and if taken, who owns it.

Parameters:

domain (string) — Domain name (e.g. "myproject.ton")

Domain availability check

const result = await sdk.ton.dns.check("wallet.ton");

console.log(`Domain: ${result.domain}`);        // "wallet.ton"
console.log(`Available: ${result.available}`);   // false

if (!result.available) {
  console.log(`Owner: ${result.owner}`);
  console.log(`NFT address: ${result.nftAddress}`);
  console.log(`Linked wallet: ${result.walletAddress}`);
}

resolve(domain)

Resolve a .ton domain to its linked wallet address. Returns null if the domain is not registered.

Parameters:

domain (string) — Domain name (e.g. "foundation.ton")

Domain resolution

const resolved = await sdk.ton.dns.resolve("foundation.ton");

if (resolved) {
  console.log(`Domain: ${resolved.domain}`);
  console.log(`Wallet: ${resolved.walletAddress}`);  // Linked address or null
  console.log(`NFT: ${resolved.nftAddress}`);
  console.log(`Owner: ${resolved.owner}`);
  if (resolved.expirationDate) {
    console.log(`Expires: ${new Date(resolved.expirationDate * 1000).toISOString()}`);
  }

  // Use the resolved address for a transfer
  if (resolved.walletAddress) {
    await sdk.ton.sendTON(resolved.walletAddress, 1.0, "Payment via .ton domain");
  }
} else {
  console.log("Domain not found");
}

getAuctions(limit?)

List currently active DNS auctions on the TON network.

Parameters:

limit (number, optional) — Maximum auctions to return.

Browse active auctions

const auctions = await sdk.ton.dns.getAuctions(10);

for (const auction of auctions) {
  const endsIn = auction.endTime - Math.floor(Date.now() / 1000);
  const hoursLeft = Math.floor(endsIn / 3600);

  console.log(`${auction.domain}`);
  console.log(`  Current bid: ${auction.lastBid} TON (${auction.bids} bids)`);
  console.log(`  Leader: ${auction.owner}`);
  console.log(`  Ends in: ${hoursLeft} hours`);
  console.log(`  NFT: ${auction.nftAddress}`);
}

startAuction(domain)

Start a new auction for an unclaimed .ton domain. This places an initial bid.

Parameters:

domain (string) — Domain to auction (e.g. "newproject.ton")

Start an auction

const result = await sdk.ton.dns.startAuction("newproject.ton");

if (result.success) {
  console.log(`Auction started for ${result.domain}`);
  console.log(`Initial bid: ${result.bidAmount} TON`);
} else {
  console.log("Failed to start auction (domain may be taken or ineligible)");
}

bid(domain, amount)

Place a bid on an active auction. Your bid must exceed the current highest bid.

Parameters:

domain (string) — Domain with active auction
amount (number) — Bid amount in TON

Place a bid

const bid = await sdk.ton.dns.bid("premium-name.ton", 15);

if (bid.success) {
  console.log(`Bid placed: ${bid.bidAmount} TON on ${bid.domain}`);
} else {
  console.log("Bid failed (may be too low or auction ended)");
}

link(domain, address) / unlink(domain)

Link a domain you own to a wallet address, or remove the link.

Parameters (link):

domain (string) — Domain you own
address (string) — TON wallet address to link

Parameters (unlink):

domain (string) — Domain you own

Link and unlink a domain

// Link domain to the bot's own wallet
const myAddress = sdk.ton.getAddress();
if (myAddress) {
  await sdk.ton.dns.link("mybot.ton", myAddress);
  console.log("Domain linked to wallet");
}

// Remove the link
await sdk.ton.dns.unlink("mybot.ton");
console.log("Domain unlinked");

setSiteRecord(domain, adnlAddress)

Set or update the TON Site (ADNL) record for a .ton domain. This allows the domain to point to a TON Site served over the ADNL network.

Parameters:

domain (string) — Domain you own (e.g. "mysite.ton")
adnlAddress (string) — ADNL address of the TON Site node (hex string)

Set ADNL site record

// Point a .ton domain to a TON Site
await sdk.ton.dns.setSiteRecord(
  "mysite.ton",
  "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
);
console.log("TON Site ADNL record set successfully");

Type Definitions

DnsCheckResult

interface DnsCheckResult {
  domain: string;          // e.g. "example.ton"
  available: boolean;      // Whether the domain is available
  owner?: string;          // Current owner address (if taken)
  nftAddress?: string;     // NFT address of the domain
  walletAddress?: string;  // Linked wallet address
  auction?: {              // Active auction info (reserved, see gotchas)
    bids: number;
    lastBid: string;
    endTime: number;
  };
}

DnsResolveResult

interface DnsResolveResult {
  domain: string;                // Domain name
  walletAddress: string | null;  // Linked wallet (null if not set)
  nftAddress: string;            // NFT address of the domain
  owner: string | null;          // Owner address
  expirationDate?: number;       // Expiration (unix timestamp)
}

DnsAuction

interface DnsAuction {
  domain: string;       // Domain name
  nftAddress: string;   // NFT address
  owner: string;        // Current highest bidder
  lastBid: string;      // Current highest bid in TON
  endTime: number;      // Auction end (unix timestamp)
  bids: number;         // Total number of bids
}

DnsAuctionResult

interface DnsAuctionResult {
  domain: string;     // Domain name
  success: boolean;   // Whether auction was started
  bidAmount: string;  // Initial bid amount in TON
}

DnsBidResult

interface DnsBidResult {
  domain: string;     // Domain name
  bidAmount: string;  // Bid amount in TON
  success: boolean;   // Whether bid was placed
}

Gotchas

DnsCheckResult.auction is always undefined at runtime. The auction field is typed but never populated by the API — it will always be undefined at runtime. Do not rely on it.
Domain names include .ton — always pass the full domain name including the .ton suffix (e.g. "myproject.ton").
You must own the domain to call link(), unlink(), or setSiteRecord(). These operations require the bot's wallet to be the domain owner.
Auction bids are irreversible — TON sent for bids is locked until the auction ends. If you are outbid, your TON is returned.
resolve() returns null if the domain does not exist. It returns a result with walletAddress: null if the domain exists but has no wallet linked.

Auction Flow

The typical flow for acquiring a new .ton domain:

Auction lifecycle

  check(domain)
       |
       v
  available? ----NO---> Domain is taken. Check owner/wallet.
       |
      YES
       |
       v
  startAuction(domain)    <-- Places initial bid, starts timer
       |
       v
  bid(domain, amount)     <-- Other participants can bid too
       |                       Each bid extends the auction
       v
  Auction ends            <-- Highest bidder wins the domain NFT
       |
       v
  link(domain, address)   <-- Link your wallet to the domain
       |
       v
  setSiteRecord(...)      <-- Optionally point to a TON Site

Complete Example: Domain Registration Flow

Full domain registration plugin

import type { PluginSDK } from "@teleton-agent/sdk";

export default {
  name: "domain-manager",
  version: "1.0.0",
  tools: [
    {
      name: "register_domain",
      description: "Check and start auction for a .ton domain",
      parameters: {
        type: "object",
        properties: {
          domain: { type: "string", description: "Domain name (e.g. mysite.ton)" },
        },
        required: ["domain"],
      },
      execute: async (args: { domain: string }, sdk: PluginSDK) => {
        // Ensure .ton suffix
        const domain = args.domain.endsWith(".ton")
          ? args.domain
          : `${args.domain}.ton`;

        // Step 1: Check availability
        const check = await sdk.ton.dns.check(domain);

        if (!check.available) {
          // Domain is taken — resolve for details
          const resolved = await sdk.ton.dns.resolve(domain);
          return {
            available: false,
            domain: check.domain,
            owner: check.owner,
            wallet: resolved?.walletAddress ?? "not linked",
            nft: check.nftAddress,
          };
        }

        // Step 2: Check wallet balance for bidding
        const balance = await sdk.ton.getBalance();
        if (!balance || parseFloat(balance.balance) < 2) {
          return { error: "Need at least 2 TON to start an auction" };
        }

        // Step 3: Start the auction
        const auction = await sdk.ton.dns.startAuction(domain);

        if (!auction.success) {
          return { error: `Failed to start auction for ${domain}` };
        }

        return {
          success: true,
          domain: auction.domain,
          initialBid: auction.bidAmount,
          message: `Auction started for ${domain} with bid of ${auction.bidAmount} TON. Monitor with getAuctions().`,
        };
      },
    },
    {
      name: "setup_domain",
      description: "Link wallet and optionally set ADNL record for a domain",
      parameters: {
        type: "object",
        properties: {
          domain: { type: "string", description: "Domain you own" },
          adnlAddress: { type: "string", description: "ADNL address for TON Site (optional)" },
        },
        required: ["domain"],
      },
      execute: async (args: { domain: string; adnlAddress?: string }, sdk: PluginSDK) => {
        const address = sdk.ton.getAddress();
        if (!address) return { error: "Wallet not initialized" };

        // Link domain to bot's wallet
        await sdk.ton.dns.link(args.domain, address);

        // Optionally set ADNL record
        if (args.adnlAddress) {
          await sdk.ton.dns.setSiteRecord(args.domain, args.adnlAddress);
        }

        // Verify
        const resolved = await sdk.ton.dns.resolve(args.domain);

        return {
          domain: args.domain,
          linkedWallet: resolved?.walletAddress,
          adnlSet: !!args.adnlAddress,
        };
      },
    },
  ],
};