Neynar Documentation

In the Farcaster protocol, a storage unit is a measure used to allocate and track the amount of data that a user (identified by their Farcaster ID or fid) can store within the network. This system is critical for managing the storage resources of the Farcaster network effectively and ensuring that the network remains scalable and efficient. The specific allocation of storage per unit varies depending on the type of data being stored. Here’s the list of storage allocations per unit:

100 cast messages
200 reaction messages
200 link messages
25 user_data messages
5 verifications messages
2 username_proof messages

The Storage Registry contract controls and tracks the allocation. This contract records the storage allocated to each fid, denominated in integer units. If a user exceeds their storage allocation, Farcaster Hub prunes their old messages. Users can buy more storage units by sending a transaction to the Storage Registry contract or using an app like caststorage.com. This guide demonstrates how to use the Neynar SDK to retrieve a Farcaster user’s storage usage and allocation. Check out this Getting Started guide to learn how to set up your environment and get an API key. First, initialize the client:

// npm i @neynar/nodejs-sdk
import { NeynarAPIClient, Configuration } from "@neynar/nodejs-sdk";

// make sure to set your NEYNAR_API_KEY .env
// don't have an API key yet? get one at neynar.com
const config = new Configuration({
  apiKey: process.env.NEYNAR_API_KEY,
});

const client = new NeynarAPIClient(config);

Then, fetch the storage usage and allocation:

const rishFID = 194;
const storageUsage = await client.lookupUserStorageUsage({fid:rishFID});

console.log(storageUsage);

Example output:

{
  object: "storage_usage",
  user: {
    object: "user_dehydrated",
    fid: 194
  },
  total_active_units: 2,
  casts: {
    object: "storage",
    used: 3707,
    capacity: 10000
  },
  reactions: {
    object: "storage",
    used: 4984,
    capacity: 5000
  },
  links: {
    object: "storage",
    used: 472,
    capacity: 5000
  },
  verifications: {
    used: 2,
    capacity: 25
  },
  username_proofs: {
    used: 1,
    capacity: 5
  },
  signers: {
    used: 17,
    capacity: 1000
  }
}

To fetch the storage allocation of a user, use the lookupUserStorageAllocation function:

const storageAllocation = await client.lookupUserStorageAllocations({fid:rishFID});
console.log(storageAllocation);

Example output:

{
  total_active_units: 2,
  allocations: [
    {
      object: "storage_allocation",
      user: [Object ...],
      units: 2,
      expiry: "2024-08-28T22:23:31.000Z",
      timestamp: "2023-08-29T22:23:31.000Z"
    }
  ]
}

That’s it! You can now look at the storage usage and allocation of any Farcaster user.

Ready to start building?

Get your subscription at neynar.com and reach out to us on Slack with any questions!

Get Started

Build Bots and Agents

Build Farcaster Mini Apps

Fetch User Information

Fetch Cast Information

Fetch Farcaster Feeds

Onboard New Users

Write Data to Farcaster

Filter Spam, Low Quality Data

Host Farcaster Mini Apps

Run Queries on FC Data

Render Farcaster in React

Get Events Via Webhooks

Fetch Notifications

Create Onchain Transactions

Intersect Onchain & Social Data

Write Direct Casts

Get Farcaster Storage Data

Publish Actions on FC Apps

Get Farcaster Data on Base

Explore Network Health

Get Hypersub Subscriptions

Contribute To Development

Storage Units Allocation

Ready to start building?

​Related API: Allocation of user

​Ready to start building?

Related API: Allocation of user

Ready to start building?