# fast-sdk

**GitHub:** [fastxyz/fast-sdk](https://github.com/fastxyz/fast-sdk/blob/main/packages/fast-sdk/README.md)

## What You Can Do

The Fast SDK is the core interface for building applications on the Fast payment network. Use it to:

* **Authorize and submit payments** — construct transfers and other supported Fast operations, then authorize them with Ed25519 keys
* **Query the network** — look up account balances, sequence numbers, token metadata, and network state
* **Manage tokens** — transfer, create, issue, and release tokens on Fast
* **Sign and verify messages** — use Ed25519 signatures for off-network messages alongside Fast network payments
* **Address conversion** — convert between hex, bytes, and bech32m address formats seamlessly

## Installation

Install from npm as `@fastxyz/sdk`. For the exact install command and current examples, use the [package README on GitHub](https://github.com/fastxyz/fast-sdk/blob/main/packages/fast-sdk/README.md).

## Architecture

The SDK is built around three composable primitives:

| Component              | Purpose                                                                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **FastProvider**       | JSON-RPC client that connects to the Fast proxy API. Handles all network queries (balance checks, account info, token lookups) and transaction submission.                                    |
| **Signer**             | Holds an Ed25519 private key and produces signatures for payments and messages. Keys never leave the Signer — you control your secrets.                                                       |
| **TransactionBuilder** | Fluent builder API for constructing operations. Chains methods like `addTokenTransfer()`, `addTokenCreation()`, `addMint()`, `addBurn()` and produces a signed envelope ready for submission. |

All three compose together: create a `FastProvider` pointing at an RPC endpoint, pair it with a `Signer` holding your key, and pass both to a `TransactionBuilder` to build and sign operations.

## Core Concepts

**The Fast payment network** is a high-performance payment network. Unlike a blockchain, it is optimized for fast finality and low-cost payment operations. Payments confirm in seconds, not minutes.

**Accounts** on Fast are identified by bech32m addresses (prefix `fast`). An account must be funded before it can submit transactions — there is no mining or staking mechanism.

**Operations** are the building blocks of every payment. Each operation has a sequence number to prevent reuse. Operations can be batched into a single payment for atomic execution.

**Token types** on Fast include fungible tokens (ERC20-like) and native token (FAST). Token addresses are bech32m-encoded on Fast, unlike the hex addresses used on EVM chains. Tokens can be issued or released by authorized accounts.

## Key Workflows

### Initialize and Query

Create a `FastProvider` pointing at the desired RPC endpoint. Use it to query account info (balances, next nonce, token holdings) and token metadata. This is the first step before building any transaction.

### Authorize and Submit a Payment

Create a `TransactionBuilder` with your `Signer` and `FastProvider`. Chain operation methods to build the transaction, then call `.sign()` to produce a signed envelope. The builder handles nonce management, BCS serialization, and Ed25519 signing.

### Submit and Confirm

Pass the signed envelope to `FastProvider.submitTransaction()`. The proxy handles broadcasting to validators, collecting quorum signatures, and assembling a certificate. Settlement is final — typically under one second.

For complete method signatures, supported operation builders, error handling, and runnable examples, see the [fast-sdk README on GitHub](https://github.com/fastxyz/fast-sdk/blob/main/packages/fast-sdk/README.md).

## RPC Endpoints

| Network | RPC URL                              | Use Case                                 |
| ------- | ------------------------------------ | ---------------------------------------- |
| Mainnet | `https://api.fast.xyz/proxy`         | Production — real tokens and payments    |
| Testnet | `https://testnet.api.fast.xyz/proxy` | Development — test tokens, no real value |

> **Tip:** Use testnet first to validate your integration before touching mainnet.

## Address Format

Fast uses bech32m addresses with the `fast` prefix. You may also encounter hex format (for raw bytes) and byte arrays (for RPC payloads). The SDK provides conversion utilities (`toHex`, `fromHex`, `toFastAddress`, `fromFastAddress`) to handle all formats.

***

**For complete API documentation, all method signatures, supported operations, and runnable examples, see the** [**fast-sdk README on GitHub**](https://github.com/fastxyz/fast-sdk/blob/main/packages/fast-sdk/README.md)**.**