Skip to main content

​
Overview

The Synapse class is the primary interface for interacting with Filecoin Onchain Cloud. It provides access to storage operations, payment management, and service provider interactions through a unified API.

​
Creation

​
Synapse.create()

Create a new Synapse instance with configuration options.
​
options
SynapseOptions
required
Configuration options for the Synapse instance
​
synapse
Synapse
A fully initialized Synapse instance
import { Synapse } from '@filoz/synapse-sdk'
import { privateKeyToAccount } from 'viem/accounts'
import { http } from 'viem'
import { calibration } from '@filoz/synapse-core/chains'

const account = privateKeyToAccount('0x...')

const synapse = Synapse.create({
  account,
  transport: http('https://api.calibration.node.glif.io/rpc/v1'),
  chain: calibration,
  withCDN: true
})

​
Properties

​
synapse.storage

Access the StorageManager for all storage operations. 
const result = await synapse.storage.upload(data)

​
synapse.payments

Access the PaymentsService for deposits, withdrawals, and payment rails. 
const balance = await synapse.payments.balance()

​
synapse.providers

Access the SPRegistryService for service provider information. 
const providers = await synapse.providers.getProviders()

​
synapse.filbeam

Access the FilBeamService for CDN statistics and monitoring. 
const stats = await synapse.filbeam.getDataSetStats(dataSetId)

​
synapse.client

The underlying Viem client with public actions. 
const blockNumber = await synapse.client.getBlockNumber()

​
synapse.sessionClient

The session key client if configured, otherwise undefined.

​
synapse.chain

The Filecoin chain configuration. 
console.log(synapse.chain.name) // "Filecoin - Calibration testnet"

​
Methods

​
getProviderInfo()

Get detailed information about a specific service provider.
​
providerAddress
Address | bigint
required
Provider’s address or provider ID
​
provider
PDPProvider
Provider information including:
  • id - Provider ID
  • serviceProvider - Provider’s address
  • pdp.serviceURL - PDP endpoint URL
  • Pricing and metadata
// By provider ID
const provider = await synapse.getProviderInfo(1n)

// By address
const provider = await synapse.getProviderInfo('0x...')

console.log(provider.pdp.serviceURL)

​
Complete Example

import { Synapse } from '@filoz/synapse-sdk'
import { privateKeyToAccount } from 'viem/accounts'
import { calibration } from '@filoz/synapse-core/chains'

// Initialize Synapse
const account = privateKeyToAccount(process.env.PRIVATE_KEY)
const synapse = Synapse.create({
  account,
  chain: calibration,
  withCDN: true
})

// Upload data
const data = new Uint8Array([1, 2, 3, 4])
const uploadResult = await synapse.storage.upload(data)

console.log('Uploaded to:', uploadResult.copies.length, 'providers')
console.log('PieceCID:', uploadResult.pieceCid.toString())

// Download data
const retrieved = await synapse.storage.download({
  pieceCid: uploadResult.pieceCid
})

// Check balance
const balance = await synapse.payments.balance()
console.log('Balance:', balance.toString())

​
Error Handling

try {
  const result = await synapse.storage.upload(data)
} catch (error) {
  if (error instanceof Error) {
    console.error('Upload failed:', error.message)
  }
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us