The x402drop guide
A little context. A faster start.
Everything you need to share from your browser or build file sharing into your tools.
Use the website
Upload, pay, and share.
Connect an assistant
API keys and MCP tools.
Build an integration
x402 payments and uploads.
From a file to a share link
- Sign in with a wallet. Connect an EVM or Solana wallet and sign the login message. Login proves ownership of your workspace.
- Choose your files and storage time. Get a live quote before payment. Each drop supports up to 1000 files, 5 GB per file, and 10 GB total, for up to 90 days.
- Pay with USDC. Choose a network offered by the payment challenge. The client signs the x402 payment and the server verifies settlement.
- Finish the upload and share. Anyone with the link can download completed files for free while the drop is active.
The workspace dashboard tracks drops, receipts, upload progress, and activity. You can resume an interrupted upload or extend eligible storage there. Expired downloads become unavailable immediately; object cleanup runs separately.
Wallet login and x402 payments
Wallet sign-in and payment are separate actions. Sign-in uses a short-lived, one-time challenge for an EVM or Solana signature. Spending uses an explicit USDC payment signature for the selected payment requirement.
The server offers Base, Arbitrum One, or Solana only when the configured receiving wallet and facilitator support that network. Read the actual accepts array for available options. Solana sign-in remains available independently of Solana payment configuration.
| x402 V2 header | Purpose |
|---|---|
| PAYMENT-REQUIRED | Payment requirements on an HTTP 402 response. |
| PAYMENT-SIGNATURE | The wallet-signed payment payload sent on retry. |
| PAYMENT-RESPONSE | The confirmed settlement receipt. |
Use the maintained x402 client SDK with a wallet signer for the selected network. Payment requirements use integer USDC atomic units; USDC has six decimal places.
Give your assistant workspace context
Open Integrations, sign in, and create a named API key. Choose its permissions and expiration, then copy the key when shown. The server stores its hash; you can revoke it anytime.
| MCP tool | Permission | Result |
|---|---|---|
| drop_list | drops:read | Your drops, files, and expiry. |
| drop_get | drops:read | One drop and its receipt reference. |
| storage_analytics | analytics:read | Storage, spending, and tracked activity. |
| storage_quote | quotes:create | An expiring signed quote. |
MCP uses Streamable HTTP at /api/mcp with a bearer API key on every request. It supports MCP 2026-07-28 and compatible 2025 clients. Each account tool reads only the key owner’s data. This connection uses API-key authentication.
Codex and Cursor snippets are available in Integrations. The plugin includes an MCP configuration and assistant skill. Paid storage and uploads use the agent API; MCP does not sign payments or spend funds.
Create storage from your application
Start with POST /api/agent/drops. The verified payment identifies the uploading wallet. Generate a private random Idempotency-Key before the first request and keep it unchanged for every retry.
const idempotencyKey = crypto.randomUUID();
const body = JSON.stringify({
files: [{ name: "report.pdf", sizeBytes: 2048, mimeType: "application/pdf" }],
durationSeconds: 86400
});
const challenge = await fetch("/api/agent/drops", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey
},
body
});
// 402: use an x402 wallet client to sign an offered payment requirement.
// Retry the same body and Idempotency-Key with PAYMENT-SIGNATURE.
// Keep idempotencyKey private and unchanged on every retry.- Validate the HTTP 402 requirements and select a supported network. Use your x402 wallet client to sign the offered requirement.
- Retry the exact file body with the same
Idempotency-Keyand encodedPAYMENT-SIGNATURE. The Idempotency-Key value must contain 16–128 allowed characters, such as a random UUID. - On success, save
slug,uploadToken, upload instructions, and receipt. Upload file bytes directly to the returned URLs. - Complete the upload through the token-protected endpoints below. Files become downloadable after storage objects are verified.
| Endpoint | Access | Purpose |
|---|---|---|
| POST /api/agent/drops | x402 payment | Pay for storage and receive upload instructions. |
| POST /api/agent/drops/{slug}/resume | Upload token | Refresh incomplete file upload instructions. |
| POST /api/agent/drops/{slug}/multipart | Upload token | Get part URLs, list parts, and complete multipart uploads. |
| POST /api/agent/drops/{slug}/complete | Upload token | Verify file objects and finish the drop. |
| GET /api/agent/drops/{slug} | Share link | Read public drop metadata. |
| GET /d/{slug}/download | Share link | Download a completed, active drop. |
Send Authorization: Bearer <uploadToken> to upload endpoints. Upload tokens and MCP API keys are separate credentials. If a paid response says uploadSetupPending, use resume to continue the existing drop.
Recover interrupted work
If a payment returns HTTP 202 with paymentPending, retain the request and payment identifier. Check its status in your signed-in workspace and continue that payment rather than signing another charge.
For interrupted uploads, use Resume upload in the dashboard or the agent resume endpoint with the original token. Larger files use multipart uploads; send the returned part ETags when completing them. Completion checks actual storage objects before files are marked ready.
Download counts represent tracked download starts from this release onward. They indicate requested downloads and do not measure completed transfers or historical activity before tracking began.