x402 AI Agent Storage
Seamless Decentralized Storage for AI Agents on SKALE Network
Overview
x402 provides an easy way for AI agents to store data on the Fula network. By leveraging the x402 payment protocol on the SKALE network, AI agents can autonomously pay for and manage decentralized storage without any human interaction.
Data stored on Fula is decentralized — it is distributed across a peer-to-peer network backed by IPFS, meaning no single entity controls your data. Every file is content-addressed using cryptographic hashes, ensuring data integrity and tamper resistance. The Fula S3-compatible gateway makes it trivially easy for any application or agent that speaks the S3 protocol to upload, download, and manage objects in this decentralized layer.
🤖 Built for AI Agents
AI agents send a request, receive a payment requirement via HTTP 402, sign a transaction on-chain, and complete the upload — all programmatically with zero human intervention.
🌐 Decentralized by Default
Files are stored on the Fula peer-to-peer network powered by IPFS. No centralized servers, no single point of failure. Each object is content-addressed and verifiable.
📦 S3-Compatible API
Use familiar S3 operations (PUT, GET, DELETE) with bucket-based organization. Any S3 client or SDK can interact with the x402 gateway.
⛓️ SKALE Network Payments
Payments are settled on the SKALE network with zero gas fees. The x402 protocol handles payment negotiation and verification automatically.
The x402 endpoint is available at:
https://x402.api.cloud.fx.land/
How It Works
The x402 payment protocol uses HTTP status code 402 Payment Required to negotiate payments between clients and the storage gateway. Here is the flow:
AI Agent x402 Gateway SKALE Network
│ │ │
│ 1. PUT /bucket/file.txt │ │
│ ─────────────────────────────────>│ │
│ │ │
│ 2. HTTP 402 Payment Required │ │
│ { amount, token, payTo } │ │
│ <─────────────────────────────────│ │
│ │ │
│ 3. Sign & send USDC payment │ │
│ ──────────────────────────────────────────────────────────────────>│
│ │ │
│ 4. PUT /bucket/file.txt │ │
│ X-PAYMENT: [signed receipt] │ │
│ ─────────────────────────────────>│ │
│ │ 5. Verify payment on-chain │
│ │ ──────────────────────────────>│
│ │ │
│ │ 6. Payment confirmed │
│ │ <──────────────────────────────│
│ │ │
│ 7. HTTP 200 OK │ │
│ { cid, expires_at, tx_hash } │ │
│ <─────────────────────────────────│ │
│ │ │
│ Downloads are FREE │ │
│ GET /bucket/file.txt │ │
│ ─────────────────────────────────>│ │
│ HTTP 200 OK + file data │ │
│ <─────────────────────────────────│ │
Note: Only the uploader (identified by their wallet address) can download their uploaded files. Downloads and deletes are free — no payment is required.
API Endpoints
The following endpoints are available on the x402 gateway. All file operations use the S3-style /{bucket}/{key} path convention where the bucket acts as a folder namespace.
Health & Service
GET /
Returns basic service information, version, and documentation links.
GET /health
Health check reporting service status, database connectivity, version, and uptime.
GET /health/detailed
Detailed health check including cleanup statistics and ephemeral object counts.
GET /health/pricing
Returns current pricing configuration with example cost calculations.
File Operations
PUT /{bucket}/{key}
Upload a file. Requires x402 payment. Returns 402 with payment requirements on first request. Include the X-PAYMENT header (base64-encoded signed receipt) on retry. Optionally set X-Fula-TTL (60–2,592,000 seconds) to control storage duration.
Response: { success, cid, bucket, key, size_bytes, expires_at, tx_hash, gateway_url }
GET /{bucket}/{key}
Download a file. Free — no payment required. Requires wallet identity via X-PAYMENT header or JWT. Only the original uploader can access the file. Returns the file binary with Content-Type, Content-Length, and ETag headers.
HEAD /{bucket}/{key}
Check file existence. Free. Returns metadata headers (Content-Length, ETag, expiry) without downloading the file body.
DELETE /{bucket}/{key}
Delete a file. Free. Requires wallet verification via X-PAYMENT or JWT. Only the original uploader can delete their files.
Credit Management
POST /credit
Top up FULA credits. Add credits to your account via x402 payment to extend storage duration before the system deletes objects due to low credit. Returns 402 with minimum payment amount on first request.
Response: { success, creditsAdded, newBalance, amountPaidUsdc, tx_hash }
Pricing
Storage pricing is calculated based on file size and storage duration, paid in USDC on the SKALE network.
| Parameter | Value |
|---|---|
| Base price | $0.01 USDC per MB per hour |
| Minimum charge | $0.001 USDC |
| Formula | ceil(sizeMB × hours × $0.01) in micro USDC |
| Default TTL | 24 hours (configurable via X-Fula-TTL header, 60s–2,592,000s) |
| Downloads | Free |
| Deletes | Free |
| Gas fees | Zero (SKALE network) |
Automatic cleanup: Expired objects are deleted every 60 seconds. Unpaid uploads (pending payment) are cleaned up after 30 minutes.
Getting Started
To test the x402 endpoints, clone the pinning service repository and run the provided test scripts. You will need a wallet private key with some USDC on the SKALE network.
git clone https://github.com/functionland/pinning-service cd pinning-service/x402-skale/scripts
Test scripts and examples are available at: github.com/functionland/pinning-service/x402-skale/scripts
Prerequisites: You need Node.js installed and a wallet private key with USDC balance on the SKALE network.
Upload Test
Sends a request to the x402 gateway, receives the required payment amount, creates and sends a test file to be uploaded, settles the payment on-chain, and then downloads and verifies the uploaded file. The API uses S3 conventions where bucket-name acts as a folder. The test script uses test-bucket as default and creates a "hello world" test file to upload.
npx tsx test-x402-upload.ts [wallet-private-key] https://x402.api.cloud.fx.land
Download Test
Downloads an already uploaded file. No payment is needed. Note that only the original uploader can read the uploaded file.
npx tsx test-x402-download.ts [uploader-private-key] "[bucket-name]" "[file-name]" https://x402.api.cloud.fx.land
Credit Test
Adds credit to the user's account in case the user wants to extend the storage time before the system deletes objects due to low credit. The amount is specified in micro USDC (e.g., 10000 = $0.01).
npx tsx test-x402-credit.ts [uploader-private-key] https://x402.api.cloud.fx.land [micro-USDC-amount]
Delete Test
Tests the delete endpoint to remove an uploaded file. Deleting is free and requires the uploader's wallet for identity verification.
npx tsx test-x402-delete.ts [uploader-private-key] "[bucket-name]" "[file-name]" https://x402.api.cloud.fx.land
OpenAPI Specification
The full OpenAPI specification for the x402 storage gateway is available at:
You can import this specification into tools like Swagger Editor or Postman to explore and test all available endpoints interactively.