Skip to content
@stellar/stellar-sdk

Connect and Fund an Account

This guide takes you from nothing to a funded testnet account you can build on. It is for anyone making their first call with @stellar/stellar-sdk. Everything here runs against testnet, so it costs nothing and is safe to repeat.

Create a keypair

A keypair is an account’s identity. The public key is the account’s address (it starts with G) and the secret key signs transactions (it starts with S). Never share or commit a secret key.

import { Keypair } from "@stellar/stellar-sdk";


const keypair = Keypair.random();


keypair.publicKey(); // "G..." (share this)
keypair.secret(); // "S..." (keep this private)

A keypair holds no funds and does not exist on the network until an account is funded for that public key (see Fund a new account).

Store the secret, not the keypair object. Rebuild the keypair when you need it:

const keypair = Keypair.fromSecret(secret);

Sign and verify a message

A keypair can also sign an arbitrary message — not a transaction — to prove it controls an address, entirely off-chain. This follows SEP-53, so signatures interoperate with the other Stellar SDKs and the CLI, and it is the basis for proof-of-ownership flows like “Sign in with Stellar”.

// Sign a string (or raw bytes); returns a 64-byte signature.
const signature = keypair.signMessage("Hello, World!");


// Anyone holding the public key can verify it — no secret key needed.
const verifier = Keypair.fromPublicKey(keypair.publicKey());
verifier.verifyMessage("Hello, World!", signature); // true

Only the secret-key holder can produce a valid signature; verification needs just the public key. See signMessage and verifyMessage in the reference.

Choose a network

Every transaction is signed for exactly one network, identified by its passphrase. Use the passphrase that matches where you are submitting so a signature from one network cannot be replayed on another.

import { Networks } from "@stellar/stellar-sdk";


Networks.TESTNET; // "Test SDF Network ; September 2015"
Networks.PUBLIC; // "Public Global Stellar Network ; September 2015"

Start on TESTNET. Switch to PUBLIC only when you are ready to use real funds.

Connect to Horizon and RPC

The SDK talks to two services, and which one you need depends on the task.

  • Horizon serves account, balance, payment, and history data and accepts classic transactions (payments, trustlines, and other non-contract operations). Use it for accounts, balances, and payments.
  • RPC is the gateway for smart contracts (Soroban): simulate and send contract calls. Use it when you invoke contracts.
import { Horizon, rpc } from "@stellar/stellar-sdk";


const horizon = new Horizon.Server("https://horizon-testnet.stellar.org");
const rpcServer = new rpc.Server("https://soroban-testnet.stellar.org");

This guide only needs Horizon. The RPC connection is shown so you know where contract work begins. For the full client API, see Horizon.Server and rpc.Server in the reference.

Fund a new account

On testnet, friendbot creates and funds a new account for free, seeding it with 10,000 XLM. There is no friendbot on the public network, where accounts are funded by an existing account.

await horizon.friendbot(keypair.publicKey()).call();

This call throws if the account already exists or friendbot is rate-limited. Funding a brand-new Keypair.random() avoids the “already exists” case, so wrap it in a try/catch to handle the rest.

Once funded, the account exists on the ledger. Load it to read its balances. loadAccount throws NotFoundError if the account is not on the ledger yet, which is how the SDK signals that funding has not gone through:

const account = await horizon.loadAccount(keypair.publicKey());
const xlm = account.balances.find((b) => b.asset_type === "native");


account.accountId(); // the funded public key
xlm?.balance; // its XLM balance, as a string

Put it together

The snippets above build on each other. Here is the whole flow as one runnable script — the same code as the steps, assembled. The blocks share the same keypair and horizon, and console.log prints the results so you can see them when you run the file:

import { Keypair } from "@stellar/stellar-sdk";


const keypair = Keypair.random();


import { Horizon, rpc } from "@stellar/stellar-sdk";


const horizon = new Horizon.Server("https://horizon-testnet.stellar.org");
const rpcServer = new rpc.Server("https://soroban-testnet.stellar.org");


// On testnet, friendbot creates and funds the account for free.
try {
  await horizon.friendbot(keypair.publicKey()).call();
} catch (e) {
  // Thrown if the account already exists or friendbot is rate-limited.
  console.error("Funding failed:", e);
  throw e;
}


const account = await horizon.loadAccount(keypair.publicKey());
const xlm = account.balances.find((b) => b.asset_type === "native");


console.log("Public key:", keypair.publicKey());
console.log("XLM balance:", xlm?.balance);

You now have a funded account and a connection to the network. From here you can send your first payment.