# Payment Operations

The Synapse SDK uses [**USDFC**](https://app.usdfc.net/) (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](/developer-guides/payments/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.

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

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

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

<details>
<summary>*Alternative: Two-Transaction Deposit (not recommended)*</summary>

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

```ts
// 1. Approve USDFC spending
await usdfc.approve(paymentAddress, depositAmount);

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

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

</details>

### Account Health Monitoring

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

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

const info = await synapse.payments.accountInfo();
const epochsRemaining = info.availableFunds / info.lockupRate;
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

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

const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
// ---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.

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

const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
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.

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

### Checking Operator Approvals

```ts twoslash
// @lib: esnext,dom
import { Synapse, calibration } from "@filoz/synapse-sdk";
import { privateKeyToAccount } from 'viem/accounts'
const synapse = Synapse.create({ account: privateKeyToAccount('0x...') });
// ---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](/developer-guides/payments/rails-settlement/) - Deep dive into payment mechanics
- [Storage Costs & Budgeting](/developer-guides/storage/storage-costs/) - Plan your storage budget
- **Ready to upload files?** You now have the basics. [Start uploading →](/developer-guides/storage/storage-operations/)