> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neynar.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Buy storage
> This api will help you rent units of storage for an year for a specific FID.
A storage unit lets you store 5000 casts, 2500 reactions and 2500 links. Requires x-wallet-id header.
## Node.js SDK
🔗 **SDK Method:** [buyStorage](/nodejs-sdk/storage-apis/buyStorage)
Use this API endpoint with the Neynar Node.js SDK for typed responses and better developer experience.
***
### Related documentation:
* [Managing Onchain Wallets](/docs/managing-onchain-wallets) - Wallet setup guide
* [Storage documentation](/docs/getting-storage-units-allocation-of-farcaster-user) - Understanding storage
## 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](/docs/managing-onchain-wallets) 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](/docs/managing-onchain-wallets) to create your app wallet in the developer portal and obtain your `x-wallet-id` value.
## Code Examples
```javascript Node.js theme={"system"}
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);
```
```bash cURL theme={"system"}
curl -X POST 'https://api.neynar.com/v2/farcaster/storage/buy' \
-H 'x-api-key: YOUR_NEYNAR_API_KEY' \
-H 'x-wallet-id: your-wallet-id' \
-H 'Content-Type: application/json' \
-d '{
"fid": 12345,
"units": 1
}'
```
```python Python theme={"system"}
import requests
headers = {
'x-api-key': 'YOUR_NEYNAR_API_KEY',
'x-wallet-id': 'your-wallet-id', # REQUIRED
'Content-Type': 'application/json'
}
response = requests.post(
'https://api.neynar.com/v2/farcaster/storage/buy',
headers=headers,
json={
'fid': 12345,
'units': 1
}
)
data = response.json()
print('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:
| Resource | Capacity per Unit |
| ------------- | --------------------------- |
| **Casts** | 5,000 casts |
| **Reactions** | 2,500 reactions |
| **Links** | 2,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
```json theme={"system"}
{
"code": "RequiredField",
"message": "x-wallet-id header is required"
}
```
**Solution:** Add the `x-wallet-id` header. See [Managing Onchain Wallets](/docs/managing-onchain-wallets) for setup instructions.
### Error: Invalid Wallet ID
```json theme={"system"}
{
"code": "InvalidWalletId",
"message": "The provided wallet_id is invalid or not found."
}
```
**Solution:** Verify your wallet\_id in the [Developer Portal](https://dev.neynar.com) or contact support.
### Error: Insufficient Wallet Balance
```json theme={"system"}
{
"code": "InsufficientFunds",
"message": "Wallet does not have enough balance to complete this transaction."
}
```
**Solution:** Fund your wallet with more ETH on Optimism.
## Next Steps
View storage allocations for a user
Track storage consumption
Fund your wallet and monitor balance
Need help? Reach out to our team
## OpenAPI
````yaml post /v2/farcaster/storage/buy/
openapi: 3.0.4
info:
contact:
email: team@neynar.com
name: Neynar
url: https://neynar.com/
description: >-
The Neynar API allows you to interact with the Farcaster protocol among
other things. See the [Neynar docs](https://docs.neynar.com/reference) for
more details.
title: Neynar API
version: 3.174.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- description: Operations related to user
externalDocs:
description: More info about user
url: https://docs.neynar.com/reference/user-operations
name: User
- description: Operations related to signer
externalDocs:
description: More info about signer
url: https://docs.neynar.com/reference/signer-operations
name: Signer
- description: Operations related to cast
externalDocs:
description: More info about cast
url: https://docs.neynar.com/reference/cast-operations
name: Cast
- description: Operations related to feed
externalDocs:
description: More info about feed
url: https://docs.neynar.com/reference/feed-operations
name: Feed
- description: Operations related to reaction
externalDocs:
description: More info about reaction
url: https://docs.neynar.com/reference/reaction-operations
name: Reaction
- description: Operations related to notifications
externalDocs:
description: More info about notifications
url: https://docs.neynar.com/reference/notifications-operations
name: Notifications
- description: Operations related to channels
externalDocs:
description: More info about channels
url: https://docs.neynar.com/reference/channel-operations
name: Channel
- description: Operations related to follows
externalDocs:
description: More info about follows
url: https://docs.neynar.com/reference/follows-operations
name: Follows
- description: Operations related to storage
externalDocs:
description: More info about storage
url: https://docs.neynar.com/reference/storage-operations
name: Storage
- description: Operations related to mini apps
name: Frame
- description: Operations for building AI agents
name: Agents
- description: Operations related to fname
name: fname
- description: Operations related to a webhook
name: Webhook
- description: >-
Securely communicate and perform actions on behalf of users across
different apps
externalDocs:
description: More info about farcaster actions
url: https://docs.neynar.com/docs/farcaster-actions-spec
name: Action
- description: Operations related to a subscriptions
name: Subscribers
- description: Operations related to a mute
name: Mute
- description: Operations related to a block
name: Block
- description: Operations related to a ban
name: Ban
- description: Operations related to onchain data
name: Onchain
- description: Operations related to login
name: Login
- description: Operations related to retrieving metrics
name: Metrics
- description: Operations related to mini app host notifications
externalDocs:
description: More info about mini app host notifications
url: https://docs.neynar.com/docs/app-host-notifications
name: App Host
paths:
/v2/farcaster/storage/buy/:
post:
tags:
- Storage
summary: Buy storage
description: >-
This api will help you rent units of storage for an year for a specific
FID.
A storage unit lets you store 5000 casts, 2500 reactions and 2500 links.
Requires x-wallet-id header.
operationId: buy-storage
parameters:
- $ref: '#/components/parameters/WalletIdHeader'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BuyStorageReqBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StorageAllocationsResponse'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ZodError'
description: Bad Request
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ConflictErrorRes'
description: Conflict
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorRes'
description: Server Error
externalDocs:
url: https://docs.neynar.com/reference/buy-storage
components:
parameters:
WalletIdHeader:
description: Wallet ID to use for transactions
in: header
name: x-wallet-id
required: true
schema:
type: string
x-is-global-header: true
schemas:
BuyStorageReqBody:
properties:
fid:
description: The unique identifier of a farcaster user or app (unsigned integer)
example: 1
format: int32
minimum: 1
type: integer
idem:
$ref: '#/components/schemas/Idem'
units:
description: >-
Number of storage units to buy.
A storage unit lets you store 5000 casts, 2500 reactions and 2500
links.
example: 1
minimum: 1
type: integer
required:
- fid
title: BuyStorageReqBody
type: object
StorageAllocationsResponse:
properties:
allocations:
items:
$ref: '#/components/schemas/StorageAllocation'
type: array
total_active_units:
example: 13
type: integer
title: StorageAllocationsResponse
type: object
ZodError:
properties:
code:
example: InvalidField
type: string
errors:
items:
properties:
code:
type: string
expected:
type: string
message:
type: string
path:
items:
type: string
type: array
received:
type: string
required:
- code
- expected
- received
- path
- message
type: object
type: array
message:
example: Invalid query parameters
type: string
required:
- message
- code
- errors
title: ZodError
type: object
ConflictErrorRes:
description: Details for the conflict error response
properties:
code:
type: string
key:
type: string
message:
type: string
property:
type: string
required:
- message
title: ConflictErrorRes
type: object
ErrorRes:
description: Details for the error response
properties:
code:
type: string
message:
type: string
property:
type: string
status:
format: int32
type: integer
required:
- message
title: ErrorRes
type: object
Idem:
description: >-
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.
title: Idem
type: string
StorageAllocation:
properties:
expiry:
example: '2024-10-08T22:03:49.000Z'
format: date-time
type: string
object:
example: storage_allocation
type: string
timestamp:
example: '2023-10-09T22:03:49.000Z'
format: date-time
type: string
units:
example: 10
type: integer
user:
$ref: '#/components/schemas/UserDehydrated'
title: StorageAllocation
type: object
UserDehydrated:
properties:
custody_address:
$ref: '#/components/schemas/EthAddress'
display_name:
nullable: true
type: string
fid:
$ref: '#/components/schemas/Fid'
object:
enum:
- user_dehydrated
type: string
pfp_url:
nullable: true
type: string
score:
type: number
username:
type: string
required:
- object
- fid
title: UserDehydrated
type: object
EthAddress:
description: Ethereum address
example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
pattern: ^0x[a-fA-F0-9]{40}$
title: EthAddress
type: string
Fid:
description: The unique identifier of a farcaster user or app (unsigned integer)
example: 3
format: int32
minimum: 0
title: Fid
type: integer
securitySchemes:
ApiKeyAuth:
description: API key to authorize requests
in: header
name: x-api-key
type: apiKey
x-default: NEYNAR_API_DOCS
````