Fast SDK

Official TypeScript SDK for the Fast network.

The package now has three entrypoints:

• @fastxyz/sdk for Node.js apps, keyfiles, and ~/.fast/* config overrides
• @fastxyz/sdk/browser for browser-safe provider, config, and protocol helpers with no node:* dependency chain
• @fastxyz/sdk/core for pure Fast helpers with no provider or wallet surface

Install

npm install @fastxyz/sdk

Node Quick Start

import { FastProvider, FastWallet } from '@fastxyz/sdk';

const provider = new FastProvider({ network: 'testnet' });
const wallet = await FastWallet.fromKeyfile('~/.fast/keys/default.json', provider);

const tx = await wallet.send({
  to: 'fast1...',
  amount: '1',
});

console.log(tx.txHash);
console.log(tx.certificate);
console.log(tx.explorerUrl);

const signed = await wallet.sign({ message: 'Hello, Fast!' });
console.log(signed.signature);
console.log(signed.messageBytes);

Browser Quick Start

import { FastProvider, getCertificateHash } from '@fastxyz/sdk/browser';

const provider = new FastProvider({ network: 'testnet' });
const balance = await provider.getBalance('fast1...', 'FAST');
console.log(balance.amount);

const certificate = await provider.getCertificateByNonce('fast1...', 1);
if (certificate) {
  console.log(getCertificateHash(certificate));
}

Core Quick Start

import {
  encodeFastAddress,
  decodeFastAddress,
  getCertificateHash,
} from '@fastxyz/sdk/core';

Architecture

• FastProvider is the low-level Fast proxy client and is available from both entrypoints.
• FastWallet is Node-only and supports keyfiles, generated wallets, and private-key imports.
• @fastxyz/sdk/browser stays low-level and does not bundle browser wallet lifecycle or injected-wallet wrappers.
• @fastxyz/sdk/core is the pure helper surface for browser-safe protocol utilities.

Supported in @fastxyz/sdk/browser

• provider reads and low-level proxy methods
• token and network config from bundled defaults or constructor overrides
• canonical Fast address codec helpers
• transaction hashing and certificate helpers

If your browser app uses an injected wallet such as window.fastset, keep that wrapper in app code or a separate client package.

If you are building a dapp-facing browser integration layer, keep that in fast-connector and build it on top of @fastxyz/sdk/browser.

Node-only

• FastWallet
• keyfile storage and saveToKeyfile()
• ~/.fast/networks.json and ~/.fast/tokens.json
• FAST_CONFIG_DIR
• env-seeded keyfile behavior

Public Helpers

@fastxyz/sdk and @fastxyz/sdk/browser both export the canonical Fast address codec helpers and the shared protocol helpers they need:

• encodeFastAddress, fastAddressToBytes, decodeFastAddress
• FAST_TOKEN_ID, FAST_DECIMALS
• hashTransaction, serializeVersionedTransaction

@fastxyz/sdk and @fastxyz/sdk/browser also export network-aware config helpers:

• getNetworkInfo, getAllNetworks
• getDefaultRpcUrl, getExplorerUrl

Use getExplorerUrl(network) for a base explorer URL and provider.getExplorerUrl(txHash) for a transaction URL. Explorer hosts are network-specific and can be overridden by config, so avoid hardcoded explorer constants.

@fastxyz/sdk/browser also exports:

• getCertificateTransaction, getCertificateHash, getCertificateTokenTransfer
• compatibility aliases for existing browser consumers: pubkeyToAddress, addressToPubkey, normalizeFastAddress

@fastxyz/sdk/core exports the pure helper set only:

• canonical address codec helpers
• amount helpers like toHex() and fromHex()
• BCS, byte, and certificate helpers
• shared Fast types and FastError

Configuration

FastProvider accepts constructor-level config injection:

const provider = new FastProvider({
  network: 'custom',
  networks: {
    custom: {
      rpc: 'https://custom.example.com/proxy',
      explorer: 'https://custom.example.com/explorer',
    },
  },
  tokens: {
    MYTOKEN: {
      symbol: 'MYTOKEN',
      tokenId: '0x1234',
      decimals: 18,
    },
  },
});

Node entrypoint config precedence:

1. constructor overrides
2. ~/.fast/networks.json and ~/.fast/tokens.json
3. bundled defaults
4. hardcoded fallbacks

Browser entrypoint config precedence:

1. constructor overrides
2. bundled defaults
3. hardcoded fallbacks

Token symbols are network-specific. Bundled defaults currently resolve:

• testnet: FAST, testUSDC
• mainnet: FAST, fastUSDC

If you use ~/.fast/tokens.json, keep it keyed by network name so the same symbol cannot silently point at different token IDs on different networks.

API Notes

• wallet.send() returns { txHash, certificate, explorerUrl } on the Node FastWallet
• wallet.sign() returns { signature, address, messageBytes } on the Node FastWallet
• provider.submitTransaction(envelope) exposes raw proxy_submitTransaction
• provider.faucetDrip({ recipient, amount, token? }) exposes raw proxy_faucetDrip
• provider.getTransactionCertificates(address, fromNonce, limit) exposes raw proxy_getTransactionCertificates
• provider.getCertificateByNonce(address, nonce) fetches a certificate directly from RPC
• provider.getExplorerUrl(txHash?) returns the configured explorer URL for the provider network

Development

npm install
npm run build
npm test
npm run live:smoke -- --live
npm run pack:dry-run
npm run pack:smoke

live:smoke performs real writes against the configured Fast network. It creates a disposable token, transfers its full initial supply to a second disposable wallet, and verifies balances plus certificates. The script refuses to run unless you pass --live or set FAST_LIVE_SMOKE=1.

Releasing

See RELEASING.md.