Skip to main content

​
Welcome to Synapse SDK

The Synapse SDK is a TypeScript/JavaScript library that provides a simple, powerful interface for building applications on Filecoin Onchain Cloud (FOC). It abstracts away the complexity of smart contracts and storage provider APIs, giving you a high-level interface to store and retrieve data on Filecoin with built-in redundancy and payments.

​
What is Filecoin Onchain Cloud?

Filecoin Onchain Cloud is a decentralized storage marketplace that combines:
  • Proof of Data Possession (PDP) - Cryptographic verification that your data is stored
  • Multi-provider redundancy - Data automatically replicated across multiple storage providers
  • Integrated payments - Usage-based payments via USDFC stablecoin
  • CDN acceleration - Optional content delivery network for fast retrievals

​
Why Use Synapse SDK?

Simple API

Upload and download data with just a few lines of code. No need to understand smart contracts or storage protocols.

Built-in Redundancy

Automatic multi-copy uploads ensure your data is safe across multiple independent storage providers.

Flexible Payments

Pay-as-you-go pricing with USDFC. Deposit once, and the SDK handles ongoing storage payments automatically.

Works Everywhere

Run in Node.js or browsers. Uses web standards like ReadableStream and fetch for maximum compatibility.

​
Architecture Overview

Synapse SDK sits between your application and the Filecoin infrastructure: 
Your Application
      ↓
Synapse SDK
      ↓
   ┌──────────────────┬──────────────────┐
   ↓                  ↓                  ↓
Smart Contracts   Storage Providers   CDN (optional)
- FWSS             - Curio HTTP API   - FilBeam
- Payments         - PDP verification
- PDPVerifier
- SPRegistry

​
Key Components

Synapse Class - Main entry point that provides access to all services:
  • synapse.storage - Upload, download, and manage data
  • synapse.payments - Deposits, withdrawals, and balance checks
  • synapse.providers - Query available storage providers
  • synapse.filbeam - CDN statistics and quotas
Storage Pipeline - Multi-step flow for reliable storage:
  1. Store - Upload data to primary provider
  2. Pull - Secondary providers fetch from primary (SP-to-SP)
  3. Commit - Register pieces on-chain with PDP verification

​
Quick Example

Here’s how simple it is to store data: 
import { Synapse } from '@filoz/synapse-sdk'
import { calibration } from '@filoz/synapse-core/chains'
import { http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

// Initialize
const account = privateKeyToAccount('0x...')
const synapse = Synapse.create({
  chain: calibration,
  transport: http(),
  account,
})

// Upload with automatic redundancy
const data = new TextEncoder().encode('Hello, Filecoin!')
const result = await synapse.storage.upload(data)

console.log('Stored at:', result.pieceCid)
console.log('Copies:', result.copies.length) // 2 by default

// Download from any provider
const retrieved = await synapse.storage.download({ 
  pieceCid: result.pieceCid 
})
console.log('Retrieved:', new TextDecoder().decode(retrieved))

​
Supported Networks

Synapse SDK works on Filecoin mainnet and calibration testnet:
Use calibration for development and testing:
import { calibration } from '@filoz/synapse-core/chains'

const synapse = Synapse.create({
  chain: calibration,
  account,
  transport: http(),
})
RPC Endpoint: https://api.calibration.node.glif.io/rpc/v1
Filecoin has a 30-second block time. Be patient when waiting for transaction confirmations.

​
Package Structure

The Synapse ecosystem includes two main packages: @filoz/synapse-sdk - High-level SDK for applications
  • Simple Synapse class with intuitive methods
  • Automatic provider selection and multi-copy uploads
  • Built-in error handling and retries
@filoz/synapse-core - Low-level protocol library
  • Direct smart contract interactions
  • PieceCID utilities and EIP-712 signing
  • Session key management
  • Used internally by synapse-sdk, but also available for advanced use cases

​
What’s Next?

Quickstart

Get up and running in 5 minutes with your first upload

Installation

Install the SDK in your Node.js or browser project

Core Concepts

Understand the storage pipeline and provider selection

API Reference

Explore all available methods and options

Build docs developers (and LLMs) love

Get started for freeTalk to us