Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.toju.network/llms.txt

Use this file to discover all available pages before exploring further.

​
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 pins to IPFS 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.

​
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. 
import { createAgent, tool } from "langchain"
import * as z from "zod"
import { createAgentClient } from "@toju.network/x402"
import * as fs from "fs/promises"
import * as path from "path"

// Create the storage tool
const storeFileTool = tool(
  async ({ filePath, durationDays }) => {
    const client = createAgentClient({
      privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
      environment: "sepolia",
    })
    const buffer = await fs.readFile(filePath)
    const file = new File([buffer], path.basename(filePath))
    const result = await client.store(file, { durationDays })
    return JSON.stringify(result)
  },
  {
    name: "store_file_ipfs",
    description: "Store a file on IPFS via decentralized storage and pay with USDC autonomously on Base.",
    schema: z.object({
      filePath: z.string().describe("Absolute path to the file to store"),
      durationDays: z.number().describe("How many days to store the file"),
    }),
  }
)

// Use with LangChain agent
const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [storeFileTool],
})

const result = await agent.invoke({
  messages: [
    { role: "user", content: "Store ./test-data/sample.txt on IPFS for 30 days." },
  ],
})
This example demonstrates:
  1. Agent receives natural language request
  2. LLM decides to use the store_file_ipfs tool
  3. Tool reads file from disk and pays via x402
  4. File uploaded to IPFS, CID returned

​
Langchain demo

Autonomous AI Agent Storing Files on IPFS

Pricing

Storage rate and cost calculator

Upload (SOL)

Human wallet uploads with Solana

CID Computation

How content identifiers work

Storage Payments

Payment mechanics