Skip to main content
POST
/
v2
/
farcaster
/
storage
/
buy
Buy storage
curl --request POST \
  --url https://api.neynar.com/v2/farcaster/storage/buy/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-wallet-id: <x-wallet-id>' \
  --data '
{
  "fid": 1,
  "units": 1,
  "idem": "<string>"
}
'
{
  "total_active_units": 13,
  "allocations": [
    {
      "object": "storage_allocation",
      "user": {
        "object": "user_dehydrated",
        "fid": 3,
        "username": "<string>",
        "display_name": "<string>",
        "pfp_url": "<string>",
        "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "score": 123
      },
      "units": 10,
      "expiry": "2024-10-08T22:03:49.000Z",
      "timestamp": "2023-10-09T22:03:49.000Z"
    }
  ]
}

​
Node.js SDK

🔗 SDK Method: buyStorage Use this API endpoint with the Neynar Node.js SDK for typed responses and better developer experience.

​
Understanding Wallet ID for Storage Purchases

This endpoint allows you to purchase storage units for a specific FID (Farcaster ID). Storage units enable users to store more casts, reactions, and links on the Farcaster protocol.

​
Wallet ID (REQUIRED)

The x-wallet-id header is required for this endpoint. You must provide a wallet_id to pay for the onchain storage purchase transaction.
New to Wallet IDs? See Managing Onchain Wallets to create your app wallet in the developer portal and obtain your x-wallet-id value.

​
Code Examples

const response = await fetch('https://api.neynar.com/v2/farcaster/storage/buy', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',  // REQUIRED
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fid: 12345,
    units: 1
  })
});

const data = await response.json();
console.log('Storage purchased:', data);

​
What You’re Paying For

When you buy storage with a wallet_id:
  • Transaction Execution: Neynar handles gas estimation, retries, and monitoring

​
Storage Units Explained

Each storage unit you purchase provides:
ResourceCapacity per Unit
Casts5,000 casts
Reactions2,500 reactions
Links2,500 links (follows, etc.)
  • Duration: 1 year from purchase
  • Network: Optimism mainnet
  • Renewal: Must be renewed annually
Planning storage needs? Most active users need 1-2 units per year. Power users (>50 casts/day) may need 3-5 units.

​
Error Handling

​
Error: Missing Wallet ID

{
  "code": "RequiredField",
  "message": "x-wallet-id header is required"
}
Solution: Add the x-wallet-id header. See Managing Onchain Wallets for setup instructions.

​
Error: Invalid Wallet ID

{
  "code": "InvalidWalletId",
  "message": "The provided wallet_id is invalid or not found."
}
Solution: Verify your wallet_id in the Developer Portal or contact support.

​
Error: Insufficient Wallet Balance

{
  "code": "InsufficientFunds",
  "message": "Wallet does not have enough balance to complete this transaction."
}
Solution: Fund your wallet with more ETH on Optimism.

​
Next Steps

Check Current Storage

View storage allocations for a user

Monitor Usage

Track storage consumption

Manage Your Wallet

Fund your wallet and monitor balance

Contact Support

Need help? Reach out to our team

Authorizations

​
x-api-key
string
header
default:NEYNAR_API_DOCS
required

API key to authorize requests

Headers

​
x-wallet-id
string
required

Wallet ID to use for transactions

Body

application/json
​
fid
integer
required
Required range: x >= 1
Example:

1

​
units
integer

Number of storage units to buy. A storage unit lets you store 100 casts, 200 reactions and 200 links.

Required range: x >= 1
Example:

1

​
idem
string

An Idempotency key is a unique identifier for the request. Note:

  1. This is used to prevent duplicate requests. Use the same idem key on retry attempts.
  2. This should be a unique identifier for each request.
  3. Recommended format is a 16-character string generated by the developer at the time of making this request.

Response

Success

​
total_active_units
integer
Example:

13

​
allocations
StorageAllocation · object[]