🇺🇸English

Upload and Share via StableUpload

Upload any local file to S3-backed cloud storage via x402 micropayments. Returns a public URL. No API keys needed.

Setup

See rules/getting-started.md for installation and wallet setup.

Quick Reference

All uploads expire after 6 months.

Workflow

1. Check wallet balance

npx agentcash@latest balance

Ensure sufficient USDC balance for the chosen tier. If balance is low and the user needs funding details, run npx agentcash@latest accounts to get deposit links and wallet addresses.

2. Determine the tier

Pick the smallest tier that fits the file. Check file size first with ls -la or wc -c.

3. Buy the upload slot

npx agentcash@latest fetch https://stableupload.dev/api/upload -m POST -b '{"filename": "report.pdf", "contentType": "application/pdf", "tier": "10mb"}'

Parameters:

• filename — name for the uploaded file (required)
• contentType — MIME type (required, advisory for browser)
• tier — "10mb", "100mb", or "1gb" (required)

Response:

{
  "uploadId": "k7gm3nqp2",
  "uploadUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf?t=...",
  "publicUrl": "https://f.stableupload.dev/k7gm3nqp2/report.pdf",
  "expiresAt": "2026-08-19T00:00:00.000Z",
  "maxSize": 10485760
}

4. Upload the file via curl

Use Bash to PUT the file to the returned uploadUrl:

curl -s -X PUT "<uploadUrl>" -H "Content-Type: <mime>" --data-binary @/absolute/path/to/file

Critical: Use --data-binary (not -d) to preserve binary content. Use the absolute path.

5. Share the public URL

Present the publicUrl to the user. This URL is publicly accessible immediately and remains live for 6 months.

Common MIME Types

Listing Previous Uploads

To list uploads for the current wallet:

npx agentcash@latest fetch https://stableupload.dev/api/uploads

Get Upload Details

npx agentcash@latest fetch https://stableupload.dev/api/download/k7gm3nqp2

Key Details

• No API keys required — payment is the authentication
• Upload URLs expire in 1 hour — upload promptly after buying the slot
• Public URLs last 6 months from purchase date
• Any file type accepted — contentType is advisory for the browser, not a restriction
• S3-backed — files stored on AWS S3 with public read access
• Discovery endpoint : npx agentcash@latest discover https://stableupload.dev if you need to verify endpoints

Common Patterns

Upload a file the user just created: Skip discovery, go straight to wallet check + buy slot + upload.

Upload multiple files: Buy separate slots for each file. Slots can be purchased in parallel but uploads must use the correct uploadUrl for each.

User asks to "share" or "send" a file: Upload it and present the public URL. The URL can be shared anywhere.

Host images for emails: Upload the image, then reference the publicUrl in email HTML:

<img src="https://f.stableupload.dev/abc/photo.png" alt="Photo" />

Error Handling

• Insufficient balance : Run npx agentcash@latest accounts to show deposit links and wallet addresses
• File too large for tier : Suggest the next tier up
• Upload URL expired : Buy a new slot (the previous payment is non-refundable)
• curl fails : Verify the file path exists and the uploadUrl is correctly quoted

Weekly Installs

50

Repository

merit-systems/a…h-skills

GitHub Stars

1

First Seen

Feb 20, 2026

Security Audits

Gen Agent Trust HubFailSocketWarnSnykFail

Installed on

cursor50

gemini-cli50

github-copilot50

amp50

codex50

kimi-cli50