Meta

Status

• 2025-08-29: Updated to summarize the difference between /v1 and /v2. This was reviewed in PR #13284.
• 2025-06-06: Updated to make clear the impact on the APIs if F3 isn't finalizing or if the latest F3-finalized tipset is older than the latest EC-finalized tipset. This was reviewed in PR #13161.
• 2025-05-01: Updated to make clear the impact on the APIs if F3 isn't finalizing. This was reviewed in PR #13068.
• 2025-04-24: This document has been updated to include information about Eth APIs in /v2. This was reviewed in PR #13068.
• 2025-04-23: This document has been updated to account for the minimum initial set of non-Eth /v2 API groups as specified in issue #12991. This was reviewed in PR #13051
• 2025-04-09: This document is still actively a Work In Progress. It has a draft discussing ChainGetTipSet. Additional APIs and API Groups will be added as part of working on issue #12987.

Table of Contents

Introduction

The Filecoin V2 APIs represent a significant redesign of Filecoin's RPC interface for non-ETH APIs with several important goals in mind:

1. User-Friendly Interface: The APIs provide intuitive ways to interact with the Filecoin network without requiring deep technical knowledge of its internals.
2. Expressive Selection Mechanisms: Through the Selector pattern, users can clearly express what data they want using criteria that make sense for their use case.
3. Smaller API Footprint: By using flexible selectors, we've reduced the number of distinct API methods needed, consolidating functionality into fewer, more powerful endpoints.
4. F3 Awareness: The APIs are fully aware of Filecoin Fast Finality (F3) and can automatically adapt to provide the appropriate finality guarantees based on the node's consensus protocol.
5. Future Extensibility: The design allows for extending selection criteria without breaking existing functionality or requiring new API methods.

ETH APIs have also been updated with F3 awareness for the finalized and safe tags (see Ethereum (Eth)).