fileshareforagents

# fileshareforagents

Client code for [fileshareforagents.online](https://fileshareforagents.online): storage and
file sharing for AI agents, paid per call in USDC through the [x402](https://x402.org)
protocol on Base. No account, no API key, no sign-up. Every paid call costs $0.01; status,
share links, passwords, delete and feedback are free.

An agent stores JSON or a file (up to 25 MB, 1 to 365 days), gets an id and a one-time
secret, and can hand the content to a human or another agent with a signed link or a
password-protected address. Content is deleted at expiry.

## In this repo

| Path | What |
|---|---|
| [`mcp/`](mcp/) | The MCP server, published as [`fileshareforagents-mcp`](https://www.npmjs.com/package/fileshareforagents-mcp) on npm and as `online.fileshareforagents/mcp` in the official MCP registry. |
| [`examples/typescript/`](examples/typescript/) | Upload, share with a human, delete, using `@x402/fetch`. |
| [`examples/python/`](examples/python/) | The same flow with the `x402` Python package. |
| [`examples/curl.sh`](examples/curl.sh) | The free surface and the 402 handshake, no wallet needed. |

## 60-second start (MCP)

Claude Code:

```
claude mcp add fileshare -e WALLET_KEY=0x... -e FILESHARE_NETWORK=testnet -- npx -y fileshareforagents-mcp
```

Claude Desktop, Cursor, Windsurf and other clients:

```json
{
  "mcpServers": {
    "fileshare": {
      "command": "npx",
      "args": ["-y", "fileshareforagents-mcp"],
      "env": { "WALLET_KEY": "0x...", "FILESHARE_NETWORK": "testnet" }
    }
  }
}
```

`testnet` (the default) uses Base Sepolia with free test USDC from
[faucet.circle.com](https://faucet.circle.com). `mainnet` uses real USDC on Base. The wallet
needs no ETH; the payment facilitator pays gas. The key stays on your machine.

## The API in one paragraph

`POST /v1/items` with the content as the body. Without payment the API answers
`402 Payment Required` with everything an x402 client needs; with a paying client the same
request returns `201` with `id`, `secret`, `expires_at` and `links`. Then
`GET /v1/items/{id}` (Bearer secret) reads it back, `POST /v1/items/{id}/links` makes a
signed share URL, `PUT /v1/items/{id}/password` protects the public address, and
`DELETE /v1/items/{id}` removes it. Full description written for agents:
[llms.txt](https://fileshareforagents.online/llms.txt). OpenAPI:
[openapi.json](https://fileshareforagents.online/openapi.json). Function-calling
definitions: [tools.json](https://fileshareforagents.online/tools.json).

## Prices

| Operation | Price |
|---|---|
| Store (includes 100 reads) | $0.01 |
| Extend expiry | $0.01 |
| 1,000 extra reads | $0.01 |
| Everything else | free |

## Feedback and abuse

`POST https://fileshareforagents.online/v1/feedback` with `{"type": "missing" | "bug" |
"abuse" | "other", "message": "..."}`. Abuse reports about a specific item include its
`item_id`. Terms: https://fileshareforagents.online/terms.

MIT licensed.