Developer GuideSDK Reference

SDK Reference

The X1NS TypeScript SDK provides a simple and type-safe way to interact with X1NS programmatically.

Installation

Quick Start

import { Connection } from '@solana/web3.js';
import {
  resolveDomain,
  getPrimaryDomain,
  isDomainAvailable,
  createSubdomain
} from '@x1ns/sdk';
 
// Create connection
const connection = new Connection('https://rpc.mainnet.x1.xyz');
 
// Resolve a domain
const owner = await resolveDomain(connection, 'alice.x1', 'mainnet');
console.log('Owner:', owner?.toBase58());
 
// Check availability
const available = await isDomainAvailable(connection, 'newdomain.x1', 'mainnet');
console.log('Available:', available);
 
// Get primary domain
const primary = await getPrimaryDomain(connection, ownerAddress, 'mainnet');
console.log('Primary domain:', primary);

Core Functions

resolveDomain()

Resolve a domain name to its owner address.

import { resolveDomain } from '@x1ns/sdk';
 
const owner = await resolveDomain(
  connection,      // Connection
  'alice.x1',      // Domain name
  'mainnet'        // Network: 'mainnet' | 'testnet'
);
 
if (owner) {
  console.log('Domain owner:', owner.toBase58());
} else {
  console.log('Domain not found (available)');
}

Parameters:

  • connection: Solana/X1 Connection object
  • domain: Full domain name (e.g., alice.x1)
  • network: Network to query ('mainnet' or 'testnet')

Returns: PublicKey | null - Owner’s public key or null if not found

isDomainAvailable()

Check if a domain is available for registration.

import { isDomainAvailable } from '@x1ns/sdk';
 
const available = await isDomainAvailable(
  connection,
  'newdomain.x1',
  'mainnet'
);
 
if (available) {
  console.log('Domain is available!');
} else {
  console.log('Domain is already registered');
}

Parameters:

  • connection: Solana/X1 Connection object
  • domain: Full domain name to check
  • network: Network to query

Returns: boolean - true if available, false if taken

getPrimaryDomain()

Get the primary domain set by a wallet owner.

import { getPrimaryDomain } from '@x1ns/sdk';
import { PublicKey } from '@solana/web3.js';
 
const ownerAddress = new PublicKey('X1abc123...');
 
const primaryDomain = await getPrimaryDomain(
  connection,
  ownerAddress,
  'mainnet'
);
 
console.log('Primary domain:', primaryDomain); // "alice.x1" or null

Parameters:

  • connection: Solana/X1 Connection object
  • owner: Owner’s PublicKey
  • network: Network to query

Returns: string | null - Primary domain name or null

getUserDomains()

Get all domains owned by an address (reverse lookup).

import { getUserDomains } from '@x1ns/sdk';
 
const domains = await getUserDomains(
  connection,
  ownerAddress,
  'mainnet'
);
 
console.log('Owned domains:', domains);
// [{ name: 'alice.x1', address: PublicKey }, ...]

Parameters:

  • connection: Solana/X1 Connection object
  • owner: Owner’s PublicKey
  • network: Network to query

Returns: Array<{ name: string, address: PublicKey }> - List of owned domains

Subdomain Functions

createSubdomainInstruction()

Create an instruction for creating a subdomain.

import { createSubdomainInstruction } from '@x1ns/sdk';
import { Transaction, sendAndConfirmTransaction } from '@solana/web3.js';
 
const instruction = await createSubdomainInstruction(
  connection,
  wallet.publicKey,     // Payer
  'wallet.alice.x1',    // Full subdomain name
  wallet.publicKey,     // Subdomain owner
  'mainnet'
);
 
const transaction = new Transaction().add(instruction);
const signature = await sendAndConfirmTransaction(connection, transaction, [wallet]);
console.log('Subdomain created:', signature);

Parameters:

  • connection: Solana/X1 Connection object
  • payer: PublicKey of transaction payer
  • subdomain: Full subdomain name (e.g., wallet.alice.x1)
  • owner: PublicKey of subdomain owner
  • network: Network

Returns: TransactionInstruction - Instruction to add to transaction

createSubdomain()

Create a subdomain (sends transaction).

import { createSubdomain } from '@x1ns/sdk';
 
const signature = await createSubdomain(
  connection,
  wallet,              // Wallet with signTransaction method
  'pay.alice.x1',     // Subdomain to create
  wallet.publicKey,   // Owner of subdomain
  'mainnet'
);
 
console.log('Created subdomain:', signature);

Parameters:

  • connection: Solana/X1 Connection object
  • wallet: Wallet object with signTransaction method
  • subdomain: Full subdomain name
  • owner: PublicKey of subdomain owner
  • network: Network

Returns: Promise<string> - Transaction signature

resolveSubdomain()

Resolve a subdomain to its owner.

import { resolveSubdomain } from '@x1ns/sdk';
 
const owner = await resolveSubdomain(
  connection,
  'wallet.alice.x1',
  'mainnet'
);
 
console.log('Subdomain owner:', owner?.toBase58());

Parameters:

  • connection: Solana/X1 Connection object
  • subdomain: Full subdomain name
  • network: Network

Returns: PublicKey | null - Owner’s public key or null

isSubdomainAvailable()

Check if a subdomain is available.

import { isSubdomainAvailable } from '@x1ns/sdk';
 
const available = await isSubdomainAvailable(
  connection,
  'new.alice.x1',
  'mainnet'
);
 
console.log('Subdomain available:', available);

Parameters:

  • connection: Solana/X1 Connection object
  • subdomain: Full subdomain name
  • network: Network

Returns: boolean - Availability status

Helper Functions

getSplNameServiceProgramId()

Get the SPL Name Service program ID for a network.

import { getSplNameServiceProgramId } from '@x1ns/sdk';
 
const programId = getSplNameServiceProgramId('mainnet');
console.log('Program ID:', programId.toBase58());

Returns: PublicKey - SPL Name Service program ID

getTldRootDomain()

Get the root domain account for a TLD.

import { getTldRootDomain } from '@x1ns/sdk';
 
const rootDomain = getTldRootDomain('x1', 'mainnet');
console.log('Root domain:', rootDomain.toBase58());

Parameters:

  • tld: TLD name ('x1', 'xnt', or 'xen')
  • network: Network

Returns: PublicKey - Root domain account

getCentralStateAddress()

Get the central state PDA address.

import { getCentralStateAddress } from '@x1ns/sdk';
 
const centralState = getCentralStateAddress('mainnet');
console.log('Central state:', centralState.toBase58());

Returns: PublicKey - Central state PDA

TypeScript Types

Domain

interface Domain {
  name: string;        // Full domain name (e.g., "alice.x1")
  address: PublicKey;  // Domain account address
}

Network

type Network = 'mainnet' | 'testnet';

TldLabel

type TldLabel = 'x1' | 'xnt' | 'xen';

Complete Examples

Resolve Domain with Error Handling

import { Connection, PublicKey } from '@solana/web3.js';
import { resolveDomain } from '@x1ns/sdk';
 
async function safeResolve(domain: string): Promise<PublicKey | null> {
  try {
    const connection = new Connection('https://rpc.mainnet.x1.xyz');
    const owner = await resolveDomain(connection, domain, 'mainnet');
    
    if (owner) {
      console.log(`✅ ${domain} → ${owner.toBase58()}`);
      return owner;
    } else {
      console.log(`❌ ${domain} is not registered`);
      return null;
    }
  } catch (error) {
    console.error(`Error resolving ${domain}:`, error);
    return null;
  }
}

Check Multiple Domains

import { isDomainAvailable } from '@x1ns/sdk';
 
async function checkBatch(domains: string[]) {
  const connection = new Connection('https://rpc.mainnet.x1.xyz');
  
  const results = await Promise.all(
    domains.map(async (domain) => ({
      domain,
      available: await isDomainAvailable(connection, domain, 'mainnet')
    }))
  );
  
  console.table(results);
}
 
checkBatch(['alice.x1', 'bob.x1', 'crypto.x1']);

Create Subdomain with Wallet

import { useWallet, useConnection } from '@solana/wallet-adapter-react';
import { createSubdomain } from '@x1ns/sdk';
 
function CreateSubdomainButton() {
  const { connection } = useConnection();
  const wallet = useWallet();
  
  const handleCreate = async () => {
    if (!wallet.publicKey) {
      alert('Connect wallet first!');
      return;
    }
    
    try {
      const sig = await createSubdomain(
        connection,
        wallet as any,
        'pay.alice.x1',
        wallet.publicKey,
        'mainnet'
      );
      
      console.log('Created subdomain:', sig);
      alert('Subdomain created successfully!');
    } catch (error) {
      console.error('Error:', error);
      alert('Failed to create subdomain');
    }
  };
  
  return <button onClick={handleCreate}>Create Subdomain</button>;
}

Constants Package

Install the constants package for shared values:

npm install @x1ns/constants
import {
  MAINNET_PROGRAM_ID,
  TESTNET_PROGRAM_ID,
  MAINNET_TLD_ROOTS,
  TESTNET_TLD_ROOTS
} from '@x1ns/constants';
 
console.log('Mainnet .x1 root:', MAINNET_TLD_ROOTS.x1);

Error Handling

The SDK throws errors for invalid inputs:

try {
  const owner = await resolveDomain(connection, 'invalid', 'mainnet');
} catch (error) {
  if (error.message.includes('Invalid domain format')) {
    console.log('Domain format is invalid');
  } else if (error.message.includes('Network error')) {
    console.log('Failed to connect to RPC');
  } else {
    console.log('Unknown error:', error);
  }
}

Next Steps

Support

Domain NamesAPI Reference