@pizzaton/dotton

Official SDK for dotTON (https://dot.tongo.run)

Installation

npm install @pizzaton/dotton

Quick Start

import DotTON from "@pizzaton/dotton";

const dotton = new DotTON({
  baseUrl: "https://dot.tongo.run/api/subs",
  network: "mainnet",
  // bearer token from /api/login/verifyPayload for protected endpoints
  authToken: process.env.DOTTON_TOKEN,
});

const platforms = await dotton.getPlatforms();
console.log(platforms.result?.platforms);

Initialization

const dotton = new DotTON({
  baseUrl?: string;        // default: https://dot.tongo.run/api/subs
  authBaseUrl?: string;    // default: inferred from baseUrl (usually .../api)
  authToken?: string;      // bearer token for protected routes
  apiKey?: string;         // deprecated alias for authToken
  network?: "mainnet" | "testnet";
  timeout?: number;        // default: 30000
  defaultHeaders?: Record<string, string>;
});

You can also set/update auth and network at runtime:

dotton.setAuthToken("...");
dotton.setNetwork("testnet");

Response Shape

Routes return the API envelope:

{
  ok: boolean | 0 | 1;
  result: T | undefined;
  code?: number;
  message?: string;
}

On request failures, SDK throws DotTONError with:

• message
• statusCode
• code (API error code, when present)
• data (raw payload)

API Methods

Auth (/api/login/*)

• generateLoginPayload()
• verifyLoginPayload(payload) (stores returned token automatically)

Platform

• getPlatforms()
• getTopDomains()
• searchDomains(query)
• findByName(query)
• getManager(domainName)
• getSubdomain(domainName, subdomainName)
• getDomainsPage({ page?, sort?, q? })

Manager

• getManagerList(platform, offset?, limit?)
• getManagerSubdomains(manager, offset?, limit?)
• findDomainAddressByName(platform, domainName)
• buySubdomain(manager, subdomainName)

User (Protected: Bearer token required)

• getUserManagers(adminAddress)
• getUserSubdomains(adminAddress)

Backward-compatible signatures with offset/limit still exist but are ignored by the new API.

Linker (Protected)

• getMyLinks()
• updateLink(domain, destination) (destination = null removes mapping)
• pullExternalLinks(domains)

Network Selection

Network is passed using API query params compatible with the Next.js backend:

• Global: new DotTON({ network: "testnet" })
• Per request: every method accepts optional requestOptions with { network }

Major Version Notes (v1.0.0)

This release aligns SDK contracts with the Next.js API implementation in sub-dns-app:

• manager/findDomainAddressByName path is used (old getDomainAddressByName path removed).
• buySubdomain now returns amount (not value).
• manager/subdomains returns { subdomains } (legacy manager/pagination payload removed).
• User endpoints are bearer-protected and return non-paginated lists.
• Platform payload now uses nft_transfer_fee and includes version.

Development

• Build: npm run build
• Example: examples/usage.ts

License

MIT