Skip to main content

Quickstart Guide

Get up and running with Synapse SDK in just a few minutes. This guide walks you through your first upload and download on Filecoin Onchain Cloud.

Prerequisites

1

Node.js 18+

Ensure you have Node.js 18 or later installed:
node --version
2

Wallet with Private Key

You’ll need a Filecoin wallet with a private key. For testnet, you can create one using:
import { privateKeyToAccount } from 'viem/accounts'
import { generatePrivateKey } from 'viem/accounts'

const privateKey = generatePrivateKey()
const account = privateKeyToAccount(privateKey)
console.log('Address:', account.address)
console.log('Private key:', privateKey)
3

Test Funds (Calibration)

For calibration testnet, get free test FIL and USDFC:

Installation

Install the Synapse SDK:
npm install @filoz/synapse-sdk

Your First Upload

Create a file called upload.ts (or upload.js for JavaScript):
upload.ts
import { Synapse } from '@filoz/synapse-sdk'
import { calibration } from '@filoz/synapse-core/chains'
import { http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

async function main() {
  // 1. Create your account from private key
  const account = privateKeyToAccount('0x...' as `0x${string}`)
  
  // 2. Initialize Synapse
  const synapse = Synapse.create({
    chain: calibration,
    transport: http(),
    account,
  })
  
  console.log('Connected to:', synapse.chain.name)
  console.log('Wallet:', account.address)
  
  // 3. Check your balances
  const usdfc = await synapse.payments.walletBalance({ token: 'USDFC' })
  console.log('USDFC balance:', Number(usdfc) / 1e18)
  
  // 4. Ensure you have operator approval (one-time setup)
  const approval = await synapse.payments.serviceApproval()
  if (!approval.isApproved) {
    console.log('Setting up operator approval...')
    await synapse.payments.setOperatorApproval({
      operator: synapse.chain.contracts.fwss.address,
      approved: true,
    })
  }
  
  // 5. Upload some data
  console.log('\nUploading data...')
  const data = new TextEncoder().encode('Hello from Filecoin Onchain Cloud!')
  
  const result = await synapse.storage.upload(data, {
    callbacks: {
      onProviderSelected: (provider) => {
        console.log('Selected provider:', provider.id)
      },
      onStored: (providerId, pieceCid) => {
        console.log(`Stored on provider ${providerId}:`, pieceCid)
      },
      onPiecesConfirmed: (dataSetId, providerId) => {
        console.log(`Confirmed on-chain: dataset ${dataSetId}, provider ${providerId}`)
      },
    },
  })
  
  console.log('\n✅ Upload complete!')
  console.log('PieceCID:', result.pieceCid)
  console.log('Size:', result.size, 'bytes')
  console.log('Copies:', result.copies.length)
  
  for (const copy of result.copies) {
    console.log(`  - Provider ${copy.providerId} (${copy.role}): dataset ${copy.dataSetId}, piece ${copy.pieceId}`)
  }
  
  // 6. Download and verify
  console.log('\nDownloading data...')
  const retrieved = await synapse.storage.download({ 
    pieceCid: result.pieceCid 
  })
  
  const text = new TextDecoder().decode(retrieved)
  console.log('Retrieved:', text)
  console.log('\n✅ Round-trip successful!')
}

main().catch(console.error)
Replace '0x...' with your actual private key. Never commit private keys to version control!

Run Your Code

Run with Node.js (requires TypeScript compilation or a tool like tsx):
node --loader ts-node/esm upload.ts
Or compile first:
tsc upload.ts
node upload.js

Expected Output

Connected to: Filecoin Calibration
Wallet: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
USDFC balance: 100.0

Uploading data...
Selected provider: 123
Stored on provider 123: baga6ea4seaqao7s73y24roe...
Stored on provider 456: baga6ea4seaqao7s73y24roe...
Confirmed on-chain: dataset 789, provider 123
Confirmed on-chain: dataset 790, provider 456

✅ Upload complete!
PieceCID: baga6ea4seaqao7s73y24roe...
Size: 35 bytes
Copies: 2
  - Provider 123 (primary): dataset 789, piece 1
  - Provider 456 (secondary): dataset 790, piece 1

Downloading data...
Retrieved: Hello from Filecoin Onchain Cloud!

✅ Round-trip successful!

Understanding What Happened

1

Provider Selection

The SDK automatically selected 2 storage providers: one endorsed provider as the primary, and one approved provider as the secondary.
2

Store on Primary

Your data was uploaded to the primary provider and converted to a PieceCID (Content Identifier for Filecoin pieces).
3

Pull to Secondary

The secondary provider fetched the data directly from the primary provider (SP-to-SP transfer), eliminating the need to upload twice.
4

Commit On-Chain

Both providers registered the piece with the PDPVerifier contract, creating provable on-chain records and starting PDP verification.
5

Download

The SDK fetched your data back from one of the providers, verified the PieceCID, and returned the bytes.

Common Issues

You need USDFC tokens to pay for storage. For calibration testnet:
  1. Contact the FilOzone team for test USDFC
  2. Or use the Synapse Playground to get tokens
Check your balance:
const balance = await synapse.payments.walletBalance({ token: 'USDFC' })
console.log('USDFC:', Number(balance) / 1e18)
The first time you use the SDK, you need to approve the Warm Storage service as an operator:
await synapse.payments.setOperatorApproval({
  operator: synapse.chain.contracts.fwss.address,
  approved: true,
})
Filecoin has a 30-second block time. If transactions seem slow, this is normal. Wait at least 60 seconds before assuming failure.
If using a JSON-RPC account (from browser wallet), you must provide a custom transport. See the Browser Integration guide.

Next Steps

Core Concepts

Learn how the storage pipeline works under the hood

Storage Operations

Explore advanced upload options and split operations

Payment Management

Manage deposits, withdrawals, and payment rails

Examples

See more complete examples and use cases

Build docs developers (and LLMs) love