x402.storage

Permanent file storage for Claude Code sessions using IPFS.

Commands

• /x402storage:setup - Configure the MCP server and add a wallet
• /x402storage:wallet - Show all wallets with addresses and balances
• /x402storage:switch-wallet - Switch active wallet between EVM and Solana
• /x402storage:store <file> - Upload a file and get a permanent URL
• /x402storage:fetch <url> - Fetch content from an x402.storage URL
• /x402storage:recall - Restore context from last saved memory

How It Works

Files uploaded via x402.storage are stored permanently on IPFS with branded URLs like https://x402.storage/{cid}. These URLs work forever - use them to persist artifacts between sessions.

$0.01 per file. $1 = 100 uploads. Pay once, store forever.

Agent Memory Convention

x402.storage uses the .agent/ directory convention for persistent memory:

.agent/
  x402storage/
    memory/
      INDEX.md      # Table of all stored memories with dates, descriptions, URLs

This convention allows:

• Team sharing: Commit .agent/x402storage/memory/INDEX.md to share context across team members
• Interoperability: Other agent tools can use .agent/<tool-name>/ for their own storage
• Simple recovery: Read INDEX.md to see all stored memories and fetch the latest

INDEX.md contains a markdown table tracking all stored sessions.

Multi-Wallet Support

x402.storage supports both EVM (Base/USDC) and Solana wallets. You can:

• Have wallets for both chains configured simultaneously
• Switch between them with /x402storage:switch-wallet
• Add additional wallets anytime with /x402storage:setup

Wallet configuration is stored in ~/.x402-config.json.

Setup Flow

When user runs /x402storage:setup:

1. Check if MCP is configured

   • Run: claude mcp list | grep x402storage
   • If found, proceed to check which wallets exist

2. Check existing config

   • Check if ~/.x402-config.json exists
   • Parse to see which wallets are already configured

3. Ask which chain to add (use AskUserQuestion)

   • Options: "Base (USDC)" or "Solana (SOL)"
   • If that chain's wallet already exists, ask for confirmation before regenerating

4. Generate wallet silently (NEVER output private keys)

   • Base:

     npx -y @x402storage/mcp --generate-evm-wallet
     

   • Solana:

     npx -y @x402storage/mcp --generate-sol-wallet
     

   • IMPORTANT: Never cat, echo, or display the config file contents

5. Add MCP (only if not already configured)

   • If MCP not in list:

     claude mcp add x402storage -- npx @x402storage/mcp
     

6. Output ONLY this:

   {chain} wallet created!
   
   Send {USDC/SOL} to: {address}
   
   Pays for permanent IPFS storage. ~$0.01/MB.
   
   After restart, run /x402storage:wallet to verify.
   

No seed phrases, no verbose output. Just the address and next step.

Store Flow

When user runs /x402storage:store <file>:

1. Check if mcp__x402storage__store_file tool is available
2. If not available, tell user to run /x402storage:setup first
3. Upload the file using the MCP tool
4. Create .agent/x402storage/memory/ directory if it doesn't exist
5. Update INDEX.md with date, description, and URL
6. Return the permanent URL

Recall Flow

When user runs /x402storage:recall:

1. Check if .agent/x402storage/memory/INDEX.md exists
2. If not found, tell user "No memory found. Store context first."
3. Read INDEX.md to get the last stored URL
4. Fetch that URL using WebFetch
5. Display the restored content

Fetch Flow

When user runs /x402storage:fetch <url>:

1. Validate URL is an x402.storage URL
2. Fetch content using WebFetch
3. Display or offer to save to file

Wallet Flow

When user runs /x402storage:wallet:

1. Check if MCP is configured
2. Call mcp__x402storage__wallet tool
3. Display all configured wallets with balances
4. Active wallet is marked with [ACTIVE]
5. If multiple wallets, mention /x402storage:switch-wallet

Switch Wallet Flow

When user runs /x402storage:switch-wallet:

1. Check which wallets are configured in ~/.x402-config.json
2. If only one wallet, tell user to add another with /x402storage:setup
3. Ask which wallet to make active
4. Call mcp__x402storage__set_active_wallet tool
5. Tell user to restart Claude Code for changes to take effect