Filecoin RPC: A Developer's Guide to the FEVM (Chain ID 314)

Filecoin is a storage network first. Its Ethereum-compatible layer, the Filecoin EVM (FEVM), arrived in 2023 and lets Solidity contracts, MetaMask and viem talk to the chain through the standard eth_ methods. The translation is good enough that most read code works unchanged. It is also thin enough that Filecoin's own design shows through: blocks come in tipsets, some block numbers have no block at all, and most of the transactions you see were never Ethereum transactions.

This guide is measured against the live chain on October 14, 2026, through the same endpoint SwiftNodes customers use.

The endpoint

https://rpc.swiftnodes.io/rpc/filecoin?key=YOUR_API_KEY
wss://rpc.swiftnodes.io/ws/filecoin?key=YOUR_API_KEY

viem ships a filecoin chain definition, so the client is short:

import { createPublicClient, http } from "viem";
import { filecoin } from "viem/chains";

const client = createPublicClient({
  chain: filecoin,
  transport: http("https://rpc.swiftnodes.io/rpc/filecoin?key=YOUR_API_KEY"),
});

What we measured

Epochs, tipsets and null rounds

Filecoin does not have one block producer per slot. Every 30 seconds, storage providers run a lottery weighted by the storage they contribute, and each winner produces a block. The blocks of one epoch form a tipset. The network expects five winners per epoch; we counted 4.8 on average, and as many as eight.

The Ethereum API presents each tipset as one block. That has two visible effects:

• miner is the zero address on every block, because there is no single producer to report. Filecoin.ChainHead returns the tipset's block CIDs if you need them.
• hash is derived from the tipset key, not from a block header that any producer signed.

Sometimes no provider wins the lottery. That epoch is a null round: the block number exists in the sequence, but there is no tipset. On Ethereum, a request for a missing block returns null. On Filecoin it returns an error:

{"code": 12, "message": "requested epoch was a null round (6454669)", "data": 6454669}

We saw three null rounds in 401 consecutive epochs. A backfill loop that throws on the first error, or treats every error as a node problem and retries forever, will stop on one of them. Handle code 12 as a skip:

async function blockOrNull(n: bigint) {
  try {
    return await client.getBlock({ blockNumber: n });
  } catch (e: any) {
    const code = e?.cause?.code ?? e?.code;
    if (code === 12) return null; // null round: no tipset at this epoch
    throw e;
  }
}

parentHash of the next tipset points across the gap to the last real one, so a chain-linkage check still works if it compares against the previous non-null epoch.

Two kinds of addresses

FEVM accounts have f410 addresses, which map one-to-one onto ordinary 0x addresses. Native Filecoin accounts (f1 and f3 keys, and actors such as storage-provider miner actors) have numeric IDs like f03665364. The Ethereum API shows those as masked ID addresses: 0xff followed by zeros and the ID in hex, such as 0xff0000000000000000000000000000000037edd4.

In 60 epochs we read 1,096 transactions. 831 of them (76%) came from masked ID senders. They are native Filecoin messages, mostly storage providers proving and committing storage, presented through the Ethereum API as type 0x2 transactions. Their input starts with 0x868e10c4, the selector Filecoin uses to wrap a native method call as calldata. The method number, the codec (0x51, CBOR) and the CBOR parameters follow it. An indexer that decodes every transaction as Solidity calldata should skip that selector.

Two practical consequences:

1. eth_estimateGas rejects a masked ID address as from with expected a class 4 address, got: 0. Estimate from an f410 (0x) address, or leave from out.
2. To convert between formats, the native API is available on the same URL. Filecoin.EthAddressToFilecoinAddress turned 0x8d6d…e3bc into f410frvwxnzdmkx5yzvewv24ezgkfmps57y54vxssbuy and a masked ID into f03665364.

Gas is counted differently

Filecoin gas units measure real work done by the Filecoin virtual machine, including storage and signature costs, so the numbers look nothing like Ethereum's:

• A transfer of 1 attoFIL to an address that has never been seen estimated 6,147,692 gas. Creating the receiving account is part of the cost.
• The same transfer to an existing account estimated 1,675,770 gas.
• A WFIL balanceOf call estimated 4,376,778 gas.

The price per unit is small to match. The base fee sat at the 100 attoFIL floor in most of the last 20 epochs, and eth_gasPrice returned about 200,000 attoFIL, almost all of it priority fee. At that price the transfer to a new address costs about 0.0000012 FIL, a fraction of a cent at $1.18 per FIL.

Two rules to keep in mind when you set limits:

• Do not hard-code 21,000. A transfer with that limit runs out of gas. Always estimate.
• Do not overestimate by a lot. Filecoin burns part of the unused gas when the limit is more than 10% above what the message used. The burn is charged at the base fee, so it is cheap today, but it grows with network load. A limit of estimate × 1.1 or a little more is enough. In our sample, one FEVM transaction set a 200,000,000 limit and used 93,731,940.

Receipts have one oddity: cumulativeGasUsed is 0x0 on every receipt we read. Use gasUsed per receipt instead.

Finality: F3

Filecoin's original finality rule was 900 epochs, about 7.5 hours. Fast Finality (F3) adds a round of voting by storage providers that finalizes tipsets within minutes. With F3 active, the safe and finalized tags returned the same block, 20 epochs (600 seconds) behind the head, in every sample.

const finalized = await client.getBlock({ blockTag: "finalized" });

For deposits, wait for finalized rather than counting confirmations yourself. Ten minutes is slower than chains with instant finality but much faster than most rollups. See our survey of finalized lag across 62 chains for comparison. The latest F3 certificate is also available through Filecoin.F3GetLatestCertificate.

Logs

eth_getLogs accepts at most 360 epochs per request. That is three hours of chain time, and it applies even when you filter by contract address:

block range exceeds maximum of 360 (got 361)

Activity is dense enough that a 100-epoch unfiltered range returned 1,920 logs. Page in steps of 360 epochs or fewer:

for (let from = start; from <= end; from += 360n) {
  const to = from + 359n > end ? end : from + 359n;
  const logs = await client.getLogs({ address: WFIL, fromBlock: from, toBlock: to });
  // ...
}

A null round inside the range is fine; eth_getLogs skips it. See our eth_getLogs range cap survey for how this compares with other chains.

History and tracing

Nobody serves public Filecoin archive state back to the FEVM launch (epoch 2,683,348, March 2023), and the depth varies a lot between nodes. On October 14, 2026 we probed each public endpoint by reading a balance at older and older heights:

Our default route covers about the last 14 days. Add &archive=1 and the request goes to the deep-history node, where balances, eth_call and eth_getLogs worked 1,700,000 epochs back. Older than that, state fails with failed to compute tipset state. Archive routing is on paid plans.

https://rpc.swiftnodes.io/rpc/filecoin?key=YOUR_API_KEY&archive=1

Tracing works on the default route. debug_traceTransaction with the callTracer, trace_block and trace_replayBlockTransactions all returned call trees, and eth_getBlockReceipts returns a whole tipset's receipts in one call.

WebSocket

eth_subscribe with newHeads works on the WebSocket URL, with one header every 30 seconds. Do not treat a gap as a dead connection until well past a minute: a null round means 60 seconds between headers, and two in a row mean 90.

Summary

• Read code works with viem's filecoin chain; FIL has 18 decimals on this API.
• Handle error code 12 as an empty epoch, not as a failure.
• Expect masked ID senders and wrapped native calls in transaction lists.
• Estimate gas every time, and do not inflate the limit much.
• Wait for finalized: about 10 minutes with F3.
• Page logs in 360-epoch steps.

Filecoin endpoints and status are on our Filecoin RPC page, alongside the rest of the 128 chains on one key. SwiftNodes has a free tier to try it.