Payment Operations

The Synapse SDK uses USDFC (a Filecoin-native stablecoin) for storage payments. Before uploading files, you must fund your account and approve operators.

This guide covers the essential operations. For advanced topics (understanding rails, settlement strategies), see Rails & Settlement.

Before working with payments, familiarize yourself with these fundamental concepts:

Key Concepts

• USDFC Token: Stablecoin on Filecoin which is used for all storage payments. The protocol requires USDFC approval before operations.
• Payment Rails: Continuous payment streams created automatically when you upload files. Rate is fixed per epoch.
• Epochs: Time periods (one epoch is 30 seconds). Payments accumulate per epoch and can be settled periodically.
• Operator Allowances: Permissions that allow contracts (like WarmStorage) to spend your USDFC and create payment rails.

Account Management

Check Your Balance

Monitor your account balance to ensure you have sufficient funds for storage operations.

const walletBalance = await synapse.payments.walletBalance();
const accountInfo = await synapse.payments.accountInfo();

console.log("Available:", accountInfo.availableFunds);
console.log("Locked:", accountInfo.lockupCurrent);
console.log("Spending rate:", accountInfo.lockupRate, "per epoch");

Copy to clipboard

Fund Your Account

import { TOKENS } from "@filoz/synapse-sdk";

const amount = parseUnits("100");
const hash = await synapse.payments.depositWithPermit({ amount });
await synapse.client.waitForTransactionReceipt({ hash });

Copy to clipboard

Alternative: Two-Transaction Deposit (not recommended)

If you cannot use permit-based deposits, you can use the traditional two-transaction approach:

const filecoinpay = synapse.chain.contracts.filecoinPay.address
const amount = parseUnits("100");

// 1. Approve USDFC spending
await synapse.payments.approve({spender: filecoinpay, amount});

// 2. Deposit
await synapse.payments.deposit({ amount });

Copy to clipboard

This requires two transactions and higher gas costs. Use depositWithPermit instead.

Account Summary

Get a comprehensive snapshot of your account’s payment state in a single call. This is the recommended way to check account health: it returns derived values like debt, lockup breakdown, and runway.

const summary = await synapse.payments.accountSummary();

console.log("Funds:", formatUnits(summary.funds));
console.log("Available:", formatUnits(summary.availableFunds));
console.log("Debt:", formatUnits(summary.debt));
console.log("Rate per epoch:", summary.lockupRatePerEpoch);
console.log("Rate per month:", formatUnits(summary.lockupRatePerMonth));
console.log("Total lockup:", formatUnits(summary.totalLockup));
console.log("  Fixed lockup:", formatUnits(summary.totalFixedLockup));
console.log("  Rate-based lockup:", formatUnits(summary.totalRateBasedLockup));
console.log("Runway (epochs):", summary.runwayInEpochs);
console.log("Gross coverage (epochs):", summary.grossCoverageInEpochs);

Copy to clipboard

Two runway numbers, differing by the lockup reserve:

• runwayInEpochs: runway excluding the lockup reserve. How long until your account enters deficit and the standard payment flow halts. Use for “when must I act?”.
• grossCoverageInEpochs: runway including the lockup reserve (funds / lockupRate). The full horizon your deposit covers at the current rate. Use for “how much have I prepaid in total?”.

The lockup reserve (totalLockup) is the portion of funds each rail has set aside under its terms. The funds are locked at the contract level while the rail is active, they can’t be withdrawn. Active payments draw from the unreserved portion of funds; the reserve sits as a floor. Once you enter deficit, standard settlement halts. A provider can then terminate the rail to claim against the reserve for up to one lockup period. Termination is one-way: once a rail has an endEpoch it’s heading to finalization and topping up your account won’t revive it. Top up before deficit to keep existing rails open.

Account Health Monitoring

Important: Monitor your account health regularly. Insufficient balance causes payment failures and service interruptions.

import { epochsToDays } from "@filoz/synapse-core/utils";

const summary = await synapse.payments.accountSummary();

const runwayDays = epochsToDays(summary.runwayInEpochs);
const totalDays = epochsToDays(summary.grossCoverageInEpochs);

console.log(`Runway: ${runwayDays} days`);
console.log(`Gross coverage: ${totalDays} days`);

if (runwayDays === 0n && summary.funds > 0n) {
  console.warn("Account in deficit: standard settlement to providers has halted. Deposit to resume.");
} else if (runwayDays < 7n) {
  console.warn("Low runway, top up soon to avoid service interruption.");
}

Copy to clipboard

epochsToDays floors to whole days and passes maxUint256 through unchanged (use that as the “infinite” sentinel when the account has no spend rate).

Withdrawing Unlocked Funds

const info = await synapse.payments.accountInfo();
await synapse.payments.withdraw({ amount: info.availableFunds });

Copy to clipboard

Approving Operators

Operators are smart contracts authorized to spend your tokens for specific services. Before uploading files, you must approve the WarmStorage operator. This approval is required only once per operator and grants permission to create payment rails on your behalf.

Three types of allowances protect your funds from unauthorized spending:

1. Rate Allowance - Max spending per epoch across all rails
2. Lockup Allowance - Max total funds locked across all rails
3. Max Lockup Period - Max duration funds can be locked (the safety net)

Approving an Operator

Approving warmStorage for 1TiB of storage for 3 months.

import { TIME_CONSTANTS } from "@filoz/synapse-sdk";

const months = 3n;

const rateAllowance = monthlyPricePerTiB / TIME_CONSTANTS.EPOCHS_PER_MONTH;
const lockupAllowance = monthlyPricePerTiB * months;
const maxLockupPeriod = TIME_CONSTANTS.EPOCHS_PER_MONTH;

await synapse.payments.approveService();

Copy to clipboard

Revoking an Operator

Revoking warmStorage’s operator approvals.

await synapse.payments.revokeService();

Copy to clipboard

Checking Operator Approvals

const approval = await synapse.payments.serviceApproval();

console.log("Approved:", approval.isApproved);
console.log(
  "Rate allowance:",
  approval.rateAllowance,
  "used:",
  approval.rateUsage
);
console.log(
  "Lockup allowance:",
  approval.lockupAllowance,
  "used:",
  approval.lockupUsage
);
console.log("Max lockup period:", approval.maxLockupPeriod);

Copy to clipboard

Next Steps

• Understanding Rails & Settlement - Deep dive into payment mechanics
• Storage Costs & Budgeting - Plan your storage budget
• Ready to upload files? You now have the basics. Start uploading →