# Quick Start with Synapse SDK

import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

The **Synapse SDK** is your gateway to **Filecoin Onchain Cloud**, a decentralized, programmable cloud platform built on Filecoin. The SDK handles all the complexity of blockchain interactions, provider selection, and data management, so you can focus on building your application.

By the end of this guide, you'll understand how to:

- Install and configure the Synapse SDK
- Connect to Filecoin networks (mainnet and calibration)
- Prepare and fund your storage balance
- Upload and download data

## Prerequisites

- **FIL** for gas fees. On testnet, get tFIL from the [Calibration Faucet](https://faucet.calibnet.chainsafe-fil.io/funds.html). For mainnet, see [Getting FIL](/resources/additional-resources/#getting-fil-tokens).
- **USDFC** for storage payments. On testnet, get tUSDFC from the [USDFC Faucet](https://forest-explorer.chainsafe.dev/faucet/calibnet_usdfc). For mainnet, see [Getting USDFC](/resources/additional-resources/#getting-usdfc-tokens).

## Installation

The Synapse SDK works in **Node.js** and **the browser**. Install it with your preferred package manager:

<Tabs syncKey="pkg">
  <TabItem label="npm" icon="seti:npm">
    ```bash
    npm install @filoz/synapse-sdk viem
    ```
  </TabItem>
  <TabItem label="pnpm" icon="pnpm">
    ```bash
    pnpm add @filoz/synapse-sdk viem
    ```
  </TabItem>
  <TabItem label="yarn" icon="seti:yarn">
    ```bash
    yarn add @filoz/synapse-sdk viem
    ```
  </TabItem>
  <TabItem label="bun" icon="bun">
    ```bash
    bun add @filoz/synapse-sdk viem
    ```
  </TabItem>
</Tabs>

`viem` is a peer dependency and must be installed separately.

:::tip[Other Languages?]
Looking for Python or Go? Check out [Community Projects](/resources/community-projects/) for community-maintained SDKs.
:::

## Quick Start

The [`Synapse`](/reference/filoz/synapse-sdk/synapse/classes/synapse/) class provides a complete, easy-to-use interface for interacting with Filecoin storage services.

:::note[Keep your private key safe]
Instead of hardcoding `privateKey` in the code, you should always consider to store and access it from `.env` files. And never commit your private key.
:::

Get started with storage in just a few lines of code.

```ts twoslash
// @lib: esnext,dom
import { Synapse, mainnet } from "@filoz/synapse-sdk"
import { privateKeyToAccount } from 'viem/accounts'

// 1) Initialize the Synapse SDK
const synapse = Synapse.create({
  account: privateKeyToAccount('0x...'),
  source: 'my-app',
  chain: mainnet, // default is calibration testnet
  // Uncomment for high-performance incentive-aligned data retrievability through Filecoin Beam
  // withCDN: true
})
// 2) Prepare account (single tx handles deposit + approval)
const file = new TextEncoder().encode(
  `🚀 Welcome to decentralized storage on Filecoin Onchain Cloud!
  Your data is safe here.
  🌍 You need to make sure to meet the minimum size
  requirement of 127 bytes per upload.`
);
const prep = await synapse.storage.prepare({
  dataSize: BigInt(file.byteLength),
})
if (prep.transaction) {
  const { hash } = await prep.transaction.execute()
  console.log(`✅ Account funded and approved (tx: ${hash})`)
}
// 3) Upload — stores 2 copies across independent providers for durability
const { pieceCid, size, complete, copies, failedAttempts } = await synapse.storage.upload(file)
console.log(`✅ Upload complete!`);
console.log(`PieceCID: ${pieceCid}`);
console.log(`Size: ${size} bytes`);
console.log(`Stored on ${copies.length} providers`);
if (!complete) console.warn(`${failedAttempts.length} copy attempt(s) failed`);
// 4) Download
const bytes = await synapse.storage.download({ pieceCid })
const decodedText = new TextDecoder().decode(bytes);
console.log(`✅ Download successful!`);
console.log(`Downloaded data: ${decodedText}\n`);
console.log("🎉 Data storage and retrieval successful!");
```

Now let's break down each step...

<Steps>

1. **Initialize the SDK**

   Set up the Synapse SDK with your credentials. In Node.js, you'll typically use a private key:

   ```ts twoslash
   // @lib: esnext,dom
   import { Synapse, mainnet } from "@filoz/synapse-sdk";
   import { privateKeyToAccount } from 'viem/accounts'
   // ---cut---
   const synapse = Synapse.create({ 
    account: privateKeyToAccount('0x...'), 
    source: 'my-app',
    chain: mainnet, // default is calibration testnet
   })
   ```

   In the browser, connect to the user's wallet instead:

   ```ts twoslash
   // @lib: esnext,dom
   import { Synapse, mainnet } from "@filoz/synapse-sdk";
   // ---cut---   
   import 'viem/window'
   import { custom } from 'viem'
   const [address] = await window.ethereum!.request({ method: 'eth_requestAccounts' })
   
   const synapse = Synapse.create({ 
    account: address, 
    transport: custom(window.ethereum!), 
    source: 'my-app',
    chain: mainnet, // default is calibration testnet
   })
   ```

   The `source` parameter identifies your application. It is stored as metadata on each dataset so that multiple apps sharing the same wallet can distinguish their own data.

2. **Payment Setup**

   The `prepare()` method calculates the exact deposit needed for your data size and returns a single transaction that handles both funding and approval.

   To size your deposit, check the up-to-date rates in [**Pricing**](/introduction/about/#pricing) and use the [storage costs guide](/developer-guides/storage/storage-costs/) for a detailed breakdown.

   ```ts twoslash
   // @lib: esnext,dom
   import { Synapse, TOKENS, formatUnits } from "@filoz/synapse-sdk";
   import { privateKeyToAccount } from 'viem/accounts'
   const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' })

   // ---cut---
   // Check current USDFC balance
   const walletBalance = await synapse.payments.walletBalance({ token: TOKENS.USDFC });
   const formattedBalance = formatUnits(walletBalance);

   // Prepare account
   const prep = await synapse.storage.prepare({
     dataSize: 1073741824n, // 1 GiB
   });

   console.log("Deposit needed:", prep.costs.depositNeeded);
   console.log("Rate per month:", prep.costs.rate.perMonth);
   console.log("Ready to upload:", prep.costs.ready);

   // Execute the transaction if needed (handles deposit + approval in one tx)
   if (prep.transaction) {
     const { hash } = await prep.transaction.execute();
     console.log(`Account funded and approved (tx: ${hash})`);
   }
   ```

3. **Store and Download Data**

   Upload data to decentralized storage and retrieve it:

   ```ts twoslash
   // @lib: esnext,dom
   import { Synapse } from "@filoz/synapse-sdk";
   import { privateKeyToAccount } from 'viem/accounts'
   const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' })
   // ---cut---
   // Upload data (stores 2 copies by default for durability)
   const file = new TextEncoder().encode(
     `Welcome to decentralized storage on Filecoin Onchain Cloud!
       Your data is safe here.
       You need to make sure to meet the minimum size
       requirement of 127 bytes per upload.`
   );
   const { pieceCid, complete, copies, failedAttempts } = await synapse.storage.upload(file);
   console.log(`Stored on ${copies.length} providers`);
   if (!complete) console.warn(`${failedAttempts.length} copy attempt(s) failed`);

   // Download data from any provider that has it
   const downloadedData = await synapse.storage.download({ pieceCid });
   const decodedText = new TextDecoder().decode(downloadedData);

   console.log(`Downloaded data: ${decodedText}`);
   ```

</Steps>

## Next Steps

You've just stored and retrieved data on Filecoin. See the [Developer Guides](/developer-guides/) overview to find the right approach for your application, then dive into specific topics:

- [Upload Pipeline](/developer-guides/storage/upload-pipeline/) - From simple one-liner to manual store, pull, and commit control
- [Storage Operations](/developer-guides/storage/storage-operations/) - Data set management, retrieval, and lifecycle
- [Payment Operations](/developer-guides/payments/payment-operations/) - Fund your account and manage storage payments
- [Session Keys](/developer-guides/session-keys/) - Delegate signing to ephemeral keys for better UX
- [API Reference](/reference/filoz/synapse-sdk/toc/) - Complete SDK classes, methods, and types
- [Example Application](https://github.com/FIL-Builders/foc-upload-dapp) - Full-stack upload dapp

Want to understand the protocol? See [Foundations & Architecture](/core-concepts/architecture/) for how PDP, Filecoin Pay, and the service provider network fit together.

Join the `#fil-builders` on [Filecoin Slack](https://filecoin.io/slack) or [Telegram](https://t.me/+Xj6_zTPfcUA4MGQ1) for help and discussions.