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 @digitalworld/digital-world-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 "@digitalworld/digital-world-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);

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 "@digitalworld/digital-world-sdk";

Networks.TESTNET; // "Test Digital World Network ; March 2025"
Networks.PUBLIC; // "Digital World Network ; June 2021"

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

Connect to Gateway and RPC

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

• Gateway 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 (Dwsa): simulate and send contract calls. Use it when you invoke contracts.

import { Gateway, rpc } from "@digitalworld/digital-world-sdk";

const gateway = new Gateway.Server("https://dex-testnet.digitalworld.global");
const rpcServer = new rpc.Server("YOUR_RPC_URL");

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

Fund a new account

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

await gateway.faucet(keypair.publicKey()).call();

This call throws if the account already exists or the faucet 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 gateway.loadAccount(keypair.publicKey());
const native = account.balances.find((b) => b.asset_type === "native");

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

Put it together

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

import { Keypair, Gateway } from "@digitalworld/digital-world-sdk";

async function main() {
  const keypair = Keypair.random();
  const gateway = new Gateway.Server("https://dex-testnet.digitalworld.global");

  console.log("Public key:", keypair.publicKey());

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

  // Throws NotFoundError if the account is not on the ledger yet.
  const account = await gateway.loadAccount(keypair.publicKey());
  const native = account.balances.find((b) => b.asset_type === "native");

  console.log("NATIVE balance:", native?.balance);
}

main().catch(console.error);

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