SNS SDKs

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

Contents

• Documentation
• Choose an integration
• JS Kit
• JavaScript SDK
• Rust SDK
• CLI
• REST proxy
• React hooks
• Compatibility and migration
• Repository map
• License

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 solana_client::nonblocking::rpc_client::RpcClient named client:

use sns_sdk::non_blocking::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.

Compatibility and migration

Domain behavior and public APIs can change between major versions. Review the relevant migration guide when upgrading:

• JavaScript SDK v4 migration guide
• JS Kit v1 migration guide
• Rust SDK v2 migration guide
• React hooks v4 migration guide

Repository map

• js/: JavaScript SDK for @solana/web3.js 1.x (guide)
• js-kit/: JavaScript SDK for @solana/kit (guide)
• rust-crates/sns-sdk/: Rust SDK (guide)
• rust-crates/sns-cli/: sns command-line application (guide)
• sdk-proxy/: Experimental Cloudflare Worker REST proxy (guide)
• react/: React hooks for SNS (guide)

License

This project is available under the MIT License.