PaymentsService

Defined in: packages/synapse-sdk/src/payments/service.ts:44

PaymentsService - Filecoin Pay client for managing deposits, approvals, and payment rails

Constructors

Constructor

new PaymentsService(options): PaymentsService

Defined in: packages/synapse-sdk/src/payments/service.ts:54

Create a new PaymentsService instance

Parameters

Parameter	Type	Description
options	{ client: Client<Transport, Chain, Account>; readClient?: Client<Transport, Chain>; }	Options for the PaymentsService
options.client	Client<Transport, Chain, Account>	Viem wallet client
options.readClient?	Client<Transport, Chain>	-

Returns

PaymentsService

A new PaymentsService instance

Methods

accountInfo()

accountInfo(options?): Promise<OutputType>

Defined in: packages/synapse-sdk/src/payments/service.ts:109

Get detailed account information from the payments contract

Parameters

Parameter	Type	Description
options	{ token?: string; }	Options for the account info
options.token?	string	The token to get account info for (defaults to USDFC)

Returns

Promise<OutputType>

Account information Pay.accounts.OutputType

Throws

Errors Pay.accounts.ErrorType

---

accountSummary()

accountSummary(options?): Promise<OutputType>

Defined in: packages/synapse-sdk/src/payments/service.ts:721

Get a comprehensive account summary including balances, rates, lockup breakdown, and timeline.

Parameters

Parameter	Type	Description
options	{ epoch?: bigint; token?: string; }	Options for the account summary
options.epoch?	bigint	Epoch to evaluate at (defaults to current block number)
options.token?	string	The token to query (defaults to USDFC)

Returns

Promise<OutputType>

Full account summary Pay.getAccountSummary.OutputType

Throws

Errors Pay.getAccountSummary.ErrorType

---

allowance()

allowance(options): Promise<bigint>

Defined in: packages/synapse-sdk/src/payments/service.ts:189

Check the current ERC20 token allowance for a spender

Parameters

Parameter	Type	Description
options	{ spender: `0x${string}`; token?: string; }	Options for the allowance check
options.spender	`0x${string}`	The address to check allowance for
options.token?	string	The token to check allowance for (defaults to USDFC)

Returns

Promise<bigint>

The current allowance amount as bigint

Throws

Errors ERC20.balance.ErrorType

---

approve()

approve(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:224

Approve an ERC20 token spender

Parameters

Parameter	Type	Description
options	{ amount: bigint; spender: `0x${string}`; token?: string; }	Options for the approve
options.amount	bigint	The amount to approve
options.spender	`0x${string}`	The address to approve as spender
options.token?	string	The token to approve spending for (defaults to USDFC)

Returns

Promise<`0x${string}`>

Transaction response object

---

approveService()

approveService(options?): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:263

Approve a service contract to act as an operator for payment rails This allows the service contract (such as Warm Storage) to create and manage payment rails on behalf of the client

Parameters

Parameter	Type	Description
options	{ lockupAllowance?: bigint; maxLockupPeriod?: bigint; rateAllowance?: bigint; service?: `0x${string}`; token?: string; }	Options for the approve service
options.lockupAllowance?	bigint	Maximum lockup amount the operator can set (defaults to maxUint256)
options.maxLockupPeriod?	bigint	Maximum lockup period in epochs the operator can set (defaults to the chain’s getPriceList().lockups.defaultLockupPeriod)
options.rateAllowance?	bigint	Maximum payment rate per epoch the operator can set (defaults to maxUint256)
options.service?	`0x${string}`	The service contract address to approve (defaults to Warm Storage contract address)
options.token?	string	The token to approve for (defaults to USDFC)

Returns

Promise<`0x${string}`>

Transaction hash Hash

Throws

Errors Pay.setOperatorApproval.ErrorType

---

balance()

balance(options?): Promise<bigint>

Defined in: packages/synapse-sdk/src/payments/service.ts:88

Get the balance of the payments contract

Parameters

Parameter	Type	Description
options	{ token?: string; }	Options for the balance
options.token?	string	The token to get balance for (defaults to USDFC)

Returns

Promise<bigint>

The balance of the payments contract

Throws

Errors Pay.accounts.ErrorType

---

decimals()

decimals(): number

Defined in: packages/synapse-sdk/src/payments/service.ts:175

Returns

number

---

deposit()

deposit(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:378

Deposit funds into the payments contract

Parameters

Parameter	Type	Description
options	DepositOptions	Options for the deposit DepositOptions

Returns

Promise<`0x${string}`>

Transaction hash Hash

Throws

Errors ERC20.balance.ErrorType | ERC20.approve.ErrorType | Pay.deposit.ErrorType

---

depositWithPermit()

depositWithPermit(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:442

Deposit funds using ERC-2612 permit to approve and deposit in a single transaction This method creates an EIP-712 typed-data signature for the USDFC token’s permit, then calls the Payments contract depositWithPermit to pull funds and credit the account.

Parameters

Parameter	Type	Description
options	{ amount: bigint; deadline?: bigint; token?: string; }	Options for the deposit with permit DepositWithPermitOptions
options.amount	bigint	Amount of USDFC to deposit (in base units)
options.deadline?	bigint	Unix timestamp (seconds) when the permit expires. Defaults to now + 1 hour.
options.token?	string	Token identifier (currently only USDFC is supported)

Returns

Promise<`0x${string}`>

Transaction response object Hash

Throws

Errors ERC20.balanceForPermit.ErrorType | ERC20.permit.ErrorType | Pay.depositWithPermit.ErrorType

---

depositWithPermitAndApproveOperator()

depositWithPermitAndApproveOperator(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:480

Deposit funds using ERC-2612 permit and approve an operator in a single transaction This signs an EIP-712 permit for the USDFC token and calls the Payments contract function depositWithPermitAndApproveOperator which both deposits and sets operator approval.

Parameters

Parameter	Type	Description
options	{ amount: bigint; deadline?: bigint; lockupAllowance?: bigint; maxLockupPeriod?: bigint; operator?: `0x${string}`; rateAllowance?: bigint; token?: string; }	Options for the deposit with permit and approve operator
options.amount	bigint	Amount of USDFC to deposit (in base units)
options.deadline?	bigint	Unix timestamp (seconds) when the permit expires. Defaults to now + 1 hour.
options.lockupAllowance?	bigint	Max lockup amount operator can set
options.maxLockupPeriod?	bigint	Max lockup period in epochs operator can set
options.operator?	`0x${string}`	Service/operator address to approve
options.rateAllowance?	bigint	Max payment rate per epoch operator can set
options.token?	string	Token identifier (currently only USDFC supported)

Returns

Promise<`0x${string}`>

Transaction hash Hash

Throws

Errors ERC20.balanceForPermit.ErrorType | ERC20.permit.ErrorType | Pay.depositWithPermitAndApproveOperator.ErrorType

---

fund()

fund(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:534

Smart deposit method that picks the right contract call based on FWSS approval state.

• If FWSS needs approval AND amount > 0: calls depositWithPermitAndApproveOperator with maxUint256 rate/lockup allowances and the chain’s default lockup period.
• If FWSS needs approval AND amount === 0: calls approveService with maxUint256 rate/lockup allowances and the chain’s default lockup period.
• If FWSS is approved AND amount > 0: calls depositWithPermit.
• If FWSS is approved AND amount === 0: no-op, returns empty hash.

Parameters

Parameter	Type	Description
options	OptionsType	FundOptions

Returns

Promise<`0x${string}`>

Transaction hash Hash

---

fundSync()

fundSync(options): Promise<OutputType>

Defined in: packages/synapse-sdk/src/payments/service.ts:552

Smart deposit and wait for confirmation.

Same routing logic as fund, but waits for the transaction receipt. Supports an onHash callback that fires once the transaction is submitted (before waiting for confirmation).

Parameters

Parameter	Type	Description
options	OptionsType	Pay.fundSync.OptionsType

Returns

Promise<OutputType>

Transaction hash and receipt Pay.fundSync.OutputType

---

getRail()

getRail(options): Promise<OutputType>

Defined in: packages/synapse-sdk/src/payments/service.ts:659

Get detailed information about a specific rail

Parameters

Parameter	Type	Description
options	{ railId: bigint; }	Options for the get rail
options.railId	bigint	The rail ID to query

Returns

Promise<OutputType>

Rail information including all parameters and current state Pay.getRail.OutputType

Throws

When the rail does not exist or is inactive

---

getRailsAsPayee()

getRailsAsPayee(options?): Promise<RailInfo[]>

Defined in: packages/synapse-sdk/src/payments/service.ts:816

Get all rails where the wallet is the payee

Parameters

Parameter	Type	Description
options	{ token?: string; }	Options for the get rails as payee
options.token?	string	The token to filter by (defaults to USDFC)

Returns

Promise<RailInfo[]>

Array of rail information []

---

getRailsAsPayer()

getRailsAsPayer(options?): Promise<RailInfo[]>

Defined in: packages/synapse-sdk/src/payments/service.ts:786

Get all rails where the wallet is the payer

Parameters

Parameter	Type	Description
options	{ token?: string; }	Options for the get rails as payer
options.token?	string	The token to filter by (defaults to USDFC)

Returns

Promise<RailInfo[]>

Array of rail information []

---

getSettlementAmounts()

getSettlementAmounts(options): Promise<SettlementResult>

Defined in: packages/synapse-sdk/src/payments/service.ts:602

Get the expected settlement amounts for a rail (read-only simulation)

Parameters

Parameter	Type	Description
options	{ railId: bigint; untilEpoch?: bigint; }	Options for the get settlement amounts
options.railId	bigint	The rail ID to check
options.untilEpoch?	bigint	The epoch to settle up to (must be <= current epoch; defaults to current). Can be used to preview partial settlements to a past epoch.

Returns

Promise<SettlementResult>

Settlement result with amounts and details SettlementResult

---

revokeService()

revokeService(options?): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:308

Revoke a service contract’s operator approval

Parameters

Parameter	Type	Description
options	{ service?: `0x${string}`; token?: string; }	Options for the revoke service
options.service?	`0x${string}`	The service contract address to revoke (defaults to Warm Storage contract address)
options.token?	string	The token to revoke approval for (defaults to USDFC)

Returns

Promise<`0x${string}`>

Transaction hash Hash

Throws

Errors Pay.setOperatorApproval.ErrorType

---

serviceApproval()

serviceApproval(options?): Promise<OutputType>

Defined in: packages/synapse-sdk/src/payments/service.ts:343

Get the operator approval status and allowances for a service

Parameters

Parameter	Type	Description
options	{ service?: `0x${string}`; token?: string; }	Options for the service approval
options.service?	`0x${string}`	The service contract address to check (defaults to Warm Storage contract address)
options.token?	string	The token to check approval for (defaults to USDFC)

Returns

Promise<OutputType>

Approval status and allowances Pay.operatorApprovals.OutputType

Throws

Errors Pay.operatorApprovals.ErrorType

---

settle()

settle(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:590

Settle a payment rail up to a specific epoch (sends a transaction)

Parameters

Parameter	Type	Description
options	{ railId: bigint; untilEpoch?: bigint; }	Options for the settle
options.railId	bigint	The rail ID to settle
options.untilEpoch?	bigint	The epoch to settle up to (must be <= current epoch; defaults to current). Can be used for partial settlements to a past epoch.

Returns

Promise<`0x${string}`>

Transaction hash Hash

Throws

Errors Pay.settleRail.ErrorType

---

settleAuto()

settleAuto(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:698

Automatically settle a rail, detecting whether it’s terminated or active This method checks the rail status and calls the appropriate settlement method:

• For terminated rails: calls settleTerminatedRail()
• For active rails: calls settle() with optional untilEpoch

Parameters

Parameter	Type	Description
options	{ railId: bigint; untilEpoch?: bigint; }	Options for the settle auto
options.railId	bigint	The rail ID to settle
options.untilEpoch?	bigint	The epoch to settle up to (must be <= current epoch for active rails; ignored for terminated rails)

Returns

Promise<`0x${string}`>

Transaction response object Hash

Throws

Error if rail doesn’t exist (contract reverts with RailInactiveOrSettled) or other settlement errors

Example

// Automatically detect and settle appropriately
const hash = await synapse.payments.settleAuto({ railId })

// For active rails, can specify epoch
const hash = await synapse.payments.settleAuto({ railId, untilEpoch: specificEpoch })

Copy to clipboard

---

settleTerminatedRail()

settleTerminatedRail(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:648

Emergency settlement for terminated rails only - bypasses service contract validation This ensures payment even if the validator contract is buggy or unresponsive (pays in full) Can only be called by the client after the max settlement epoch has passed

Parameters

Parameter	Type	Description
options	{ railId: bigint; }	Options for the settle terminated rail
options.railId	bigint	The rail ID to settle

Returns

Promise<`0x${string}`>

Transaction hash Hash

Throws

Errors Pay.settleTerminatedRailWithoutValidation.ErrorType

---

totalAccountFixedLockup()

totalAccountFixedLockup(options?): Promise<OutputType>

Defined in: packages/synapse-sdk/src/payments/service.ts:754

Get the total fixed lockup across all rails.

Fetches all rails for the account and sums their lockupFixed values. Includes terminated-but-not-finalized rails since they still hold locked funds.

Parameters

Parameter	Type	Description
options	{ token?: string; }	Options for the total account fixed lockup
options.token?	string	The token to query (defaults to USDFC)

Returns

Promise<OutputType>

Total fixed lockup Pay.totalAccountFixedLockup.OutputType

Throws

Errors Pay.totalAccountFixedLockup.ErrorType

---

walletBalance()

walletBalance(options?): Promise<bigint>

Defined in: packages/synapse-sdk/src/payments/service.ts:131

Get the balance of the wallet

Parameters

Parameter	Type	Description
options	{ token?: string; }	Options for the wallet balance
options.token?	string	The token to get wallet balance for (defaults to FIL)

Returns

Promise<bigint>

The balance of the wallet

Throws

Errors getBalance.ErrorType

---

withdraw()

withdraw(options): Promise<`0x${string}`>

Defined in: packages/synapse-sdk/src/payments/service.ts:569

Withdraw funds from the payments contract

Parameters

Parameter	Type	Description
options	{ amount: bigint; token?: string; }	Options for the withdraw
options.amount	bigint	The amount to withdraw
options.token?	string	The token to withdraw (defaults to USDFC)

Returns

Promise<`0x${string}`>

Transaction hash Hash

Throws

Errors Pay.withdraw.ErrorType

---

create()

static create(options): PaymentsService

Defined in: packages/synapse-sdk/src/payments/service.ts:68

Create a new PaymentsService with pre-configured client

Parameters

Parameter	Type	Description
options	{ account: Account; chain?: Chain; transport?: Transport; }	Options for the PaymentsService
options.account	Account	Viem account (required)
options.chain?	Chain	Filecoin chain (optional, defaults to DEFAULT_CHAIN)
options.transport?	Transport	Viem transport (optional, defaults to http())

Returns

PaymentsService

A new PaymentsService instance