PaymentsService

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

Constructors

Constructor

new PaymentsService(
   provider,
   signer,
   paymentsAddress,
   usdfcAddress,
   disableNonceManager): PaymentsService;

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

Parameters

Parameter	Type	Description
provider	Provider	Direct provider instance for balance checks, nonce management, and epoch calculations
signer	Signer	Signer instance for transaction signing (may be wrapped in NonceManager)
paymentsAddress	string	Address of the Payments contract
usdfcAddress	string	Address of the USDFC token contract
disableNonceManager	boolean	When true, manually manages nonces using provider.getTransactionCount() Note: Both provider and signer are required for NonceManager compatibility. When NonceManager is disabled, we need direct provider access for reliable nonce management. Using signer.provider could interfere with NonceManager’s internal state or behave differently with MetaMask/hardware wallets.

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

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

Check the current ERC20 token allowance for a spender

Parameters

Parameter	Type	Default value	Description
spender	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<TransactionResponse>;

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

Approve an ERC20 token spender

Parameters

Parameter	Type	Default value	Description
spender	string	undefined	The address to approve as spender
amount	TokenAmount	undefined	The amount to approve
token	string	TOKENS.USDFC	The token to approve spending for (defaults to USDFC)

Returns

Promise<TransactionResponse>

Transaction response object

---

approveService()

approveService(
   service,
   rateAllowance,
   lockupAllowance,
   maxLockupPeriod,
token): Promise<TransactionResponse>;

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

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	string	undefined	The service contract address to approve
rateAllowance	TokenAmount	undefined	Maximum payment rate per epoch the operator can set
lockupAllowance	TokenAmount	undefined	Maximum lockup amount the operator can set
maxLockupPeriod	TokenAmount	undefined	Maximum lockup period in epochs the operator can set
token	string	TOKENS.USDFC	The token to approve for (defaults to USDFC)

Returns

Promise<TransactionResponse>

Transaction response object

---

balance()

balance(token): Promise<bigint>;

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

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

Parameters

Parameter	Type	Default value
_token	string	TOKENS.USDFC

Returns

number

---

deposit()

deposit(
   amount,
   token,
callbacks?): Promise<TransactionResponse>;

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

Parameters

Parameter	Type	Default value
amount	TokenAmount	undefined
token	string	TOKENS.USDFC
callbacks?	DepositCallbacks	undefined

Returns

Promise<TransactionResponse>

---

depositWithPermit()

depositWithPermit(
   amount,
   token,
deadline?): Promise<TransactionResponse>;

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

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

Returns

Promise<TransactionResponse>

Transaction response object

---

depositWithPermitAndApproveOperator()

depositWithPermitAndApproveOperator(
   amount,
   operator,
   rateAllowance,
   lockupAllowance,
   maxLockupPeriod,
   token,
deadline?): Promise<TransactionResponse>;

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

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

Returns

Promise<TransactionResponse>

Transaction response object

---

getRail()

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

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

Get detailed information about a specific rail

Parameters

Parameter	Type	Description
railId	number | bigint	The rail ID to query

Returns

Promise<{ commissionRateBps: bigint; endEpoch: bigint; from: string; lockupFixed: bigint; lockupPeriod: bigint; operator: string; paymentRate: bigint; serviceFeeRecipient: string; settledUpTo: bigint; to: string; token: string; validator: 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:1095

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

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

Get the expected settlement amounts for a rail (read-only simulation) Note: The actual settlement will require a network fee (FIL) to be sent with the transaction

Parameters

Parameter	Type	Description
railId	number | bigint	The rail ID to check
untilEpoch?	number | 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<TransactionResponse>;

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

Revoke a service contract’s operator approval

Parameters

Parameter	Type	Default value	Description
service	string	undefined	The service contract address to revoke
token	string	TOKENS.USDFC	The token to revoke approval for (defaults to USDFC)

Returns

Promise<TransactionResponse>

Transaction response object

---

serviceApproval()

serviceApproval(service, token): Promise<{
  isApproved: boolean;
  lockupAllowance: bigint;
  lockupUsed: bigint;
  maxLockupPeriod: bigint;
  rateAllowance: bigint;
  rateUsed: bigint;
}>;

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

Get the operator approval status and allowances for a service

Parameters

Parameter	Type	Default value	Description
service	string	undefined	The service contract address to check
token	string	TOKENS.USDFC	The token to check approval for (defaults to USDFC)

Returns

Promise<{ isApproved: boolean; lockupAllowance: bigint; lockupUsed: bigint; maxLockupPeriod: bigint; rateAllowance: bigint; rateUsed: bigint; }>

Approval status and allowances

---

settle()

settle(railId, untilEpoch?): Promise<TransactionResponse>;

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

Settle a payment rail up to a specific epoch (sends a transaction) Note: This method automatically includes the required network fee (FIL) for burning

Parameters

Parameter	Type	Description
railId	number | bigint	The rail ID to settle
untilEpoch?	number | 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<TransactionResponse>

Transaction response object

Throws

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

---

settleAuto()

settleAuto(railId, untilEpoch?): Promise<TransactionResponse>;

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

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 (requires settlement fee)

Parameters

Parameter	Type	Description
railId	number | bigint	The rail ID to settle
untilEpoch?	number | bigint	The epoch to settle up to (must be <= current epoch for active rails; ignored for terminated rails)

Returns

Promise<TransactionResponse>

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<TransactionResponse>;

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

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

Returns

Promise<TransactionResponse>

Transaction response object

---

walletBalance()

walletBalance(token?): Promise<bigint>;

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

Parameters

Parameter	Type
token?	string

Returns

Promise<bigint>

---

withdraw()

withdraw(amount, token): Promise<TransactionResponse>;

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

Parameters

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

Returns

Promise<TransactionResponse>