Hot decentralized storage on top of IPFS + Filecoin, now operated by Storacha. Uses UCAN-based capability auth and 'Spaces' (DID-scoped buckets) via the `@web3-storage/w3up-client` SDK; uploads are content-addressed (CIDs) and persisted to Filecoin in the background.
- 01NFT metadata and media pinning with Filecoin backup
- 02fast hot reads via IPFS gateways
- 03user-owned data via UCAN delegations
- 04client-side uploads with delegated capabilities
- 05free-tier-friendly Web3 file hosting
- pnpm add @web3-storage/w3up-client
| Variable | Scope | Description |
|---|---|---|
| W3_AGENT_KEY | Server | Base64-encoded ed25519 private key for the agent DID (generate via `w3 key create --json`). Server-side only. |
| W3_PROOF | Server | Base64 UCAN delegation that grants this agent access to your Space (`w3 delegation create <agent-did> --base64`). Server-side only. |
| W3_SPACE_DID | Server | DID of the target Space (e.g. `did:key:z6...`). |
Use `@web3-storage/w3up-client`. On the server, build a client from your stored agent key and delegation: `const principal = Signer.parse(process.env.W3_AGENT_KEY); const store = new StoreMemory(); const client = await create({ principal, store }); const proof = await Proof.parse(process.env.W3_PROOF); const space = await client.addSpace(proof); await client.setCurrentSpace(space.did());`. Upload a single file with `const cid = await client.uploadFile(file)` (Blob/File) or many with `client.uploadDirectory([files])`. Read via any IPFS gateway (`https://w3s.link/ipfs/${cid}` or `https://${cid}.ipfs.w3s.link`). For browser uploads, delegate a short-lived UCAN to the user's agent via `client.createDelegation(audience, ['space/blob/add', 'upload/add'], { expiration })` — never ship the root agent key.
- ⚑Web3.Storage rebranded to Storacha and the API moved from the old `web3.storage` REST API + API tokens to the UCAN-based `w3up` model — old tutorials with `Web3Storage({ token })` are deprecated and the legacy endpoint is read-only.
- ⚑Auth is capability-based via UCAN delegations, not API keys. You generate an agent DID, register a Space, and delegate scoped capabilities — losing the agent key + delegation means you can't write to the Space.
- ⚑Pinning a CID does not make it private — anyone with the CID can read it from any IPFS gateway. Encrypt before upload if confidentiality matters.
- ⚑Filecoin deal-making happens asynchronously after upload — your CID is hot on IPFS immediately but provable Filecoin persistence appears minutes-to-hours later. Don't promise SLAs based solely on the upload receipt.
- ⚑Free-tier limits and rate limits apply per Space — viral NFT mints can hit them fast. Monitor usage via the Storacha dashboard.
- ⚑Gateway centralization risk — `w3s.link` is convenient but a single gateway. Fall back across multiple IPFS gateways for production reads.