Synapse SDK

What is Synapse SDK?

Synapse SDK is a TypeScript SDK for interacting with the Filecoin Onchain Cloud - a smart-contract based marketplace for storage and other services in the Filecoin ecosystem. It provides a high-level API for interacting with the system. Additionally, it offers a low-level API for direct interaction with the underlying smart contracts and storage providers.

The SDK integrates with four key components of the Filecoin Onchain Cloud:

PDPVerifier : Proof verification contract powered by (PDP)
Filecoin Pay : Payment layer contract powered by (Filecoin Pay)
Filecoin Warm Storage Service : Business logic contract powered by (WarmStorage)
Service Providers : Service providers are the actors that safeguard the data stored in the Filecoin Onchain Cloud powered by the Curio Storage software

The Synapse class provides a single entry point for all operations:

interface 
interface SynapseAPI
SynapseAPI {
  // Create a new Synapse instance
  
SynapseAPI.create(options: SynapseOptions): Synapse
create(
options: SynapseOptions
options: 
(alias) interface SynapseOptions
import SynapseOptions
SynapseOptions): 
class Synapse
Synapse
  // Properties
  
SynapseAPI.client: Client
client: 
type Client<transport extends Transport = Transport, chain extends Chain | undefined = Chain | undefined, account extends Account | undefined = Account | undefined, rpcSchema extends RpcSchema | undefined = undefined, extended extends Extended | undefined = { ...; } | undefined> = Client_Base<transport, chain, account, rpcSchema> & (extended extends {
    [x: string]: unknown;
    account?: undefined;
    batch?: undefined;
    cacheTime?: undefined;
    ccipRead?: undefined;
    chain?: undefined;
    dataSuffix?: undefined;
    experimental_blockTag?: undefined;
    key?: undefined;
    name?: undefined;
    pollingInterval?: undefined;
    request?: undefined;
    transport?: undefined;
    type?: undefined;
    uid?: undefined;
} ? extended : unknown) & {
    extend: <const client extends {
        [x: string]: unknown;
        account?: undefined;
        batch?: undefined;
        cacheTime?: undefined;
        ccipRead?: undefined;
        ... 9 more ...;
        uid?: undefined;
    } & ExactPartial<ExtendableProtectedActions<...>>>(fn: (client: Client<transport, chain, account, rpcSchema, extended>) => client) => Client<transport, chain, account, rpcSchema, Prettify<client> & (extended extends {
        [x: string]: unknown;
        account?: undefined;
        batch?: undefined;
        cacheTime?: undefined;
        ccipRead?: undefined;
        ... 9 more ...;
        uid?: undefined;
    } ? extended : unknown)>;
}
Client
  
SynapseAPI.chain: Chain
chain: 
(alias) interface Chain
import Chain
Chain
  // Services
  
SynapseAPI.payments: PaymentsService
payments: 
class PaymentsService
PaymentsService
  
SynapseAPI.storage: StorageManager
storage: 
class StorageManager
StorageManager
  
SynapseAPI.providers: SPRegistryService
providers: 
class SPRegistryService
SPRegistryService
  
SynapseAPI.filbeam: FilBeamService
filbeam: 
class FilBeamService
FilBeamService
  // Storage provider info getter
  
SynapseAPI.getProviderInfo(providerAddress: string): Promise<PDPProvider>
getProviderInfo(
providerAddress: string
providerAddress: string): 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<
(alias) interface PDPProvider
import PDPProvider
PDPProvider>
}

Payment Operations

Fund your account and manage payments for Filecoin storage services.

When You Need This

Required before uploading files (must fund account and approve operators)
To monitor account balance and health
If you’re a service provider managing settlements

View Payment Operations Guide → - Learn the basics in less than 10 minutes

View Rails & Settlement Guide → - Learn the advanced payment concepts

Storage Operations

The SDK provides two storage approaches:

Auto-managed — The SDK handles provider selection and data set creation
Explicit control — Full control over providers, data sets, and batch operations

Key Concepts

Storage Contexts — Manage storage lifecycle and provider connections
Data Sets — Organize related data pieces with shared payment rails
PieceCIDs — Content-addressed identifiers for stored data
Service Providers — Decentralized storage with cryptographic proofs

View Storage Operations Guide → - Learn the basics in less than 10 minutes

View Storage Context Guide → - Learn the advanced storage concepts

View Storage Costs Guide → - Learn how to calculate your storage costs

Technical Constraints

Metadata Limits

Metadata is subject to the following contract-enforced limits:

Data Set Metadata

Maximum of 10 key-value pairs per data set
Keys: Maximum 32 characters
Values: Maximum 128 characters

Piece Metadata

Maximum of 5 key-value pairs per piece
Keys: Maximum 32 characters
Values: Maximum 128 characters

These limits are enforced by the blockchain contracts. The SDK will validate metadata before submission and throw descriptive errors if limits are exceeded.

Size Constraints

Upload size limits:

Minimum: 127 bytes (required for PieceCID calculation)
Maximum: ~1 GiB (1,065,353,216 bytes)

PieceCID

Understanding PieceCID is essential for working with Filecoin storage, as it serves as the unique identifier for your uploaded data.

PieceCID is Filecoin’s native content address identifier, a variant of CID. When you upload data, the SDK calculates a PieceCID—an identifier that:

Uniquely identifies your bytes, regardless of size, in a short string form
Enables retrieval from any provider storing those bytes
Contains embedded size information

Format Recognition:

PieceCID: Starts with bafkzcib, 64-65 characters - this is what Synapse SDK uses
LegacyPieceCID: Starts with baga6ea4seaq, 64 characters - for compatibility with other Filecoin services

PieceCID is also known as “CommP” or “Piece Commitment” in Filecoin documentation. The SDK exclusively uses PieceCID (v2 format) for all operations—you receive a PieceCID when uploading and use it for downloads.

LegacyPieceCID (v1 format) conversion utilities are provided for interoperability with other Filecoin services that may still use the older format.

Technical Reference: See FRC-0069 for the complete specification of PieceCID (“v2 Piece CID”) and its relationship to LegacyPieceCID (“v1 Piece CID”). Most Filecoin tooling currently uses v1, but the ecosystem is transitioning to v2.

Additional Resources

Getting Started - Installation and setup guide
Payment Operations Guide - Complete payment operations reference
Storage Operations Guide - Complete storage operations reference
API Reference - Full API documentation
GitHub Repository - Source code and examples