Skip to main content

​
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 parameters
2

Receive 402

Server responds with 402 Payment Required and a price quote in USDC
3

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 attached
5

Facilitator settles

Coinbase’s public facilitator verifies and settles the USDC transfer on Base
6

File stored

Server uploads to IPFS via Storacha and returns the CID

​
Install

pnpm add @toju.network/x402

​
Quick start

import { createAgentClient } from '@toju.network/x402'

const client = createAgentClient({
  privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
  environment: 'mainnet',
})

const file = new File([fileBuffer], 'report.pdf', { type: 'application/pdf' })
const result = await client.store(file, { durationDays: 30 })

console.log(result.cid)       // bafy...
console.log(result.expiresAt) // 2025-06-01T00:00:00.000Z
Your agent’s wallet needs USDC on Base to pay. At our rate of 3×10⁻¹² USD/byte/day, storing 1 MB for 30 days costs about $0.0001.

​
createAgentClient

import { createAgentClient } from '@toju.network/x402'

const client = createAgentClient(options)

​
Options

​
privateKey
`0x${string}`
required
EVM private key for the agent’s wallet. Must hold USDC on Base to pay for storage.
​
environment
'mainnet'
required
Target environment. Use 'mainnet' for Base Mainnet with real USDC.

​
estimateStorageCost

Check the cost before uploading. 
const estimate = await client.estimateStorageCost(
  1_000_000, // sizeInBytes
  30          // durationDays
)

console.log(estimate.usdc) // '0.000090' (USDC, 6 decimal places)
console.log(estimate.usd)  // '0.00'

​
Parameters

​
sizeInBytes
number
required
Raw byte count of the file
​
durationDays
number
required
How long to keep the file on IPFS

​
Response

​
usdc
string
Cost in USDC, formatted to 6 decimal places (e.g. '0.000090')
​
usd
string
Approximate USD cost, formatted to 2 decimal places

​
store

Upload a file and pay autonomously via x402. 
const result = await client.store(file, { durationDays: 30 })

​
Parameters

​
file
File
required
The file to upload. Use the standard Web API File object — works in Node.js 20+ and all modern runtimes.
​
options.durationDays
number
required
Storage duration in days

​
Response

​
cid
string
IPFS content identifier for the uploaded file (e.g. bafybei...)
​
expiresAt
string
ISO 8601 date string when the file will be removed from IPFS
​
fileName
string
Original file name
​
fileSize
number
File size in bytes

​
USDC on Base

USDC uses 6 decimal places on all EVM chains (Circle standard). The SDK and server handle conversion automatically.
NetworkUSDC Contract
Base Mainnet0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
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.

​
Framework integrations

AgentClient works with any framework that can hold an EVM private key: 
// LangChain tool
import { DynamicTool } from 'langchain/tools'

const storeTool = new DynamicTool({
  name: 'store_file',
  description: 'Store a file on IPFS and return its CID',
  func: async (filePath: string) => {
    const buffer = await fs.readFile(filePath)
    const file = new File([buffer], path.basename(filePath))
    const result = await client.store(file, { durationDays: 30 })
    return result.cid
  },
})

// CrewAI-style (TypeScript)
const storeAction = async (input: { filePath: string; days: number }) => {
  const buffer = await fs.readFile(input.filePath)
  const file = new File([buffer], path.basename(input.filePath))
  return client.store(file, { durationDays: input.days })
}

Pricing

Storage rate and cost calculator

Upload (SOL)

Human wallet uploads with Solana

CID Computation

How content identifiers work

Storage Payments

Payment mechanics