Agent Payments (x402)

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:

Send request

Agent sends POST /upload/agent with the file and storage parameters

Receive 402

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

Sign off-chain

SDK signs an EIP-3009 authorization (no on-chain transaction yet)

Retry with payment

SDK retries the request with the signed X-PAYMENT header attached

Facilitator settles

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

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

`0x${string}`

required

EVM private key for the agent’s wallet. Must hold USDC on Base to pay for storage.

'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

number

required

Raw byte count of the file

number

required

How long to keep the file on IPFS

Response

string

Cost in USDC, formatted to 6 decimal places (e.g. '0.000090')

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

required

The file to upload. Use the standard Web API File object — works in Node.js 20+ and all modern runtimes.

number

required

Storage duration in days

Response

string

IPFS content identifier for the uploaded file (e.g. bafybei...)

string

ISO 8601 date string when the file will be removed from IPFS

string

Original file name

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.

Network	USDC Contract
Base Mainnet	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`

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:

Agent receives natural language request
LLM decides to use the store_file_ipfs tool
Tool reads file from disk and pays via x402
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

​Overview

​Install

​Quick start

​createAgentClient

​Options

​estimateStorageCost

​Parameters

​Response

​store

​Parameters

​Response

​USDC on Base

​AI Agent Integrations

​LangChain

​Langchain demo

​Related

Pricing

Upload (SOL)

CID Computation

Storage Payments

Overview

Install

Quick start

createAgentClient

Options

estimateStorageCost

Parameters

Response

store

Parameters

Response

USDC on Base

AI Agent Integrations

LangChain

Langchain demo

Related