Overview
@toju.network/x402 implements the x402 protocol for autonomous storage payments. An agent instantiates AgentClient with a funded Base wallet, calls store(), and the SDK handles the full payment negotiation automatically — no wallet prompts, no manual signing steps.
The flow under the hood:
1
Send request
Agent sends
POST /upload/agent with the file and storage parameters2
Receive 402
Server responds with
402 Payment Required and a price quote in USDC3
Sign off-chain
SDK signs an EIP-3009 authorization (no on-chain transaction yet)
4
Retry with payment
SDK retries the request with the signed
X-PAYMENT header attached5
Facilitator settles
Coinbase’s public facilitator verifies and settles the USDC transfer on Base
6
File stored
Server pins to IPFS and returns the CID
Install
Quick start
createAgentClient
Options
EVM private key for the agent’s wallet. Must hold USDC on Base to pay for storage.
estimateStorageCost
Check the cost before uploading.Parameters
Response
store
Upload a file and pay autonomously via x402.Parameters
The file to upload. Use the standard Web API
File object — works in Node.js 20+ and all modern runtimes.Response
USDC on Base
USDC uses 6 decimal places on all EVM chains (Circle standard). The SDK and server handle conversion automatically.Your agent wallet needs enough USDC to cover the storage cost, plus a small amount of ETH on Base for gas. Gas fees on Base are typically under $0.001 per transaction.
AI Agent Integrations
@toju.network/x402 works with any AI agent framework that can hold an EVM private key and execute TypeScript. The SDK handles all payment logic — you just need to wrap it as a tool or action.
LangChain
This example shows how to integrate@toju.network/x402 with LangChain. See the complete working example in the x402-langchain repo.
- Agent receives natural language request
- LLM decides to use the
store_file_ipfstool - Tool reads file from disk and pays via x402
- File uploaded to IPFS, CID returned
Langchain demo
Autonomous AI Agent Storing Files on IPFSRelated
Pricing
Storage rate and cost calculator
Upload (SOL)
Human wallet uploads with Solana
CID Computation
How content identifiers work
Storage Payments
Payment mechanics