SNS SDKs

Official SDKs, React hooks, a CLI, and an experimental REST proxy for integrating with Solana Name Service (SNS).

Documentation

The complete SDK and API documentation is available at dev.sns.id. For general SNS guides, visit guide.sns.id.

This README is an integration overview. Use the developer documentation and package-specific guides for complete API details.

Choose an integration

| Integration | Use it for | Guide | | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------- | | JavaScript SDK | TypeScript or JavaScript applications using @solana/web3.js 1.x | JavaScript SDK | | JS Kit SDK | TypeScript applications using @solana/kit on Node.js 24+ | JS Kit SDK | | Rust SDK | Async or blocking Rust applications on the Solana 2.1 client stack | Rust SDK | | React hooks | React 18 or 19 applications using the JavaScript SDK and React Query | React hooks | | CLI | Mainnet SNS reads and administration from a terminal | CLI | | REST proxy (experimental) | HTTP integrations that cannot use a native SDK | REST proxy |

JavaScript SDK

Use the JavaScript SDK with applications built on @solana/web3.js 1.x.

npm install @bonfida/spl-name-service @solana/web3.js

import { safeResolve } from "@bonfida/spl-name-service/domain";
import { Connection } from "@solana/web3.js";
const connection = new Connection("https://your-rpc-endpoint.example"); const owner = await safeResolve(connection, "mydomain.sns");

See the JavaScript SDK package guide and v4 migration guide.

JS Kit SDK

Use JS Kit SDK with applications built on @solana/kit. It requires Node.js 24 or later.

npm install @solana-name-service/sns-sdk-kit @solana/kit

import { resolve } from "@solana-name-service/sns-sdk-kit/domain";
import {
  createDefaultRpcTransport,
  createSolanaRpcFromTransport,
} from "@solana/kit";
const transport = createDefaultRpcTransport({   url: "https://your-rpc-endpoint.example", }); const rpc = createSolanaRpcFromTransport(transport);
const owner = await resolve({ rpc, domain: "mydomain.sns" }); // Or use safeResolve.

See the JS Kit package guide and v1 migration guide.

Rust SDK

The Rust SDK provides asynchronous APIs by default. Enable its blocking feature when synchronous APIs are required.

cargo add sns-sdk

Given a solanaclient::nonblocking::rpcclient::RpcClient named client:

use snssdk::nonblocking::resolve::{resolve, AllowPda};
let owner = resolve(&client, "mydomain.sns", AllowPda::Deny).await?; // Or use safe_resolve.

See the Rust SDK package guide and v2 migration guide.

CLI

Install the published CLI crate. It provides the sns executable.

cargo install sns-cli

sns resolve mydomain.sns

Run sns --help for the current command list and sns <command> --help for command-specific options.

See the CLI guide for runtime configuration, domain rules, and the complete command reference.

REST proxy

Experimental: The REST proxy is provided for integrations that cannot use a native SDK. Its availability and API may change.

All application routes use GET.
The /resolve/:domain and /safe-resolve/:domain routes require a full domain name ending in .sns or .sol, for example mydomain.sns or mydomain.sol.
All other routes that accept a domain name assume an .sns domain and require a TLD-less value. Pass mydomain or sub.mydomain, not mydomain.sns.

Available endpoints:

Resolution: /resolve/:domain, /safe-resolve/:domain
Domains and ownership: /domain-key/:domain, /domains/:owner, /primary-domain/:owner, /multiple-primary-domains/:owners, /reverse-key/:domain, /reverse-lookup/:pubkey, /subdomains/:parent
Compatibility aliases: /favorite-domain/:owner, /multiple-favorite-domains/:owners
Records: /types/record, /record-key-v2/:domain/:record, /record-v2/:domain/:record, /records-v2/:domain?records=<csv>
Instruction construction: /register, /create-subdomain

See the REST proxy guide for query parameters, request conventions, response and error types, RPC overrides, deprecated routes, and operational considerations.

React hooks

@bonfida/sns-react provides React Query hooks for SNS data in applications using @solana/web3.js.

npm install @bonfida/sns-react @bonfida/spl-name-service@^4.0.0 @solana/web3.js@^1.98.2 @tanstack/react-query@^5.0.0 react

Wrap the application in TanStack Query's QueryClientProvider before using the hooks.

import { useResolve } from "@bonfida/sns-react";
import type { Connection } from "@solana/web3.js";
export function Resolve({ connection }: { connection: Connection }) {   const { data, isPending } = useResolve(connection, "mydomain.sns");
if (isPending) return <span>Loading...</span>;   return <span>{data?.toBase58() ?? "Not found"}</span>; }

Use useSafeResolve when callers require the JavaScript SDK's safe-resolution consistency check.

See the React hooks package guide for peer dependencies and available hooks.