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
Node.js 18+
Ensure you have Node.js 18 or later installed: 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)
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):
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
Run directly with Node.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
Provider Selection
The SDK automatically selected 2 storage providers: one endorsed provider as the primary, and one approved provider as the secondary.
Store on Primary
Your data was uploaded to the primary provider and converted to a PieceCID (Content Identifier for Filecoin pieces).
Pull to Secondary
The secondary provider fetched the data directly from the primary provider (SP-to-SP transfer), eliminating the need to upload twice.
Commit On-Chain
Both providers registered the piece with the PDPVerifier contract, creating provable on-chain records and starting PDP verification.
Download
The SDK fetched your data back from one of the providers, verified the PieceCID, and returned the bytes.
Common Issues
Insufficient USDFC balance
You need USDFC tokens to pay for storage. For calibration testnet:
- Contact the FilOzone team for test USDFC
- 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.
'Transport must be custom' error
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