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.

// @lib: esnext,dom
import { Synapse } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
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");

Fund Your Account

// @lib: esnext,dom
import { Synapse, parseUnits } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
import { TOKENS } from "@filoz/synapse-sdk";

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

Alternative: Two-Transaction Deposit (not recommended)

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

// @lib: esnext,dom
import { Synapse, parseUnits } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
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 });

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 funded-until epoch.

// @lib: esnext,dom
import { Synapse, formatUnits } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
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("Funded until epoch:", summary.fundedUntilEpoch);

Account Health Monitoring

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

// @lib: esnext,dom
import { Synapse } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
import { TIME_CONSTANTS } from "@filoz/synapse-sdk";

const summary = await synapse.payments.accountSummary();
const epochsRemaining = summary.availableFunds / summary.lockupRatePerEpoch;
const daysRemaining =
  Number(epochsRemaining) / Number(TIME_CONSTANTS.EPOCHS_PER_DAY);

console.log(`Days remaining: ${daysRemaining.toFixed(1)}`);
if (daysRemaining < 7) console.warn("Low balance!");

Withdrawing Unlocked Funds

// @lib: esnext,dom
import { Synapse } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'

const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
const info = await synapse.payments.accountInfo();
await synapse.payments.withdraw({ amount: info.availableFunds });

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.

// @lib: esnext,dom
import { Synapse, calibration } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'

const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
const monthlyPricePerTiB = null as unknown as bigint;
// ---cut---
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();

Revoking an Operator

Revoking warmStorage’s operator approvals.

// @lib: esnext,dom
import { Synapse, calibration } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
await synapse.payments.revokeService();

Checking Operator Approvals

// @lib: esnext,dom
import { Synapse, calibration } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' });
// ---cut---
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);

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 →