PaymentsService

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

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

Constructors

Constructor

new PaymentsService(client): PaymentsService

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

Parameters

Parameter	Type	Description
client	Client<Transport, Chain, Account>	Client instance for balance checks, nonce management, and epoch calculations

Returns

PaymentsService

Methods

accountInfo()

accountInfo(token): Promise<{ availableFunds: bigint; funds: bigint; lockupCurrent: bigint; lockupLastSettledAt: bigint; lockupRate: bigint; }>

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

Get detailed account information from the payments contract

Parameters

Parameter	Type	Default value	Description
token	string	TOKENS.USDFC	The token to get account info for (defaults to USDFC)

Returns

Promise<{ availableFunds: bigint; funds: bigint; lockupCurrent: bigint; lockupLastSettledAt: bigint; lockupRate: bigint; }>

Account information including funds, lockup details, and available balance

---

allowance()

allowance(spender, token): Promise<bigint>

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

Check the current ERC20 token allowance for a spender

Parameters

Parameter	Type	Default value	Description
spender	`0x${string}`	undefined	The address to check allowance for
token	string	TOKENS.USDFC	The token to check allowance for (defaults to USDFC)

Returns

Promise<bigint>

The current allowance amount as bigint

---

approve()

approve(spender, amount, token): Promise<`0x${string}`>

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

Approve an ERC20 token spender

Parameters

Parameter	Type	Default value	Description
spender	`0x${string}`	undefined	The address to approve as spender
amount	bigint	undefined	The amount to approve
token	string	TOKENS.USDFC	The token to approve spending for (defaults to USDFC)

Returns

Promise<`0x${string}`>

Transaction response object

---

approveService()

approveService(service, rateAllowance, lockupAllowance, maxLockupPeriod, token): Promise<`0x${string}`>

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

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	Default value	Description
service	`0x${string}`	undefined	The service contract address to approve
rateAllowance	bigint	undefined	Maximum payment rate per epoch the operator can set
lockupAllowance	bigint	undefined	Maximum lockup amount the operator can set
maxLockupPeriod	bigint	undefined	Maximum lockup period in epochs the operator can set
token	string	TOKENS.USDFC	The token to approve for (defaults to USDFC)

Returns

Promise<`0x${string}`>

Transaction response object

---

balance()

balance(token): Promise<bigint>

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

Parameters

Parameter	Type	Default value
token	string	TOKENS.USDFC

Returns

Promise<bigint>

---

decimals()

decimals(_token): number

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

Parameters

Parameter	Type	Default value
_token	string	TOKENS.USDFC

Returns

number

---

deposit()

deposit(amount, token, options?): Promise<`0x${string}`>

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

Parameters

Parameter	Type	Default value
amount	bigint	undefined
token	string	TOKENS.USDFC
options?	DepositOptions	undefined

Returns

Promise<`0x${string}`>

---

depositWithPermit()

depositWithPermit(amount, token, deadline?): Promise<`0x${string}`>

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

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	Default value	Description
amount	bigint	undefined	Amount of USDFC to deposit (in base units)
token	string	TOKENS.USDFC	Token identifier (currently only USDFC is supported)
deadline?	bigint	undefined	Unix timestamp (seconds) when the permit expires. Defaults to now + 1 hour.

Returns

Promise<`0x${string}`>

Transaction response object

---

depositWithPermitAndApproveOperator()

depositWithPermitAndApproveOperator(amount, operator?, rateAllowance?, lockupAllowance?, maxLockupPeriod?, deadline?, token?): Promise<`0x${string}`>

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

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	Default value	Description
amount	bigint	undefined	Amount of USDFC to deposit (in base units)
operator?	`0x${string}`	undefined	Service/operator address to approve
rateAllowance?	bigint	undefined	Max payment rate per epoch operator can set
lockupAllowance?	bigint	undefined	Max lockup amount operator can set
maxLockupPeriod?	bigint	undefined	Max lockup period in epochs operator can set
deadline?	bigint	undefined	Unix timestamp (seconds) when the permit expires. Defaults to now + 1 hour.
token?	string	TOKENS.USDFC	Token identifier (currently only USDFC supported)

Returns

Promise<`0x${string}`>

Transaction response object

---

getRail()

getRail(railId): Promise<{ commissionRateBps: bigint; endEpoch: bigint; from: `0x${string}`; lockupFixed: bigint; lockupPeriod: bigint; operator: `0x${string}`; paymentRate: bigint; serviceFeeRecipient: `0x${string}`; settledUpTo: bigint; to: `0x${string}`; token: `0x${string}`; validator: `0x${string}`; }>

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

Get detailed information about a specific rail

Parameters

Parameter	Type	Description
railId	bigint	The rail ID to query

Returns

Promise<{ commissionRateBps: bigint; endEpoch: bigint; from: `0x${string}`; lockupFixed: bigint; lockupPeriod: bigint; operator: `0x${string}`; paymentRate: bigint; serviceFeeRecipient: `0x${string}`; settledUpTo: bigint; to: `0x${string}`; token: `0x${string}`; validator: `0x${string}`; }>

Rail information including all parameters and current state

Throws

Error if the rail doesn’t exist or is inactive (contract reverts with RailInactiveOrSettled)

---

getRailsAsPayee()

getRailsAsPayee(token): Promise<RailInfo[]>

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

Get all rails where the wallet is the payee

Parameters

Parameter	Type	Default value	Description
token	string	TOKENS.USDFC	The token to filter by (defaults to USDFC)

Returns

Promise<RailInfo[]>

Array of rail information

---

getRailsAsPayer()

getRailsAsPayer(token): Promise<RailInfo[]>

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

Get all rails where the wallet is the payer

Parameters

Parameter	Type	Default value	Description
token	string	TOKENS.USDFC	The token to filter by (defaults to USDFC)

Returns

Promise<RailInfo[]>

Array of rail information

---

getSettlementAmounts()

getSettlementAmounts(railId, untilEpoch?): Promise<SettlementResult>

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

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

Parameters

Parameter	Type	Description
railId	bigint	The rail ID to check
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

---

revokeService()

revokeService(service, token): Promise<`0x${string}`>

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

Revoke a service contract’s operator approval

Parameters

Parameter	Type	Default value	Description
service	`0x${string}`	undefined	The service contract address to revoke
token	string	TOKENS.USDFC	The token to revoke approval for (defaults to USDFC)

Returns

Promise<`0x${string}`>

Transaction response object

---

serviceApproval()

serviceApproval(service, token): Promise<OutputType>

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

Get the operator approval status and allowances for a service

Parameters

Parameter	Type	Default value	Description
service	`0x${string}`	undefined	The service contract address to check
token	string	TOKENS.USDFC	The token to check approval for (defaults to USDFC)

Returns

Promise<OutputType>

Approval status and allowances

---

settle()

settle(railId, untilEpoch?): Promise<`0x${string}`>

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

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

Parameters

Parameter	Type	Description
railId	bigint	The rail ID to settle
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 response object

Throws

Error if untilEpoch is in the future (contract reverts with CannotSettleFutureEpochs)

---

settleAuto()

settleAuto(railId, untilEpoch?): Promise<`0x${string}`>

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

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
railId	bigint	The rail ID to settle
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

Throws

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

Example

// Automatically detect and settle appropriately
const tx = await synapse.payments.settleAuto(railId)
await tx.wait()

// For active rails, can specify epoch
const tx = await synapse.payments.settleAuto(railId, specificEpoch)

---

settleTerminatedRail()

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

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

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
railId	bigint	The rail ID to settle

Returns

Promise<`0x${string}`>

Transaction response object

---

walletBalance()

walletBalance(token?): Promise<bigint>

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

Parameters

Parameter	Type
token?	string

Returns

Promise<bigint>

---

withdraw()

withdraw(amount, token): Promise<`0x${string}`>

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

Parameters

Parameter	Type	Default value
amount	bigint	undefined
token	string	TOKENS.USDFC

Returns

Promise<`0x${string}`>