js-stellar-sdk: the JavaScript client for Horizon and Soroban RPC

Two network surfaces, one library

js-stellar-sdk is a JavaScript library for communicating with a Stellar Horizon server and Stellar RPC. While primarily intended for applications built on Node.js or in the browser, it can be adapted for use in other environments with some tinkering.

The library provides three things. A networking layer API for Horizon endpoints, which are REST-based. A networking layer for Soroban RPC, which is JSONRPC-based. And facilities for building and signing transactions, for communicating with a Stellar Horizon instance, and for submitting transactions or querying network history.

Having both network layers in one package is the point, because Stellar's architecture has two quite different services. Horizon is the indexer and the historical API: accounts, payments, offers, and the transaction history. Soroban RPC is the contract execution path, reached over JSONRPC with a different request and response shape. An application that does both, which is most applications that touch smart contracts, would otherwise need two client libraries with two different error handling and authentication conventions.

The readme also points at a set of workarounds for non-traditional JavaScript environments, with dedicated sections for React Native, Expo managed workflows, Cloudflare Workers and Deno. That list is a good summary of where this kind of library is awkward, since each of those environments has a different idea of what fetch, streams and package resolution mean.

The author is the Stellar Development Foundation, the licence is Apache-2.0, and the published package is @stellar/stellar-sdk at version 17.2.1.

Installing it, and the four package managers

The installation section lists npm, pnpm and yarn, and the package is included in your own project with one command:

npm install --save @stellar/stellar-sdk

The alternatives are the same package under the other managers, including Deno, which installs it through npm compatibility:

pnpm add @stellar/stellar-sdk

deno add npm:@stellar/stellar-sdk

Then you require or import it:

var StellarSdk = require("@stellar/stellar-sdk");
// or
import * as StellarSdk from "@stellar/stellar-sdk";

The readme adds a note that matters for bundle size. Preferably, you would only import the pieces you need to enable tree-shaking and lower your final bundle sizes. That is a general remark about barrel files, but the package layout makes it a real option, because the exports map in the manifest defines separate entry points for the root, /base, /contract and /rpc, each with its own types, import and require conditions, so a bundler can drop the parts you never import.

For browsers there is a CDN route, with a script tag pointing at a versioned file on cdnjs, and a note to always make sure you use the latest version number, which can be found on the releases page in GitHub.

The manifest shows the build outputs behind those entry points, with a CommonJS build at lib/cjs, an ES module build at lib/esm, types at lib/esm/index.d.ts, and the package declared as an ES module with pnpm 10.34.6 as its package manager.

The /base subpath, and the stellar-base fold-in

Two changes in the 16 and 17 lines reshaped what you import, and both are worth understanding before you upgrade.

The first is that @stellar/stellar-base is now folded into @stellar/stellar-sdk. Its classes and functions are bundled in and re-exported from the top level, so the SDK is the only package you need.

The migration is mechanical if you imported the base package directly. Update your imports, and the symbols keep their names, so a project-wide find and replace of the old package name with the new one usually does it:

// before
import { Keypair, TransactionBuilder, Asset } from "@stellar/stellar-base";

// after
import { Keypair, TransactionBuilder, Asset } from "@stellar/stellar-sdk";

Then uninstall the base package, with npm uninstall @stellar/stellar-base. The readme is emphatic about this: don't keep both packages installed, because two copies of the base library cause confusing runtime errors, such as instanceof checks failing on values that look correct. That is the classic duplicated-class-identity failure, and it is a nasty one to debug because the values are correct and the check still fails.

The second change is the /base subpath, and it is the more interesting one for a specific use case. If you only use the offline primitives, StrKey, Keypair, TransactionBuilder, xdr and friends, you can import them from the /base subpath instead of the package root:

import { StrKey, Keypair } from "@stellar/stellar-sdk/base";

This loads only the former stellar-base modules, skipping Horizon, RPC and the SEP helpers, federation, web auth and stellar.toml, along with their networking dependencies. The readme notes that in CommonJS environments, where require cannot tree-shake the root barrel, this is noticeably leaner and avoids pulling in dependencies like axios, eventsource and smol-toml.

So there is a real trade here. The root import is the simple path. The /base import is the path for an offline signer, a hardware wallet integration or a key generation service that has no business holding a network client at all.

The version policy, and why protocol version matters

The versioning section is short and carries an operational message that is easy to miss.

Use either the latest version, v17, or v16 of @stellar/stellar-sdk depending on your migration needs. Version 16 remains supported through March 2027 for protocol compatibility and security fixes.

Then the reason: the Stellar network upgrades its protocol periodically, and older unsupported SDK versions may fail to decode newer data, for example newer XDR. And there is a concrete way to check what you are dealing with. You can check the protocol a network currently runs in the current_protocol_version field of its Horizon root, for example horizon.stellar.org for Mainnet, with Testnet and Futurenet exposing their own.

That is the failure mode to understand. It is not a build error and not a type error. It is a decoder in an old library meeting a struct layout it has never seen, and the symptom is a runtime failure on data that is perfectly valid on the network. Which is why the readme tells you to check the protocol version rather than only the package version.

Two support lines are in flight, and the release history shows them moving together. v17.2.0 on 2026-09-28, v17.2.1 on 2026-10-01, and v16.3.1 on 2026-10-01. The last push was on 2026-10-19.

The documentation policy is stated too. The docs and the API reference cover the latest version only, and to read docs for an older version you find its Git tag on the releases page and browse the docs directory at that ref on GitHub, where the release notes mark the breaking changes in each version. A dedicated RELEASE_POLICY.md and a CHANGELOG.md are in the repository root.

The build is where the XDR comes from

The Makefile in the repository root documents how the library stays in step with the protocol, and it is the most revealing file in the project.

The xdr/xdr.json file is the canonical schema graph consumed by tools/xdrgen/generate.mjs, which emits the classes in src/xdr/generated/. It is produced by the generator-definitions-json tool from stellar/rs-stellar-xdr, run over the protocol .x files fetched from stellar/stellar-xdr at the commit pinned in the variable XDR_COMMIT. The generator is built and run inside the Docker image pinned by RUST_IMAGE, so regenerating only needs docker, curl and pnpm.

The three targets are make for the whole regeneration, make xdr-json for the schema graph only, and make xdr-classes for the generated classes only via pnpm run xdrgen.

The pinned commits are in the file, with XDR_COMMIT set to a specific commit on the stellar-xdr repository and RS_XDR_REF set to a commit on the rs-stellar-xdr repository.

The comment about feature gating is the part that shows real protocol work. Taking a new protocol snapshot means bumping the pinned commit and rerunning make. Protocol changes that upstream still gates behind a CAP conditional are excluded unless their feature symbols are listed in XDR_FEATURES, which is a comma separated lowercase list, so individual gated CAPs can be cherry-picked, and once upstream ungates a CAP it is always included.

There is a subtlety in the recorded checksums, documented in the notes. The recorded per-file sha256 values are computed by the generator over content with the conditional blocks and all whitespace stripped, not the raw bytes, so the hashes are stable across formatting changes in the upstream files.

For a consumer this matters only indirectly, but it matters a lot for a contributor. The XDR layer is not hand written, it is generated from the protocol definitions, and the generation is pinned and reproducible.

The CLI, the agent docs and the subpath exports

Several smaller surfaces round out the package, and two of them are unusual.

The first is the CLI. The readme describes it as generating TypeScript bindings for Stellar smart contracts, and the manifest registers three bin entries: stellar-js, stellar-sdk, and stellar-contract-bindings-typescript, all pointing at scripts under bin. A second entry point on the package, the /contract subpath in the exports map, gives the contract-facing modules their own importable surface alongside the root, /base and /rpc entries.

The second unusual surface is the AI agent documentation. The generated API doc site publishes agent-friendly bundles, raw markdown siblings, and a crawler policy for AI tools, and the site's URL, base path and AI policy values live in config/site.ts. There is an llms.txt that is an index of the guides, reference pages and other agent-facing docs, and an llms-full.txt sibling. The doc site is built with Astro, given the astro.config.mjs at the root, and the TypeDoc configuration lives in typedoc.json.

The readme also says the usage documentation lives in two places, across the Stellar Developer Docs, which includes tutorials and examples, and on the generated API doc site.

The practical read is that this project treats documentation as a published artefact with formats for machines, not just a page for humans. For a library whose consumers are increasingly automated, that is a reasonable bet, and it does not change the code, but it does mean the docs are versioned alongside the package.

The repository also carries a .semgrepignore and a .socket-basics.json, which are the usual markers of a project that runs supply chain scanning on its own dependencies, and a .husky directory for git hooks.

Where this SDK is the wrong choice

There are cases where pulling in this library is the wrong decision, and the readme is honest about most of them.

The first is a browser application that only signs. If all you do is generate a keypair and produce a signed transaction for someone else to submit, then the root import brings Horizon, RPC, the SEP helpers and their networking dependencies along with it. The /base subpath exists precisely for that case, and using the root there is a mistake that costs bundle size for nothing.

The second is a non-JavaScript target with a different runtime. The readme says the library is primarily intended for applications built on Node.js or in the browser and can be adapted for other environments with some tinkering. If you are in one of the listed environments, React Native, Expo, Cloudflare Workers or Deno, expect to read those sections before you start, because each has a specific friction point.

The third is a project that will outlive the supported versions. Two lines are supported, v16 and v17, and v16 stops receiving protocol compatibility and security fixes in March 2027. If your application has a multi year life, that date is in your planning, not just in the release notes.

The fourth is the axios transport question. The default bundle uses a native fetch HTTP client with no axios dependency, and if you need the axios transport, for example to match the behavior of older SDK versions, you set the USE_AXIOS environment variable to true when building and the build produces a separate stellar-sdk-axios.js in dist, importable from Node via the /axios subpath. That is a build-time choice, not a runtime one, so it belongs in your build configuration rather than in application code.

And the fifth is a project that does not need Stellar at all, which the readme is quietly sarcastic about. The advice to want to watch a video in the terminal but not use mpv or vlc because they are too mainstream comes from a different project, and the tone does not carry over. What does carry over is the principle: pick the tool whose scope matches the problem, because this library's scope is large.

Editorial conclusion

Adopt js-stellar-sdk if you are building on Stellar from JavaScript or TypeScript, since it covers both the Horizon REST surface and the Soroban JSONRPC surface, and the /base subpath keeps an offline signing tool from dragging in the network stack. Skip it if you are on an older major and cannot move yet, since only v16 and v17 are supported, and remember v16 stops receiving fixes in March 2027. Verify first that your Stellar network's protocol version is one your SDK version can decode, by checking the current_protocol_version field of the Horizon root, and decide which of the two supported majors you are targeting before you pin.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. stellar/js-stellar-sdk on GitHub