| name | sui-sdks |
| description | Sui SDK landscape — which SDK to pick (TypeScript, Rust, or community-maintained Python/Go/Dart/Kotlin/Swift), how they map to each other, and how to install and wire each one up. Use when a user is starting a new Sui project in any language, migrating between languages, comparing APIs across SDKs, or asking "what SDK should I use for X?". For deep patterns inside a single SDK, route to that SDK's reference file.
|
Sui SDKs
MCP tool: When available in your environment, also query the Sui documentation MCP server (https://sui.mcp.kapa.ai) for up-to-date answers. Use it for verification and for details not covered by these reference files.
Most AI agents give confusing, outdated, or cross-wired answers about Sui SDKs. This skill fixes the three most common failure modes:
- Recommending a community SDK as if it were official. Only two SDKs are maintained by Mysten Labs: TypeScript (
@mysten/sui) and Rust (sui-rust-sdk family of crates). Everything else is community-maintained.
- Mixing up TypeScript SDK generations. The old
@mysten/sui.js package was renamed to @mysten/sui at v1.0. The v2 client API (client.core.*, include instead of show*, SuiGrpcClient replacing SuiClient) is distinct from v1.
- Not using the installed LLM docs. Every
@mysten/* package ships docs/llms-index.md + topic-specific markdown files to node_modules. Agents should read those before answering; they are guaranteed to match the installed version.
All patterns in this skill are derived from:
If unsure about any specific API in any SDK, fetch from the relevant doc page — do not extrapolate from a different SDK's surface.
Reference files
typescript — TypeScript SDK (@mysten/sui v2)
Path: typescript.md
Load when: writing, reviewing, or migrating TypeScript/JavaScript code that imports @mysten/sui, constructing PTBs in TS, choosing between SuiGrpcClient / SuiJsonRpcClient / SuiGraphQLClient, using the v2 Core API, or migrating from SDK v1 (@mysten/sui.js).
Covers: install, imports, client classes and when to use each, v2 Core API, PTB construction, pure/object inputs, coinWithBalance intent, execution & status checking, waitForTransaction, keypairs, offline building, sponsored transactions, v1→v2 migration table, $extend pattern for kiosk/suins/deepbook/walrus/seal/zksend.
rust — Rust SDK (sui-* crates)
Path: rust.md
Load when: writing Rust code that interacts with Sui — CLI tools, backend services, validators, indexers. Also when choosing between the new modular crates and the legacy in-monorepo sui-sdk crate.
Covers: the five crates (sui-sdk-types, sui-crypto, sui-rpc, sui-graphql, sui-transaction-builder), TransactionBuilder API with an end-to-end example, signing via sui-crypto, gRPC client from sui-rpc, relationship to the legacy sui-sdk crate, and the "intents" feature flag (high-level Coin / Balance intents).
community — Community SDKs (Python, Go, Dart, Kotlin, Swift, Vue)
Path: community.md
Load when: a user asks about or is using a non-TS-non-Rust SDK. Also when assessing risk for a language choice (maintainer responsiveness, feature gaps vs official SDKs).
Covers: for each community SDK — repo, maintainer, install, what's supported/not, caveats, and a recommendation on whether to use it or call the Rust/TS SDK from an FFI wrapper instead.
mapping — Cross-SDK operation mapping
Path: mapping.md
Load when: porting code from one SDK to another, writing a polyglot reference, or answering "how do I do X in SDK Y".
Covers: side-by-side tables mapping the 10-or-so core Sui operations (build PTB, split gas, moveCall, transfer, sign & execute, wait, query object / owned objects / balance, dry-run) across the TS and Rust SDKs, with syntactic parallels.
llm-docs — Using bundled docs from node_modules
Path: llm-docs.md
Load when: the agent needs authoritative, version-matched TypeScript API docs before writing code. Always check node_modules/@mysten/*/docs/llms-index.md first if it exists.
Covers: the docs/llms-index.md convention, which @mysten/* packages ship it, how to read the index and target pages, how to wire it into AGENTS.md / CLAUDE.md for a project.
Routing guide
| Task | Load |
|---|
| "Which SDK should I use?" | (this file) + mapping |
| Writing TS/JS code against Sui | typescript + llm-docs |
| Writing Rust code against Sui | rust |
| Using pysui / ksui / suikit / sui-go / mofalabs/sui | community |
| User mentions Go / Python / Dart / Kotlin / Swift / Vue (even casually, e.g. "my team uses Go") | community (always — language constraint trumps perf recommendations) |
| Porting between languages | mapping + (target SDK file) |
Migrating from @mysten/sui.js / SDK v1 | typescript |
| Frontend / React integration | route to frontend-apps skill first (covers React hooks, wallet connection, query patterns), then typescript here for Transaction construction |
| PTB semantics deep dive | route to ptbs skill, then language-specific file here |
| Data access patterns (gRPC vs GraphQL vs indexer) | route to accessing-data skill |
| Full project setup | all reference files (or the SDK-specific one + llm-docs) |
| Code review | all reference files |
Skill Content
Key concepts
- Two officially-supported SDKs. TypeScript (
@mysten/sui) and Rust (sui-rust-sdk crates). Both are maintained by Mysten Labs and updated alongside protocol changes. For performance-critical paths in non-Rust languages, sui-rust-sdk can be called via FFI (Foreign Function Interface) from Python, Go, Swift, etc., giving those languages access to the official SDK without relying on community wrappers.
- Everything else is community. Python (
pysui), Go (block-vision/sui-go-sdk), Dart (mofalabs/sui), Kotlin (mcxross/ksui), Swift (opendive/suikit), Vue (SuiFansCN/suiue). They typically lag protocol updates and feature coverage varies. Treat them as best-effort.
- The TS SDK has two client generations. v1 used
SuiClient + @mysten/sui.js. v2 uses SuiGrpcClient / SuiJsonRpcClient / SuiGraphQLClient from @mysten/sui. JSON-RPC is deprecated; gRPC is recommended for new code.
- The Rust SDK has two generations. The new modular crates (
sui-sdk-types, sui-crypto, sui-rpc, sui-transaction-builder) are the recommended surface. The "legacy Rust SDK" is the monolithic sui-sdk crate in the sui monorepo; it supports JSON-RPC with forward/backward compatibility and is still used by many existing projects, but is not the recommended target for new code.
- Every
@mysten/* package ships LLM-ready docs. Look for node_modules/@mysten/sui/docs/llms-index.md and follow its pointers before asking the user to clarify APIs. Matches the installed version exactly.
- Frameworks on top of SDKs.
@mysten/dapp-kit-react (React wallet integration; @mysten/dapp-kit-core for Vue/vanilla/Svelte/Web Components), @mysten/kiosk, @mysten/suins, @mysten/deepbook-v3, @mysten/walrus, @mysten/seal, @mysten/zksend, @mysten/enoki — all are thin layers over @mysten/sui. The Mysten extensions integrate via the v2 client.$extend(...) pattern; dApp Kit does not (it's a React framework, not a client extension — see frontend-apps skill). The bare @mysten/dapp-kit package name is the deprecated JSON-RPC-only predecessor.
Rules
- Default to TypeScript or Rust, but respect language constraints. For any new Sui project, recommend TypeScript (
@mysten/sui) or Rust (sui-rust-sdk crates) — unless the user has named a language (Go, Python, Dart, Kotlin, Swift, Vue) or said "my team uses X". Then community.md is the load: name the canonical community SDK (block-vision/sui-go-sdk for Go, pysui for Python, etc.), flag the staleness risk, and offer FFI-to-Rust as a fallback. Do not recommend TypeScript or Rust as a replacement language when the user has stated their team's language. For example, if the user says "my team uses Go", do not suggest rewriting in TypeScript — recommend the Go community SDK and/or Rust via FFI.
- For TypeScript, always use
@mysten/sui, never @mysten/sui.js. The .js-suffixed package is frozen at v1 and will not receive updates. Legacy code using it should be migrated.
- For TypeScript v2, use
SuiGrpcClient by default. SuiJsonRpcClient exists for legacy compatibility; SuiGraphQLClient is for specialized query flows. See typescript.md for the decision.
- For Rust, prefer
sui-rust-sdk crates over the legacy monorepo sui-sdk. Import sui-transaction-builder, sui-sdk-types, sui-crypto, sui-rpc individually — pay only for what you use.
- Check
node_modules/@mysten/*/docs/llms-index.md before writing TS code. If the project has @mysten/sui installed, those docs are the authoritative, version-matched source. Read the index, then the targeted page.
- Do not mix v1 and v2 TS patterns. Code that uses
SuiClient, TransactionBlock, getFullnodeUrl, options: { showEffects }, signAndExecuteTransactionBlock, or result.effects?.status?.status is v1. Migrate wholesale or keep everything on v1 — a half-migrated file is a bug surface.
- Community SDK caveat is mandatory. When recommending or using a community SDK, mention that it's community-maintained and may lag protocol updates. Check the repo's last commit and latest Sui version support before relying on it.
- Frameworks integrate via
$extend() in v2. client.$extend(suins(), deepbook({ address })) is the v2 pattern. Do not instantiate SuinsClient or DeepBookClient directly — that's the v1 style.
- Route frontend questions to the
frontend-apps skill. When the user asks about React hooks, wallet connection, or dApp Kit query patterns, explicitly direct them to the frontend-apps skill for hook-level details. This skill covers SDK selection and Transaction construction only.
- Cite the docs when unsure. Official TS SDK docs live at
sdk.mystenlabs.com. The inventory list lives at docs.sui.io/references/sui-sdks. Rust SDK docs live on docs.rs (per-crate) and mystenlabs.github.io/sui-rust-sdk/<crate_name>/ (e.g., /sui_transaction_builder/).
Common mistakes
- Calling a community SDK "the Python SDK" or "the Go SDK" as if official. There is no official Python or Go SDK. Name the specific package (
pysui, block-vision/sui-go-sdk) and flag it as community.
- Telling users
SuiClient is the recommended client. That was v1. v2 uses SuiGrpcClient (or SuiJsonRpcClient for legacy flows).
- Recommending
@mysten/sui.js. Deprecated package name. Always @mysten/sui.
- Confusing the two Rust SDKs. The new
sui-rust-sdk crates (on crates.io as separate crates like sui-sdk-types / sui-transaction-builder / sui-rpc) are distinct from the legacy sui-sdk crate in the sui monorepo. New code should use the former.
- Fetching TS docs from the web when they're installed locally. If the project has
@mysten/sui installed, read node_modules/@mysten/sui/docs/llms-index.md instead — it matches the installed version.
- Hardcoding a specific SDK version. SDK APIs evolve. Prefer "install the latest
@mysten/sui" and then consult the bundled docs, rather than pinning advice to a version.
- Recommending
@mysten/dapp-kit for backend code. dApp Kit is a React-oriented frontend framework. Backend or CLI code should use @mysten/sui directly.
- Providing React hook details instead of routing to the
frontend-apps skill. When a user asks about React hooks, wallet connection patterns, or dApp Kit query patterns, do not answer with hook-level code from this skill. Instead, explicitly tell the user: "For React hook details, see the frontend-apps skill." This skill covers SDK selection and Transaction construction only — the frontend-apps skill has the hook-level guidance.
- Using JSON-RPC as the default for any client. JSON-RPC is deprecated for the TS SDK; the legacy Rust SDK supports it but the new Rust SDK does not. Default to gRPC.
