PaymentsService

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

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:55

Create a new PaymentsService instance

Parameters

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

Returns

PaymentsService

A new PaymentsService instance

Methods

accountInfo()

accountInfo(options?): Promise<OutputType>

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

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

---

allowance()

allowance(options): Promise<bigint>

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

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:226

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:265

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 30 days in epochs)
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:90

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:177

Returns

number

---

deposit()

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

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

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:444

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:522

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

---

getRail()

getRail(options): Promise<OutputType>

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

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:754

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:727

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:611

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:310

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:345

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:595

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:707

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 })

---

settleTerminatedRail()

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

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

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

---

walletBalance()

walletBalance(options?): Promise<bigint>

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

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:574

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