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:

Check if MCP is configured
- Run: claude mcp list | grep x402storage
- If found, proceed to check which wallets exist
Check existing config
- Check if ~/.x402-config.json exists
- Parse to see which wallets are already configured
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
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
Add MCP (only if not already configured)
- If MCP not in list:
```
claude mcp add x402storage -- npx @x402storage/mcp
```

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>:

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

Recall Flow

When user runs /x402storage:recall:

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

Fetch Flow

When user runs /x402storage:fetch <url>:

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

Wallet Flow

When user runs /x402storage:wallet:

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

Switch Wallet Flow

When user runs /x402storage:switch-wallet:

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

x402storage

SKILL.md