@stellar/stellar-sdk
Advanced tools
A library for working with the Stellar network, including communication with the Horizon and Soroban RPC servers.
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:
Jump to:
stellar-sdk vs. stellar-baseUsing npm or yarn to include stellar-sdk in your own project:
npm install --save @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.)
You can use a CDN:
<script src="https://cdnjs.cloudflare.com/ajax/libs/stellar-sdk/{version}/stellar-sdk.js"></script>
Note that this method relies on using a third party to host the JS library. This may not be entirely secure. You can self-host it via Bower:
bower install @stellar/stellar-sdk
and include it in the browser:
<script src="./bower_components/stellar-sdk/stellar-sdk.js"></script>
<script>
console.log(StellarSdk);
</script>
If you don't want to use or install Bower, you can copy the packaged JS files from the Bower repo, or just build the package yourself locally (see Developing :arrow_right: Building) and copy the bundle.
| Always make sure that you are using the latest version number. They can be found on the releases page in GitHub. |
|---|
You can configure whether or not to build the browser bundle with the axios dependency. In order to turn off the axios dependency, set the USE_AXIOS environment variable to false. You can also turn off the eventsource dependency by setting USE_EVENTSOURCE to false.
npm run build:browser:no-axios
This will create stellar-sdk-no-axios.js in dist/.
npm run build:browser:no-eventsource
This will create stellar-sdk-no-eventsource.js in dist/.
npm run build:browser:minimal
This will create stellar-sdk-minimal.js in dist/.
The usage documentation for this library lives in a handful of places:
You can also refer to:
Horizon module) andrpc module)yarn add --dev rn-nodeifyyarn rn-nodeify --install url,events,https,http,util,stream,crypto,vm,buffer --hack --yarn
require('crypto') on shim.jsreact-native link react-native-randombytesrn-cli.config.jsmodule.exports = {
resolver: {
extraNodeModules: require("node-libs-react-native"),
},
};
import "./shim"; to the top of index.jsyarn add @stellar/stellar-sdkThere is also a sample that you can follow.
Note: Only the V8 compiler (on Android) and JSC (on iOS) have proper support for Buffer and Uint8Array as is needed by this library. Otherwise, you may see bizarre errors when doing XDR encoding/decoding such as source not specified.
yarn add --dev rn-nodeifyyarn rn-nodeify --install process,url,events,https,http,util,stream,crypto,vm,buffer --hack --yarn
import "./shim"; to your app's entry point (by default ./App.js)yarn add @stellar/stellar-sdkexpo install expo-randomAt this point, the Stellar SDK will work, except that StellarSdk.Keypair.random() will throw an error. To work around this, you can create your own method to generate a random keypair like this:
import * as Random from 'expo-random';
import { Keypair } from '@stellar/stellar-sdk';
const generateRandomKeypair = () => {
const randomBytes = Random.getRandomBytes(32);
return Keypair.fromRawEd25519Seed(Buffer.from(randomBytes));
};
Both eventsource (needed for streaming) and axios (needed for making HTTP requests) are problematic dependencies in the CFW environment. The experimental branch make-eventsource-optional is an attempt to resolve these issues.
It requires the following additional tweaks to your project:
axios-fetch-adapter lets you use axios with fetch as a backend, which is available to CF workersaxios@"<= 1.0.0" versions, so we need to force an override into the underlying dependencyyarn versions, so we need to force the environment to use Yarn 1In summary, the package.json tweaks look something like this:
"dependencies": {
// ...
"@stellar/stellar-sdk": "git+https://github.com/stellar/js-stellar-sdk#make-eventsource-optional",
"@vespaiach/axios-fetch-adapter": "^0.3.1",
"axios": "^0.26.1"
},
"overrides": {
"@stellar/stellar-sdk": {
"axios": "$axios"
}
},
"packageManager": "yarn@1.22.19"
Then, you need to override the adapter in your codebase:
import { Horizon } from '@stellar/stellar-sdk';
import fetchAdapter from '@vespaiach/axios-fetch-adapter';
Horizon.AxiosClient.defaults.adapter = fetchAdapter as any;
// then, the rest of your code...
All HTTP calls will use fetch, now, meaning it should work in the CloudFlare Worker environment.
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.
# Using npx (no installation required)
npx @stellar/stellar-sdk generate [options]
# Or if installed globally
stellar-js generate [options]
You can generate bindings from three different sources:
npx @stellar/stellar-sdk generate \
--wasm ./path/to/wasm_file/my_contract.wasm \
--output-dir ./my-contract-client \
--contract-name my-contract
# 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
npx @stellar/stellar-sdk generate \
--contract-id CABC...XYZ \
--network testnet \
--output-dir ./my-contract-client
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
| 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"}') |
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) |
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
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,
});
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.
git clone https://github.com/stellar/js-stellar-sdk.git
cd js-stellar-sdk
yarn
Because we support the oldest maintenance version of Node, please install and develop on Node 20 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 20
# if you've never installed 18 before you'll want to re-install yarn
npm install -g yarn
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
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.
yarn fmt
You can build the developer version (unoptimized, commented, with source maps, etc.) or the production bundles:
yarn build
# or
yarn build:prod
To run all tests:
yarn test
To run a specific set of tests:
yarn test:node
yarn test:browser
yarn test:integration
In order to have a faster test loop, these suite-specific commands do not build the bundles first (unlike yarn test). If you make code changes, you will need to run yarn build (or a subset like yarn build:node corresponding to the test suite) before running the tests again to see your changes.
To generate and check the documentation site:
# install the `serve` command if you don't have it already
npm i -g serve
# clone the base library for complete docs
git clone https://github.com/stellar/js-stellar-base
# generate the docs files
yarn docs
# get these files working in a browser
cd jsdoc && serve .
# you'll be able to browse the docs at http://localhost:5000
For information on how to contribute or publish new versions of this software to npm, please refer to our contribution guide.
stellar-sdk vs stellar-basestellar-sdk is a high-level library that serves as client-side API for Horizon and Soroban RPC, while `stellar-base is lower-level library for creating Stellar primitive constructs via XDR helpers and wrappers.
Most people will want stellar-sdk instead of stellar-base. You should only use stellar-base if you know what you're doing!
If you add stellar-sdk to a project, do not add stellar-base! Mismatching versions could cause weird, hard-to-find bugs. stellar-sdk automatically installs stellar-base and exposes all of its exports in case you need them.
Important! The Node.js version of the
stellar-base(stellar-sdkdependency) package uses thesodium-nativepackage as an optional dependency.sodium-nativeis a low level binding to libsodium, (an implementation of Ed25519 signatures). If installation ofsodium-nativefails, or it is unavailable,stellar-base(andstellar-sdk) will fallback to using thetweetnaclpackage implementation. If you are using them in a browser, you can ignore this. However, for production backend deployments, you should be usingsodium-native. Ifsodium-nativeis successfully installed and working theStellarSdk.FastSigningvariable will returntrue.
js-stellar-sdk is licensed under an Apache-2.0 license. See the LICENSE file for details.
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 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.
FAQs
A library for working with the Stellar network, including communication with the Horizon and Soroban RPC servers.
The npm package @stellar/stellar-sdk receives a total of 161,991 weekly downloads. As such, @stellar/stellar-sdk popularity was classified as popular.
We found that @stellar/stellar-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Malicious dYdX client packages were published to npm and PyPI after a maintainer compromise, enabling wallet credential theft and remote code execution.
Security News
gem.coop is testing registry-level dependency cooldowns to limit exposure during the brief window when malicious gems are most likely to spread.
Security News
Following multiple malicious extension incidents, Open VSX outlines new safeguards designed to catch risky uploads earlier.