@webdom/sdk

v0.1.6

Published

14 days ago

TypeScript SDK for Webdom agent API and contract transaction builders

Downloads

301

0High
0Medium
0Low

webdom

webdom ton sdk cli marketplace domains

Webdom Agent SDK

Agent skills & TypeScript SDK for the Webdom Agent API, Webdom transaction builders, and low-level smart contracts helpers.

Overview

TON DNS is one of the clearest on-chain narratives in the TON ecosystem outside of Telegram-native NFTs. The market has shown renewed momentum in 2026: February 2026 was the strongest month for .ton mint volume at roughly 282k TON, surpassed only by August 2022 during the initial TON DNS release. Secondary market activity has accelerated as well. As of March 23, 2026, .ton secondary sales have already reached more than 22.8k TON for the month, making March 2026 the second-strongest month on record for secondary market volume and roughly 3x the average monthly secondary volume over the prior 12 months.

This repository provides AI agents and developers with seamless access to the TON DNS ecosystem. With these tools, agents can easily discover domains, check ownership and market status, authenticate using TON wallets, and prepare transactions for buying, selling, bidding, renewing, and managing domains — enabling all the actions of a real user.

Short demo

https://github.com/user-attachments/assets/846cbfd2-012b-46e0-97d8-553a401d174b

Installation

npm install -g @webdom/sdk
npx skills add webdom-market/sdk

Quick Start

import { createWebdomSdk } from '@webdom/sdk';

const sdk = createWebdomSdk();

const domains = await sdk.api.catalog.listDomains({
    search: 'gold',
    domain_zone: 'ton',
    limit: 5
});

console.log(domains.items.map((domain) => domain.name));

const labels = await sdk.api.catalog.listAvailableDomainLabels({
    regex: '^[a-z]{4}$',
    limit: 5,
    has_letter: true
});

console.log(labels.labels);
console.log(labels.items[0]?.category, labels.items[0]?.tags);

const details = await sdk.api.domains.get({
    domain_name: 'example.ton'
});

console.log(details.owner);

Surface

createWebdomSdk() returns an isolated SDK instance with these namespaces:

sdk.api
sdk.raw
sdk.auth
sdk.balances
sdk.tx
sdk.context

Each SDK instance keeps its own API base URL, token storage, fetch implementation, TON client, and contract addresses.

Configuration

import { createWebdomSdk } from '@webdom/sdk';

const sdk = createWebdomSdk({
    apiBaseUrl: 'https://webdom.market/api/agent/v1',
    toncenterEndpoint: 'https://mainnet-v4.tonhubapi.com',
    tokenStorage: {
        async getToken() {
            return process.env.WEBDOM_AGENT_TOKEN ?? null;
        },
        async setToken(token) {
            process.env.WEBDOM_AGENT_TOKEN = token ?? '';
        }
    },
    contracts: {
        marketplace: 'EQD7-a6WPtb7w5VgoUfHJmMvakNFgitXPk3sEM8Gf_WEBDOM'
    }
});

Defaults:

apiBaseUrl: https://webdom.market/api/agent/v1
toncenterEndpoint: https://mainnet-v4.tonhubapi.com
built-in Webdom contract addresses
per-instance in-memory token storage

Authentication

The auth client manages the TON Proof flow and token persistence for one SDK instance.

const token = await sdk.auth.authenticate({
    mnemonic: process.env.WALLET_MNEMONIC!.split(' '),
    walletVersion: 'v4r2'
});

console.log(token.access_token);

If the signature is produced outside the SDK, exchange the external proof directly:

const challenge = await sdk.auth.getTonProofPayload();

const token = await sdk.auth.exchangeTonProofForToken({
    challenge_id: challenge.challenge_id,
    wallet_address: 'UQ...',
    wallet_public_key: 'deadbeef',
    proof: externalProof
});

Token helpers:

await sdk.auth.setToken('existing-token');
console.log(await sdk.auth.getToken());
await sdk.auth.clearToken();

Advanced auth helpers live under @webdom/sdk/auth:

import { signTonProof, buildTonProofTokenExchangeRequest } from '@webdom/sdk/auth';

High-Level vs Raw API

High-level namespaces unwrap data, page_info, and meta:

const result = await sdk.api.catalog.listDomains({ limit: 10 });
console.log(result.items, result.pageInfo, result.meta);

const availableLabels = await sdk.api.catalog.listAvailableDomainLabels({
    regex: '^gold',
    limit: 10
});
console.log(availableLabels.labels, availableLabels.filterOptions);
console.log(availableLabels.items, availableLabels.pageInfo, availableLabels.meta);

const marketplaceConfig = await sdk.api.marketplace.getConfig();
console.log(marketplaceConfig.deploy_configs);

Raw namespaces preserve the original API envelope:

const envelope = await sdk.raw.catalog.listDomains({ limit: 10 });
console.log(envelope.data.items, envelope.meta.request_id);

const rawAvailableLabels = await sdk.raw.catalog.listAvailableDomainLabels({
    regex: '^[a-z]{4}$',
    limit: 10
});
console.log(rawAvailableLabels.data.items, rawAvailableLabels.data.filter_options, rawAvailableLabels.page_info);

const rawMarketplaceConfig = await sdk.raw.marketplace.getConfig();
console.log(rawMarketplaceConfig.data.deploy_configs);

Transactions

Transaction builders are grouped by domain:

sdk.tx.domains
sdk.tx.sales
sdk.tx.auctions
sdk.tx.offers
sdk.tx.swaps
sdk.tx.marketplace
sdk.tx.nft

Each builder returns a PreparedTransaction with TonConnect-ready messages:

const tx = await sdk.tx.sales.purchaseTonSimple({
    saleAddress: 'EQ...'
});

console.log(tx.messages);

Advanced tx helpers are also available via:

import { createTxClient } from '@webdom/sdk/tx';

Sending Transactions With `@ton/mcp@alpha`

The SDK only prepares transaction data. To actually sign and send that transaction to TON, pass PreparedTransaction.messages into the raw CLI command @ton/mcp@alpha send_raw_transaction.

Minimal flow:

Build the transaction with webdom or sdk.tx.*
Take the messages array from the result
Pass that array to npx -y @ton/mcp@alpha send_raw_transaction --messages ...
Poll get_transaction_status with the returned normalizedHash

Example:

export MNEMONIC="word1 word2 ..."

TX_JSON=$(webdom build-purchase-tx --sale-address EQ... --price 70000000000000)
MESSAGES=$(echo "$TX_JSON" | jq -c '.messages')

HASH=$(
  npx -y @ton/mcp@alpha send_raw_transaction \
    --messages "$MESSAGES" \
  | jq -r '.normalizedHash'
)

npx -y @ton/mcp@alpha get_transaction_status --normalizedHash "$HASH"

send_raw_transaction accepts the same message fields that the SDK already returns: address, amount, payload, and optional stateInit. The extra SDK fields such as meta and queryId are not part of the broadcast request.

If MNEMONIC or PRIVATE_KEY is not set, @ton/mcp@alpha uses the local TON config registry at ~/.config/ton/config.json. In that mode you can also pass --walletSelector to choose a specific wallet.

Where to read more:

@ton/mcp README: https://github.com/ton-connect/kit/blob/main/packages/mcp/README.md
install TON skills for an agent: npx skills add ton-connect/kit/packages/mcp

CLI

The CLI has two layers:

workflow commands optimized for humans and AI agents
low-level namespace.method commands for full API coverage

Workflow examples:

webdom find-domain --query gold --limit 5
webdom find-domain --regex '^gold.*\\.ton$' --limit 5
webdom find-available-labels --regex '^[a-z]{4}$' --limit 5
webdom find-available-labels --regex '^ton' --has-letter true --first-char t
webdom get-domain --domain example.ton
webdom get-wallet-balances --address UQ...
webdom build-purchase-tx --sale-address EQ... --price 1500000000
webdom build-sale-tx --user-address UQ... --domain-address EQ... --domain-name example.ton --currency USDT --price 1000000000 --valid-until 1767225600
webdom build-offer-tx --domain-name example.ton --seller-address UQ... --currency TON --price 1000000000 --valid-until 1767225600
webdom build-auction-tx --user-address UQ... --domain-address EQ... --domain-name example.ton --currency TON --start-time 1766620800 --end-time 1767225600 --min-bid-value 1000000000 --max-bid-value 100000000000 --min-bid-increment 5 --time-increment 300

Low-level examples:

webdom catalog.list-domains --search gold --limit 5
webdom catalog.list-domains --regex '^gold.*\\.ton$' --limit 5
webdom catalog.list-available-domain-labels --regex '^[a-z]{4}$' --limit 5
webdom domains.get --domain-name example.ton
webdom marketplace.config
webdom auth.authenticate
webdom auth.token.get

By default the CLI persists tokens in ~/.config/webdom/agent-token. Override it with --token-file or WEBDOM_AGENT_TOKEN_FILE.

Agent-oriented features:

webdom commands
webdom schema find-domain
webdom help domains.get
echo '{"domain":"example.ton"}' | webdom get-domain --input -
webdom find-domain --query gold --select items --jsonl

Defaults:

success responses are compact JSON on stdout
errors are structured JSON on stderr
--pretty enables formatted JSON
--input - reads JSON params from stdin
--select path.to.field extracts a nested value before printing
--jsonl emits arrays as one JSON object per line

Use webdom help <command> for human help, webdom schema <command> for machine-readable metadata, or webdom commands to inspect the full command catalog. Yout can find more examples in EXAMPLES.md

Entry Points

The package uses a focused root export plus explicit advanced entrypoints:

@webdom/sdk: createWebdomSdk, config helpers, WebdomApiError, toNano, fromNano
@webdom/sdk/api: raw and high-level API factories/types
@webdom/sdk/auth: TON Proof helpers and auth client exports
@webdom/sdk/tx: transaction client exports
@webdom/sdk/contracts: low-level contract helpers
@webdom/sdk/types: generated API schema types
@webdom/sdk/cli: CLI runner and command metadata

Rate Limits

The Agent API applies rate limits to every endpoint.

authenticated requests: 5 RPS with burst 20, limited both per wallet and per client IP
unauthenticated requests: 1 RPS per client IP

When a limit is exceeded, the API returns 429 Too Many Requests and includes standard retry metadata in headers such as Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Scope.

If you need higher limits, contact t.me/domainer.