js-stellar-sdk

Stellar JS SDK (js-stellar-sdk)

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:

• a networking layer API for Horizon endpoints (REST-based),
• a networking layer for Soroban RPC (JSONRPC-based).
• facilities for building and signing transactions, for communicating with a Stellar Horizon instance, and for submitting transactions or querying network history.

Jump to:

• Installation: details on hitting the ground running
• Usage: links to documentation and a variety of workarounds for non-traditional JavaScript environments
  • ...with React Native
  • ...with Expo
  • ...with CloudFlare Workers
  • ...with Deno
• CLI: generate TypeScript bindings for Stellar smart contracts
• Migrating: migration guides for breaking changes
• Developing: contribute to the project!
• License

Installation

Using npm, pnpm, or yarn to include stellar-sdk in your own project:

npm install --save @stellar/stellar-sdk
# or
pnpm add @stellar/stellar-sdk
# or
yarn add @stellar/stellar-sdk
# or
deno add npm:@stellar/stellar-sdk

Then, require or import it in your JavaScript code:

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

(Preferably, you would only import the pieces you need to enable tree-shaking and lower your final bundle sizes.)

Browsers

You can use a CDN:

Note: Always make sure that you are using the latest version number. They can be found on the releases page in GitHub.

Custom Installation

The default bundle uses a native-fetch HTTP client with no axios dependency. If you need the axios transport (for example, to match the behavior of older SDK versions), set the USE_AXIOS environment variable to true when building.

Build with Axios

pnpm run build:lib:axios

This will create stellar-sdk-axios.js in dist/. Consumers can also import the axios-backed entry from Node via @stellar/stellar-sdk/axios.

Migrating from @stellar/stellar-base

@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.

This only matters if you import @stellar/stellar-base directly. If you depend on @stellar/stellar-sdk and never installed the base package separately, skip this section. The fold-in landed in @stellar/stellar-sdk v16.0.0; on earlier versions the SDK still depends on the separate base package, so don't remove it there.

To migrate:

1. Install @stellar/stellar-sdk if you don't already (see Installation).

2. Update your imports. The symbols you import keep their names, so a project-wide find and replace of "@stellar/stellar-base" with "@stellar/stellar-sdk" usually does it:

   javascript复制

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

3. Uninstall the base package:

   bash复制

   npm uninstall @stellar/stellar-base

Don't keep both packages installed. Two copies of the base library cause confusing runtime errors, such as instanceof checks failing on values that look correct.

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, stellar.toml) and their networking dependencies. In CommonJS environments — where require() can't tree-shake the root barrel — this is noticeably leaner and avoids pulling in dependencies like axios, eventsource, and smol-toml.

Versioning and compatibility

Always use the latest @stellar/stellar-sdk. The Stellar network upgrades its protocol periodically, and an older SDK may fail to decode newer data (for example, newer XDR). 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; Testnet and Futurenet expose their own).

These docs and the API reference cover the latest version only. To read docs for an older version, find its Git tag on the releases page and browse the docs/ directory at that ref on GitHub. The release notes there mark the breaking changes in each version.

Usage

The usage documentation for this library lives in a handful of places:

• across the Stellar Developer Docs, which includes tutorials and examples, and
• on the generated API doc site — which also publishes agent-friendly bundles, raw markdown siblings, and a crawler policy for AI tools. The site's URL, base path, and AI policy values live in config/site.ts.

AI agent documentation

Agents can use the documentation bundles published on the website:

• llms.txt — an index of the guides, reference pages, and other agent-facing docs.
• llms-full.txt — the full documentation corpus plus the changelog in one text file.

These generated bundles are not committed to the repo. To inspect bundles for a local branch, run pnpm docs:llms; the generated files are written under public/ for the website build.

You can also refer to:

• the documentation for the Horizon REST API (if using the Horizon module) and
• the documentation for Soroban RPC's API (if using the rpc module)

Usage with Jest

Some of the SDK's dependencies (@noble/hashes, @noble/ed25519, uint8array-extras, @exodus/bytes) ship only ES modules. Node itself handles this (require(esm) is unflagged from Node 22.12.0, the minimum this SDK supports), but Jest's default transform pipeline does not: tests that load the SDK fail with SyntaxError: Cannot use import statement outside a module coming from inside node_modules.

Tell Jest to transform those packages instead of skipping them:

// jest.config.js
module.exports = {
  transformIgnorePatterns: [
    "node_modules/(?!(\\.pnpm|@noble|@exodus|uint8array-extras)/)",
  ],
};

.pnpm belongs in that list even though it is not a package. Under pnpm the real path is node_modules/.pnpm/@/node_modules//…, so without it the pattern matches at the first node_modules/ segment and the package is skipped before the name is ever compared.

If you compile tests with ts-jest or Babel, also make sure the compilation target is es2020 or later — the SDK and its crypto dependencies use native BigInt, and downleveling below es2020 breaks it at runtime (for example TypeError: Cannot convert a BigInt value to a number).

Usage with React Native

The SDK works in React Native, and as of v17 it no longer needs a Buffer polyfill. The one thing you still need to provide in your app's entry file:

• A Web Crypto random source. Keypair.random() and SEP-10 challenge generation call crypto.getRandomValues(), which React Native doesn't provide out of the box. Add a polyfill that registers it on the global scope, imported once before any SDK code runs.

Modern React Native uses Metro with autolinking, so beyond adding the polyfill above, no manual native linking or custom resolver config is required.

If you use Horizon streaming (server.…().stream()), be aware it depends on an EventSource, which is now an included dependency and will work in any runtimes that support fetch, ReadableStream, TextDecoder, URL, Event, MessageEvent, EventTarget.

React Native apps using the Hermes engine may need to polyfill broken typed array methods such as subarray, since this compatibility is no longer provided by @stellar/js-xdr. If you run into issues, consider a polyfill such as @exodus/patch-broken-hermes-typed-arrays.

Usage with Expo managed workflows

Expo has the same requirement as React Native above — a crypto.getRandomValues() source. Install a polyfill for it (use npx expo install so versions are matched to your Expo SDK) and import it at the top of your entry point (by default App.js) before any SDK code.

Once crypto.getRandomValues() is available, Keypair.random() works normally — the manual expo-random workaround from older Expo SDKs is no longer needed.

Usage with CloudFlare Workers

The SDK defaults to a native-fetch HTTP client, so Horizon and RPC requests work in the Workers runtime without an HTTP adapter. As of v17 the SDK no longer uses Buffer, so the nodejs_compat flag is no longer required for it. The one thing to watch for:

• Streaming. Horizon's .stream() depends on EventSource; long-lived streaming connections don't fit the Workers request model well, so prefer polling (.call() / .cursor()) for Horizon data in a Worker.

Usage with Deno

Deno pulls the SDK in through its npm compatibility layer. Add it to your deno.json (see Installation) and import the bare specifier, or skip that step and import the npm: specifier directly:

import * as StellarSdk from "@stellar/stellar-sdk";
// or, without adding it to deno.json
import * as StellarSdk from "npm:@stellar/stellar-sdk";

Two Deno-specific things to keep in mind:

• Permissions. Horizon and RPC calls need network access, so run with --allow-net (or scope it, e.g. --allow-net=horizon-testnet.stellar.org,soroban-testnet.stellar.org).
• The CLI. Run it without installing anything: deno run -A npm:@stellar/stellar-sdk (see CLI).

CLI

The SDK includes a command-line tool for generating TypeScript bindings from Stellar smart contracts. These bindings provide fully-typed client code with IDE autocompletion and compile-time type checking.

Running the CLI

# Using npx (no installation required)
npx @stellar/stellar-sdk generate [options]

# Or if installed globally
stellar-js generate [options]

Generating Bindings

You can generate bindings from three different sources:

From a local WASM file

npx @stellar/stellar-sdk generate \
  --wasm ./path/to/wasm_file/my_contract.wasm \
  --output-dir ./my-contract-client \
  --contract-name my-contract

From a WASM hash on the network

# testnet, futurenet, and localnet have default RPC URLs
npx @stell