Stellar JS SDK

Build applications on the Stellar network using @stellar/stellar-sdk (v14.x, Node 20+).

Installation

npm install @stellar/stellar-sdk

Import only what you need:

import {
  Keypair,
  Horizon,
  rpc,
  TransactionBuilder,
  Networks,
  Operation,
  Asset,
  Memo,
  BASE_FEE,
} from "@stellar/stellar-sdk";

Never install @stellar/stellar-base separately — the SDK re-exports everything from it.

Quick Start

import {
  Keypair,
  Horizon,
  TransactionBuilder,
  Networks,
  Operation,
  Asset,
  BASE_FEE,
} from "@stellar/stellar-sdk";

// 1. Create keypair and fund on testnet
const keypair = Keypair.random();
await fetch(`https://friendbot.stellar.org?addr=${keypair.publicKey()}`);

// 2. Connect to Horizon
const server = new Horizon.Server("https://horizon-testnet.stellar.org");

// 3. Build, sign, submit a payment
const account = await server.loadAccount(keypair.publicKey());
const tx = new TransactionBuilder(account, {
  fee: BASE_FEE,
  networkPassphrase: Networks.TESTNET,
})
  .addOperation(
    Operation.payment({
      destination: "GABC...",
      asset: Asset.native(),
      amount: "10",
    }),
  )
  .setTimeout(30)
  .build();

tx.sign(keypair);
const result = await server.submitTransaction(tx);

Core Workflow

Every Stellar JS SDK interaction follows this pattern:

Connect — create Horizon.Server or rpc.Server instance
Load account — fetch current sequence number via server.loadAccount()
Build transaction — use TransactionBuilder with operations
Sign — call transaction.sign(keypair)
Submit — call server.submitTransaction(transaction)

Always set .setTimeout(30) on transactions. Always handle errors by inspecting error.response.data.extras.result_codes.

Key Concepts

Stroops: 1 XLM = 10,000,000 stroops. BASE_FEE = 100 stroops.
Amounts: Always strings with up to 7 decimal places (e.g., '100.1234567').
Sequence numbers: Auto-managed when using server.loadAccount().
Network passphrase: Transactions are network-specific. Use Networks.TESTNET, Networks.PUBLIC, etc.
Trustlines: Required before receiving any non-XLM asset.
Base reserve: 0.5 XLM per account subentry (trustlines, offers, signers, data entries).
Max 100 operations per transaction (1 for smart contract operations).

When to Use Horizon vs RPC

Use Case	Module
Account balances, payment history, transaction queries	`Horizon.Server`
Streaming payments, transactions, effects	`Horizon.Server` (`.stream()`)
Orderbook, DEX trading, trade history	`Horizon.Server`
Asset info, fee stats, ledger data	`Horizon.Server`
Smart contract interactions	`rpc.Server`
Transaction simulation (`simulateTransaction`)	`rpc.Server`
Contract events	`rpc.Server`
Preparing contract transactions (`prepareTransaction`)	`rpc.Server`

Reference Files

API Reference: Complete class/method reference for all SDK modules — Keypair, TransactionBuilder, Horizon.Server, rpc.Server, Operations, Assets, contract module, WebAuth, Federation, StellarToml, XDR helpers. Read when you need specific method signatures or parameter details.
Code Examples: Working code examples for all common tasks — payments, path payments, asset issuance, trustlines, DEX trading, streaming, fee-bumps, claimable balances, sponsored reserves, multisig, RPC interactions, SEP-10 auth, federation, error handling. Read when implementing a specific feature.
Networks & Configuration: Network URLs, passphrases, Friendbot, testnet/mainnet switching, CLI bindings generation, browser/React Native setup, key limits. Read when configuring the SDK for a specific environment or deploying to a different network.