@stellar/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
• CLI: generate TypeScript bindings for Stellar smart contracts
• 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

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:

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

• 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";
  

• 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

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, smol-toml, eventsource) ship only ES modules. Node itself handles this (require(esm) works on all supported Node versions), 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/(?!(@noble|uint8array-extras|smol-toml|eventsource)/)",
  ],
};

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, but its JavaScript runtime doesn't ship a couple of things the SDK expects from Node. You'll need to provide them in your app's entry file:

• A global Buffer. XDR encoding/decoding relies on Buffer. Install a polyfill and assign it to global.Buffer.
• 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 two polyfills 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 two requirements as React Native above — a global Buffer and a crypto.getRandomValues() source. Install polyfills for both (use npx expo install so versions are matched to your Expo SDK) and import them 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. The things to watch for are:

• Node compatibility. The SDK relies on Buffer. Enable the nodejs_compat flag in your wrangler.toml so Node built-ins are available.
• 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.

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 @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,
});

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.

• Clone the repo:

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

• Install Node

Because we support the oldest maintenance version of Node, please install and develop on the version pinned in .nvmrc (currently Node 22) 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

• Enable Corepack

corepack enable

• Install dependencies inside js-stellar-sdk folder:

cd js-stellar-sdk
pnpm install

• 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

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.

Similar packages

Other packages similar to @stellar/stellar-sdk

stellar-sdk

stellar-sdk is another JavaScript library for interacting with the Stellar network. It provides similar functionalities to @stellar/stellar-sdk, such as building and submitting transactions, managing accounts, and accessing the Stellar network. However, @stellar/stellar-sdk is the official SDK maintained by the Stellar Development Foundation, which may offer more up-to-date features and better support.

js-stellar-sdk

js-stellar-sdk is a community-driven library for interacting with the Stellar network. It offers similar capabilities to @stellar/stellar-sdk, including transaction creation and account management. While it may have a different API design, it serves the same purpose of enabling developers to build applications on the Stellar network.