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:

<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>

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:

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

3. Uninstall the base package:

   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

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. The Stellar network upgrades its protocol periodically, and older unsupported SDK versions 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/<pkg>@<version>/node_modules/<pkg>/…, 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]

Stellar CLI plugin

When the SDK is installed globally it also registers a stellar-contract-bindings-typescript binary. This follows the Stellar CLI plugin convention: the CLI discovers any executable on your PATH named stellar-* and exposes it as a subcommand. The binary maps directly onto stellar-js generate, forwarding every option unchanged, so the flags documented below apply identically.

Note that the Stellar CLI currently ships its own native stellar contract bindings typescript command (now deprecated). While that built-in command exists it takes precedence over the plugin. Once the CLI drops its native implementation, stellar contract bindings typescript (and the dashed stellar contract-bindings-typescript) will resolve to this plugin.

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 @stellar/stellar-sdk generate \
  --wasm-hash <hex-encoded-hash> \
  --network testnet \
  --output-dir ./my-contract-client \
  --contract-name my-contract

From a deployed contract ID

npx @stellar/stellar-sdk generate \
  --contract-id CABC...XYZ \
  --network testnet \
  --output-dir ./my-contract-client

With custom RPC server options

For mainnet or when connecting to RPC servers that require authentication:

# Mainnet requires --rpc-url (no default)
npx @stellar/stellar-sdk generate \
  --contract-id CABC...XYZ \
  --rpc-url https://my-rpc-provider.com \
  --network mainnet \
  --output-dir ./my-contract-client

# With custom timeout and headers for authenticated RPC servers
npx @stellar/stellar-sdk generate \
  --contract-id CABC...XYZ \
  --rpc-url https://my-rpc-server.com \
  --network mainnet \
  --output-dir ./my-contract-client \
  --timeout 30000 \
  --headers '{"Authorization": "Bearer my-token"}'

# localnet with default RPC URL auto-enables --allow-http
npx @stellar/stellar-sdk generate \
  --contract-id CABC...XYZ \
  --network localnet \
  --output-dir ./my-contract-client

# When overriding the default URL, you must specify --allow-http if using HTTP
npx @stellar/stellar-sdk generate \
  --contract-id CABC...XYZ \
  --rpc-url http://my-local-server:8000/rpc \
  --network localnet \
  --output-dir ./my-contract-client \
  --allow-http

CLI Options

Option	Description
--wasm <path>	Path to a local WASM file
--wasm-hash <hash>	Hex-encoded hash of WASM blob on the network
--contract-id <id>	Contract ID of a deployed contract
--rpc-url <url>	Stellar RPC server URL (has defaults for testnet/futurenet/localnet, required for mainnet)
--network <network>	Network to use: testnet, mainnet, futurenet, or localnet (required for network sources)
--output-dir <dir>	Output directory for generated bindings (required)
--contract-name <name>	Name for the generated package (derived from filename if not provided)
--overwrite	Overwrite existing files in the output directory
--allow-http	Allow insecure HTTP connections to RPC server (default: false)
--timeout <ms>	RPC request timeout in milliseconds
--headers <json>	Custom headers as JSON object (e.g., '{"Authorization": "Bearer token"}')

Default RPC URLs

When using --network, the CLI provides default RPC URLs for most networks:

Network	Default RPC URL
testnet	https://soroban-testnet.stellar.org
futurenet	https://rpc-futurenet.stellar.org
localnet	http://localhost:8000/rpc (auto-enables --allow-http only when using default URL)
mainnet	None - you must provide --rpc-url (find providers)

Generated Output

The CLI generates a complete npm package structure:

my-contract-client/
├── src/
│   ├── index.ts      # Barrel exports
│   ├── client.ts     # Typed Client class with contract methods
│   └── types.ts      # TypeScript interfaces for contract types
├── package.json
├── tsconfig.json
├── README.md
└── .gitignore

Using Generated Bindings

After generating, you can use the bindings in your project:

import { Client } from "./my-contract-client";

const client = new Client({
  contractId: "CABC...XYZ",
  networkPassphrase: Networks.TESTNET,
  rpcUrl: "https://soroban-testnet.stellar.org",
  publicKey: keypair.publicKey(),
  ...basicNodeSigner(keypair, Networks.TESTNET),
});

// Fully typed method calls with IDE autocompletion
const result = await client.transfer({
  from: "GABC...",
  to: "GDEF...",
  amount: 1000n,
});

Migrating

Upgrading from an earlier version? The Migration Guide lists every breaking change by SDK version, newest first, and links to the deep-dive guides for the largest ones.

Developing

So you want to contribute to the library: welcome! Whether you’re working on a fork or want to make an upstream request, the dev-test loop is pretty straightforward.

1. Clone the repo:

git clone https://github.com/stellar/js-stellar-sdk.git

2. Install Node

Because we support the oldest maintenance version of Node, please install and develop on the version pinned in .nvmrc (currently Node 22; the minimum supported is 22.12.0) so you don’t get surprised when your code works locally but breaks in CI.

Here’s how to install nvm if you haven’t: https://github.com/creationix/nvm

nvm install

If you work on several projects that use different Node versions, you might it helpful to install this automatic version manager: https://github.com/wbyoung/avn

3. Enable Corepack

corepack enable

4. Install dependencies inside js-stellar-sdk folder:

cd js-stellar-sdk
pnpm install

5. Observe the project’s code style

While you’re making changes, make sure to run the linter to catch any linting errors (in addition to making sure your text editor supports ESLint) and conform to the project’s code style.

pnpm run fmt

Building

You can build the developer version (unoptimized, commented, with source maps, etc.) or the production bundles:

pnpm run build
# or
pnpm run build:prod

Testing

To run all tests:

pnpm run test

To run a specific set of tests:

pnpm run test:node
pnpm run test:browser
pnpm run test:integration

To generate and check the documentation site:

# generate the docs site (reference pages, llms bundles, and the Astro site under dist/site)
pnpm run docs

# preview the built site in a browser
pnpm docs:preview

# the preview server prints the local URL (default http://localhost:4321)

# for a live-reloading dev server instead, use:
pnpm docs:dev

Release & support policy

See RELEASE_POLICY.md for how the SDK is versioned, how long each release line is supported, and the table of currently supported versions.

To report a vulnerability, see SECURITY.md.

Publishing

For information on how to contribute or publish new versions of this software to npm, please refer to our contribution guide.

Miscellaneous

License

js-stellar-sdk is licensed under an Apache-2.0 license. See the LICENSE file for details.