PaymentsService

Overview

The PaymentsService provides access to the Filecoin Pay contract for managing deposits, withdrawals, operator approvals, and payment rails. All operations use USDFC tokens. Access via synapse.payments.

Balance Operations

`balance()`

Get the available balance in the payments contract.

options

object

Show properties

token

TokenIdentifier

default:"USDFC"

Token to check balance for (currently only USDFC supported)

balance

bigint

Available funds in base units (18 decimals)

const balance = await synapse.payments.balance()
console.log('Available:', balance.toString())

`walletBalance()`

Get the token balance in the wallet.

options

object

Show properties

token

TokenIdentifier

default:"FIL"

Token to check (FIL or USDFC)

balance

bigint

Wallet balance in base units

// Check FIL balance
const filBalance = await synapse.payments.walletBalance({ token: 'FIL' })

// Check USDFC balance
const usdfc = await synapse.payments.walletBalance({ token: 'USDFC' })

`accountInfo()`

Get detailed account information from the payments contract.

options

object

Show properties

token

TokenIdentifier

default:"USDFC"

Token to get info for

info

object

Account information including:

availableFunds - Funds available for withdrawal
lockedFunds - Funds locked in active rails
Additional account details

const info = await synapse.payments.accountInfo()
console.log('Available:', info.availableFunds)
console.log('Locked:', info.lockedFunds)

`decimals()`

Get the number of decimals for tokens (both FIL and USDFC use 18).

decimals

number

Number of decimals (always 18)

const decimals = synapse.payments.decimals() // 18

Deposit Operations

`deposit()`

Deposit USDFC tokens into the payments contract.

options

DepositOptions

required

Deposit options

Show properties

amount

bigint

required

Amount to deposit in base units

Address

Recipient address (defaults to sender)

token

TokenIdentifier

default:"USDFC"

Token to deposit

onAllowanceCheck

(current, required) => void

Called when checking allowance

onApprovalTransaction

(tx: Hash) => void

Called when approval tx is sent

onApprovalConfirmed

(receipt) => void

Called when approval is confirmed

onDepositStarting

() => void

Called before deposit tx

txHash

Hash

Transaction hash of the deposit

import { parseUnits } from 'viem'

const amount = parseUnits('100', 18) // 100 USDFC

const txHash = await synapse.payments.deposit({
  amount,
  onAllowanceCheck: (current, required) => {
    if (current < required) {
      console.log('Approving USDFC spend...')
    }
  },
  onApprovalTransaction: (tx) => console.log('Approval tx:', tx),
  onDepositStarting: () => console.log('Depositing...')
})

console.log('Deposit tx:', txHash)

`depositWithPermit()`

Deposit using ERC-2612 permit to combine approval and deposit in one transaction.

options

object

required

Show properties

amount

bigint

required

Amount to deposit

deadline

bigint

Permit deadline (defaults to now + 1 hour)

token

TokenIdentifier

default:"USDFC"

Token to deposit

txHash

Hash

Transaction hash

const txHash = await synapse.payments.depositWithPermit({
  amount: parseUnits('100', 18)
})

`depositWithPermitAndApproveOperator()`

Deposit and approve a service operator in a single transaction.

options

object

required

Show properties

amount

bigint

required

Amount to deposit

operator

Address

Operator address (defaults to FWSS contract)

rateAllowance

bigint

Maximum rate per epoch

lockupAllowance

bigint

Maximum lockup amount

maxLockupPeriod

bigint

Maximum lockup period in epochs

txHash

Hash

Transaction hash

const txHash = await synapse.payments.depositWithPermitAndApproveOperator({
  amount: parseUnits('1000', 18),
  rateAllowance: parseUnits('10', 18),
  lockupAllowance: parseUnits('100', 18)
})

`withdraw()`

Withdraw funds from the payments contract.

options

object

required

Show properties

amount

bigint

required

Amount to withdraw

token

TokenIdentifier

default:"USDFC"

Token to withdraw

txHash

Hash

Transaction hash

const txHash = await synapse.payments.withdraw({
  amount: parseUnits('50', 18)
})

Operator Approvals

`approveService()`

Approve a service contract as an operator to manage payment rails.

options

object

Show properties

service

Address

Service contract address (defaults to FWSS)

rateAllowance

bigint

Maximum payment rate per epoch (defaults to max)

lockupAllowance

bigint

Maximum lockup amount (defaults to max)

maxLockupPeriod

bigint

Maximum lockup period in epochs (defaults to 30 days)

token

TokenIdentifier

default:"USDFC"

Token to approve for

txHash

Hash

Transaction hash

// Approve with custom limits
const txHash = await synapse.payments.approveService({
  rateAllowance: parseUnits('10', 18), // 10 USDFC per epoch
  lockupAllowance: parseUnits('1000', 18) // 1000 USDFC lockup
})

// Approve with defaults (maxUint256)
const txHash = await synapse.payments.approveService()

`revokeService()`

Revoke a service contract’s operator approval.

options

object

Show properties

service

Address

Service contract address (defaults to FWSS)

token

TokenIdentifier

default:"USDFC"

Token to revoke for

txHash

Hash

Transaction hash

const txHash = await synapse.payments.revokeService()

`serviceApproval()`

Check operator approval status and allowances.

options

object

Show properties

service

Address

Service contract address (defaults to FWSS)

token

TokenIdentifier

default:"USDFC"

Token to check

approval

object

Approval status:

isApproved - Whether operator is approved
rateAllowance - Maximum rate per epoch
lockupAllowance - Maximum lockup amount
rateUsage - Current rate usage
lockupUsage - Current lockup usage

const approval = await synapse.payments.serviceApproval()

if (!approval.isApproved) {
  console.log('Service not approved')
} else {
  console.log('Rate allowance:', approval.rateAllowance)
  console.log('Rate used:', approval.rateUsage)
  console.log('Lockup allowance:', approval.lockupAllowance)
  console.log('Lockup used:', approval.lockupUsage)
}

ERC20 Operations

`allowance()`

Check current ERC20 allowance for a spender.

options

object

required

Show properties

spender

Address

required

Spender address to check

token

TokenIdentifier

default:"USDFC"

Token to check

allowance

bigint

Current allowance amount

const allowance = await synapse.payments.allowance({
  spender: '0x...'
})

`approve()`

Approve an ERC20 spender.

options

object

required

Show properties

spender

Address

required

Spender address

amount

bigint

required

Amount to approve

token

TokenIdentifier

default:"USDFC"

Token to approve

txHash

Hash

Transaction hash

const txHash = await synapse.payments.approve({
  spender: '0x...',
  amount: parseUnits('100', 18)
})

Payment Rails

`getRail()`

Get detailed information about a payment rail.

options

object

required

Show properties

railId

bigint

required

Rail ID to query

rail

object

Rail information including payer, payee, rate, lockup, and settlement status

const rail = await synapse.payments.getRail({ railId: 1n })

console.log('Payer:', rail.payer)
console.log('Payee:', rail.payee)
console.log('Rate:', rail.rate)
console.log('Lockup:', rail.lockup)

`getRailsAsPayer()`

Get all rails where the wallet is the payer.

options

object

Show properties

token

TokenIdentifier

default:"USDFC"

Token to filter by

rails

RailInfo[]

Array of rail information

const rails = await synapse.payments.getRailsAsPayer()

rails.forEach(rail => {
  console.log(`Rail ${rail.railId}: ${rail.payee}`)
})

`getRailsAsPayee()`

Get all rails where the wallet is the payee.

options

object

Show properties

token

TokenIdentifier

default:"USDFC"

Token to filter by

rails

RailInfo[]

Array of rail information

const rails = await synapse.payments.getRailsAsPayee()

Settlement Operations

`settle()`

Settle a payment rail up to a specific epoch.

options

object

required

Show properties

railId

bigint

required

Rail ID to settle

untilEpoch

bigint

Epoch to settle up to (defaults to current)

txHash

Hash

Transaction hash

const txHash = await synapse.payments.settle({ railId: 1n })

// Partial settlement to past epoch
const txHash = await synapse.payments.settle({
  railId: 1n,
  untilEpoch: 1000n
})

`getSettlementAmounts()`

Preview settlement amounts without executing (read-only).

options

object

required

Show properties

railId

bigint

required

Rail ID

untilEpoch

bigint

Epoch to settle up to

result

SettlementResult

Settlement details:

totalSettledAmount - Total amount settled
totalNetPayeeAmount - Amount to payee after fees
totalOperatorCommission - Operator commission
totalNetworkFee - Network fee
finalSettledEpoch - Final epoch settled
note - Settlement note

const amounts = await synapse.payments.getSettlementAmounts({
  railId: 1n
})

console.log('Will settle:', amounts.totalSettledAmount)
console.log('Payee gets:', amounts.totalNetPayeeAmount)
console.log('Commission:', amounts.totalOperatorCommission)

`settleTerminatedRail()`

Emergency settlement for terminated rails (bypasses validation).

options

object

required

Show properties

railId

bigint

required

Terminated rail ID

txHash

Hash

Transaction hash

const txHash = await synapse.payments.settleTerminatedRail({
  railId: 1n
})

`settleAuto()`

Automatically detect rail status and settle appropriately.

options

object

required

Show properties

railId

bigint

required

Rail ID

untilEpoch

bigint

Epoch for active rails

txHash

Hash

Transaction hash

// Automatically uses settleTerminatedRail or settle
const txHash = await synapse.payments.settleAuto({ railId: 1n })

Complete Example

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

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

// Check wallet balance
const walletBalance = await synapse.payments.walletBalance({ 
  token: 'USDFC' 
})
console.log('Wallet:', formatUnits(walletBalance, 18), 'USDFC')

// Deposit funds
const depositTx = await synapse.payments.deposit({
  amount: parseUnits('100', 18),
  onApprovalTransaction: (tx) => console.log('Approving...', tx),
  onDepositStarting: () => console.log('Depositing...')
})
console.log('Deposited:', depositTx)

// Check contract balance
const balance = await synapse.payments.balance()
console.log('Contract balance:', formatUnits(balance, 18), 'USDFC')

// Approve storage service
const approval = await synapse.payments.serviceApproval()
if (!approval.isApproved) {
  const approveTx = await synapse.payments.approveService({
    rateAllowance: parseUnits('10', 18),
    lockupAllowance: parseUnits('50', 18)
  })
  console.log('Service approved:', approveTx)
}

// Check rails
const rails = await synapse.payments.getRailsAsPayer()
console.log('Active rails:', rails.length)

for (const rail of rails) {
  // Preview settlement
  const amounts = await synapse.payments.getSettlementAmounts({
    railId: rail.railId
  })
  console.log(`Rail ${rail.railId} owes:`, 
    formatUnits(amounts.totalSettledAmount, 18))
}

Synapse SDK

Synapse Core

React Hooks

Types & Errors

Overview

Balance Operations

`balance()`

`walletBalance()`

`accountInfo()`

`decimals()`

Deposit Operations

`deposit()`

`depositWithPermit()`

`depositWithPermitAndApproveOperator()`

`withdraw()`

Operator Approvals

`approveService()`

`revokeService()`

`serviceApproval()`

ERC20 Operations

`allowance()`

`approve()`

Payment Rails

`getRail()`

`getRailsAsPayer()`

`getRailsAsPayee()`

Settlement Operations

`settle()`

`getSettlementAmounts()`

`settleTerminatedRail()`

`settleAuto()`

Complete Example

See Also

Build docs developers (and LLMs) love

Synapse SDK

Synapse Core

React Hooks

Types & Errors

​Overview

​Balance Operations

​balance()

​walletBalance()

​accountInfo()

​decimals()

​Deposit Operations

​deposit()

​depositWithPermit()

​depositWithPermitAndApproveOperator()

​withdraw()

​Operator Approvals

​approveService()

​revokeService()

​serviceApproval()

​ERC20 Operations

​allowance()

​approve()

​Payment Rails

​getRail()

​getRailsAsPayer()

​getRailsAsPayee()

​Settlement Operations

​settle()

​getSettlementAmounts()

​settleTerminatedRail()

​settleAuto()

​Complete Example

​See Also

Build docs developers (and LLMs) love

Overview

Balance Operations

`balance()`

`walletBalance()`

`accountInfo()`

`decimals()`

Deposit Operations

`deposit()`

`depositWithPermit()`

`depositWithPermitAndApproveOperator()`

`withdraw()`

Operator Approvals

`approveService()`

`revokeService()`

`serviceApproval()`

ERC20 Operations

`allowance()`

`approve()`

Payment Rails

`getRail()`

`getRailsAsPayer()`

`getRailsAsPayee()`

Settlement Operations

`settle()`

`getSettlementAmounts()`

`settleTerminatedRail()`

`settleAuto()`

Complete Example

See Also