Lighthouse x Base: Storage That Agents Can Pay For Themselves
Base solved how machines pay. Lighthouse solved where their data lives. x402 joins them.
For most of the last decade, teams solved storage and payment separately. You provisioned capacity ahead of time, put a credit card on file, and hoped your forecast was close. That model assumes a human is somewhere in the loop, watching a dashboard, approving an invoice.
Autonomous software breaks that assumption. An agent that needs to persist an artifact at 3am does not have a procurement process. It has a wallet.
This is why the Lighthouse and Base combination matters, beyond a simple chain integration. Base gives machines a settlement layer with stablecoins and sub-cent fees. Lighthouse gives them storage that is content addressed, encrypted before it leaves the client, and gated by conditions those same chains can evaluate. Together, an agent can buy storage, store data, prove what it stored, and control who reads it, without a human touching any step.
Here is how it works and what you can build with it.
x402: Pay Per Upload, in USDC, on Base
x402 takes the HTTP 402 Payment Required status code, which has been a placeholder in the spec since the 1990s, and makes it a real protocol step. Instead of returning 402 as a dead end, the server returns it as a quote.
The flow is four moves:
- Your client POSTs a file to the upload endpoint.
- The server responds
402with a price and apayToaddress. Pricing is dynamic, based on file size. - The client pays USDC on Base mainnet, automatically.
- The client retries with payment proof, and the server responds
200with the CID.
No API key. No pre-funded balance. No subscription. The client library handles the payment leg, so from your code it reads like an ordinary fetch that happens to cost money.
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { statSync, openAsBlob } from "fs";
const SERVER_URL = process.env.SERVER_URL || "http://localhost:12000";
const signer = privateKeyToAccount(process.env.PRIVATE_KEY);
const client = new x402Client();
registerExactEvmScheme(client, { signer });
const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const filePath = "./myfile.pdf";
const fileBlob = await openAsBlob(filePath);
const response = await fetchWithPayment(`${SERVER_URL}/api/upload`, {
method: "POST",
headers: {
"Content-Type": "application/octet-stream",
"Content-Length": String(statSync(filePath).size),
"x-file-name": "myfile.pdf",
},
body: fileBlob,
});
const { cid, ipfsUrl } = await response.json();
That is the entire integration. openAsBlob streams from disk rather than buffering the file in memory, which matters when the thing calling this is a long-running process handling files it did not choose the size of.
Two things worth knowing that the code does not show.
You get a settlement receipt. The response carries a PAYMENT-RESPONSE header containing base64-encoded JSON with the transaction hash and the payer address. Decode it and you have an onchain reference on Base mainnet, chain ID 8453, verifiable on BaseScan by anyone. The upload produced two independently checkable facts: a CID that proves what was stored, and a transaction that proves what was paid. For agent workloads, that pairing is the audit trail.
Storage has a term, and renewal is also an x402 call. Files stored through the x402 path on IPFS and Filecoin carry a one-year storage period. Renewing is the same pattern against /api/renew with an x-file-id header, payment handled automatically. Retention is a deal term that Lighthouse manages, not a promise of forever, and the renewal endpoint is how you extend it. An agent can be given a budget and a renewal schedule and left alone.
x402 works on both storage paths. For IPFS and Filecoin, follow the pay-per-use upload tutorial. For Walrus-backed blob storage, the Walrus x402 guide points at a hosted endpoint at x402-walrus.lighthouse.storage, so you can pay in USDC on Base for storage that settles on Sui without touching Sui infrastructure. One wallet, one payment rail, two storage networks underneath.
Encryption and Access Control, Evaluated Against Base
Pay-per-use solves who pays. It does not solve who reads. That's the second half of the integration, and often the more important one for Base builders.
Public IPFS is not private. Anyone holding a CID can retrieve the bytes. Filecoin and Walrus store whatever they are given, plaintext included. "Decentralized" and "private" get used interchangeably across this category, including by vendors who know better. They are not the same property, and conflating them is how sensitive data ends up publicly addressable.
Lighthouse encrypts client-side through Kavach before anything leaves the browser or runtime. The encryption key is split with BLS threshold cryptography and distributed across independent key nodes, so no single node ever holds a complete key. Reconstruction requires a threshold of nodes to participate, and each node independently evaluates your access conditions before releasing its share.
The practical consequence: Lighthouse cannot read your files. Neither can storage node operators on IPFS, Filecoin, or Walrus. Compromising Lighthouse infrastructure does not expose file contents, because there is no plaintext and no complete key to take.
Because Base is an EVM chain, the full condition set applies to your Base contracts and tokens:
- ERC-20 balance thresholds. Hold 100 of a token to decrypt.
- ERC-721 and ERC-1155 ownership. Gate on holding a specific NFT or collection.
- Native balance conditions. Gate on ETH held on Base.
- Custom contract return values. Point at any contract on Base, call a method, compare the result with equality or greater-than or less-than. This is the general case: if your logic can be expressed in a Base contract, it can gate decryption.
- Block number and time windows. Release a document at a block height, or inside a date range.
- Passkeys and zkTLS proofs. Identity conditions that do not require a token at all.
You compose conditions with boolean aggregators. Require all of a set, or any one of them. Grant access directly to named addresses. Share a single file with multiple parties under independent conditions. Revoke access after granting it.
Here's the pattern for Base contracts, and teams still get it backwards: contracts cannot initiate uploads. Your application uploads through Lighthouse, receives a CID, and stores it in the contract. Onchain byte storage costs gas proportional to size, which makes storing file bytes onchain impractical. A CID is a compact, verifiable pointer to bytes that live where bytes should live, with encryption and access rules attached.
What Base Builders Can Actually Ship
Base's app surface maps cleanly onto the categories already building on Lighthouse. Working across our ecosystem, the same handful of shapes keep recurring.
Consumer social and creator apps. User-generated content at scale, served through gateways tuned for retrieval, including 4K video streaming and image resizing applied at retrieval time rather than by storing variants. Token-gated media where a Base contract decides who decrypts. Base offers a low-cost path to consumer scale in the EVM world, and consumer apps generate substantial storage per user.
Onchain media and NFTs. Metadata and media addressed by CID and referenced from your Base contracts. Unlockable content behind ownership conditions. Pay-to-view media where a payment contract gates decryption, which composes neatly with x402: the buyer pays onchain, the contract state changes, the key nodes see the new state and release shares.
Agent and AI applications. Covered in the next section, and a growing category across our platform.
DePIN and device networks. Sensor and telemetry data persisted with verifiable addressing, encrypted so the network operator cannot read payloads, with proof-of-contribution records where tamper evidence is the point.
RWAs, documents, and compliance. This is where per-recipient conditions earn their keep. A KYC packet can be shared with each reviewing party under independent conditions, and revoked when the relationship ends. An audit trail where the CID proves a filing was not altered after submission. Multi-party agreements where each counterparty decrypts only what their role permits.
Data availability and modular infrastructure. Content-addressed blobs with verifiable references, payload offchain, CID anchored onchain.
The Agentic Case, Stated Directly
The reason this integration exists is that autonomous systems have a data problem that nobody solved on their behalf.
An agent that cannot prove what it read cannot be audited. An agent that loses state cannot be trusted with any task longer than a session. An agent operating on data nobody can verify produces outputs nobody can defend. As models converge and get cheaper, differentiation moves down the stack, to what the agent remembers and whether that memory holds up under scrutiny.
Five layers, and Base supplies one of them:
- Persistence. Files and blobs on IPFS, Filecoin, or Walrus.
- Addressing. CIDs derived from content, so later alteration is detectable.
- Confidentiality. Kavach threshold encryption with per-party conditions.
- Memory. Semantic recall over stored context, exposed through MCP.
- Payment. x402 on Base for autonomous settlement.
Layer 5 is the one that removes the human. Everything else can be built with an API key that somebody has to fund. x402 on Base means the agent funds itself.
On layer 4, Memory gives agents remember, recall, and forget primitives, with every memory persisted as a verifiable blob addressed by an IPFS-compatible CID. Since memory lives on the network rather than inside one app or session, an agent resumes across sessions, machines, and runtimes. Rebuild the entire store on a fresh machine from nothing but an API key. Semantic recall runs locally with an in-process embedding model, so no embedding data leaves the machine and no second API key is required. A bundled MCP server exposes all of it as tools to Claude Code, Claude Desktop, and any MCP-capable runtime.
One honest caveat: Memory blobs are currently stored unencrypted. Anyone with the CID can read them. Do not put secrets in Memory yet. Encrypted memory follows our encrypted upload support. Everything in the encryption section above applies to file uploads today, not to Memory.
The patterns worth building on this stack: agent memory across sessions and machines; decision receipts, where a CID turns an action log into evidence rather than assertion; training and evaluation datasets shared under conditions and revocable later; multi-agent coordination over shared encrypted state with per-agent scoping; artifact persistence for workflows that must survive a process restart; and provenance trails for regulated environments, where the question is not only what the agent did but whether the record of it can be trusted.
The Rest of the Toolbox
A few things that come along with the integration and tend to surprise people:
An S3-compatible API. L3 speaks AWS Signature V4, so tools like the AWS CLI, boto3, rclone, and AWS SDKs work unchanged. Every object response includes its CID in the x-amz-meta-cid header, so you get content addressing without changing client code. If your Base app already has S3 integration, this is a config change, not a migration.
IPNS for mutable references. A stable name over changing content, so onchain references do not break when the content updates.
Migration with CID preservation. Move existing IPFS data to Walrus without changing CIDs. Your contracts keep pointing at the same identifiers.
Account delegation. One account authorizes another to act on its behalf, which is how you build team and service-account patterns, including giving an agent scoped authority over a parent account.
A free tier to start on. 5 GB on the Filecoin path, no card required. Enough to build the thing before deciding what it costs.
For scale context: 31K+ developers and teams, 9.3M+ file objects, and 15.6TB stored. The Lighthouse explorer is public, so those are verified figures.
Get Started
Pick the path for what you're building:
- x402 pay-per-use upload on IPFS and Filecoin
- x402 on the Walrus path
- Token gating with custom contracts
- Encryption features: share, revoke, condition
- Memory for agents, over MCP
- Create an API key and start on the free tier
Building something on Base that needs storage it can pay for itself? Talk to our team.
Stay in Touch
Learn more at the website, docs, or GitHub. Join the community on Discord, X, Telegram, and LinkedIn.
