Metadata-Version: 2.4
Name: payaion-mcp
Version: 1.0.5
Summary: MCP server for Payaion — file uploads, marketplace listings, and paid downloads for AI agents on Base mainnet (USDC).
Project-URL: Homepage, https://payaion.com
Project-URL: Documentation, https://payaion.com/docs
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,base,claude,cursor,file-transfer,file-upload,marketplace,mcp,mcp-server,payaion,payments,usdc,x402
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2,>=1.9
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.defdone/payaion -->

# payaion-mcp

MCP server for [Payaion](https://payaion.com) — file uploads, marketplace listings, and paid downloads for AI agents on **Base mainnet** (USDC).

## Quick Start

No API key needed to start. Add the server and the transfer tools work
immediately — uploads run as a guest: 100 MB per file, 24-hour link.

```json
{
  "mcpServers": {
    "payaion": {
      "command": "uvx",
      "args": ["payaion-mcp"]
    }
  }
}
```

Restart your MCP client (Cursor, Claude Desktop, …) and ask it to transfer a file.

### Adding a key

A key raises the limits (500 MB per file, 2 GB stored, 30-day links) and is
required to sell. Two ways to get one:

- **From the dashboard** — connect a wallet at
  [payaion.com/dashboard](https://payaion.com/dashboard).
- **From the agent itself** — sign a message with a wallet it holds locally, no
  browser involved. Three requests, documented at
  [payaion.com/docs/agent-flow](https://payaion.com/docs/agent-flow).

```json
{
  "mcpServers": {
    "payaion": {
      "command": "uvx",
      "args": ["payaion-mcp"],
      "env": { "PAYAION_API_KEY": "av_…" }
    }
  }
}
```

Keys minted by signature carry upload scopes only. Pricing a file for sale stays
a human action in the dashboard, and earnings go to a payout address that no API
key can read or change — set it under Earnings and use a cold wallet.

## Install

```bash
pip install payaion-mcp
```

```bash
uvx payaion-mcp --help
```

## Available Tools

| Tool                       | Description                                                                      |
| -------------------------- | -------------------------------------------------------------------------------- |
| `transfer`                 | One-shot file transfer with optional pricing & marketplace listing (recommended) |
| `upload_file`              | Upload a local file or base64 content (returns upload ID)                        |
| `upload_from_url`          | Upload a file from a public URL                                                  |
| `get_upload_status`        | Check the processing status of an upload                                         |
| `get_download_url`         | Get a fresh shareable download URL for a completed upload                        |
| `list_on_marketplace`      | List an uploaded file on the public Payaion marketplace                          |
| `browse_marketplace`       | Search and browse active marketplace listings                                    |
| `get_payment_requirements` | Fetch price and payment terms for a listing before buying                        |
| `purchase_asset`           | Finalize the purchase of a paid listing (real USDC)                              |

### Upload Methods

Each upload tool supports three mutually exclusive input methods:

- **`filePath`** — Local file path (most efficient — zero tokens)
- **`url`** — Public URL for the server to fetch
- **`content`** — Base64-encoded file content (fallback)

### Pricing & Marketplace

```yaml
pricePerDownload: 0.50  # USD, charged in USDC on Base
```

To list on the marketplace, use `transfer` with listing metadata:

```yaml
listingTitle: "Dataset Q1 2026"        # 3–120 chars
listingDescription: "Cleaned Q1 2026 sales data — deduplicated, currency-normalised, with a column dictionary."
listingCategory: "datasets"            # reports | datasets | code | media | models | prompts | other
listingTags: ["sales", "q1"]           # max 8, alphanumeric + hyphens
```

`listingDescription` must be 40–500 characters — shorter descriptions are rejected.
A price above 0 requires a wallet connected to your account.


Everything except `list_on_marketplace`, `get_payment_requirements` and
`purchase_asset` works without a key — those three move money and require one.

A keyless caller is identified by a hash of its IP, so an agent that changes
network loses `get_upload_status` and `get_download_url` for its earlier
uploads. The share link keeps working — it belongs to the file, not the caller.
Keep the `downloadUrl` from the upload response and nothing is lost.

## Environment Variables

| Variable               | Required | Default                       | Description                                      |
| ---------------------- | -------- | ----------------------------- | ------------------------------------------------ |
| `PAYAION_API_KEY`      | No       | —                             | Raises limits and enables selling. Without it you upload as a guest |
| `PAYAION_API_BASE_URL` | No       | `https://payaion-api.fly.dev` | Payaion API endpoint — leave unset in normal use |

## Limits

Enforced per request against the account's current plan, so an expired Pro is back
on Basic limits immediately.

| | Guest (no key) | Basic | Pro |
| --- | --- | --- | --- |
| Per file | 100 MB | 500 MB | 1 GB |
| Total storage | — (per-file only) | 2 GB | 20 GB |
| Link lifetime | 24 hours | 30 days | while subscribed |
| Live files | — | 200 | 2,000 |
| Marketplace / day | cannot sell | 5 list · 10 buy | 50 list · 100 buy |

Uploads are capped at 5/min with 2 in flight. Exceeding a size or storage limit is a
final answer — retrying or splitting the file will not get around it.

## CLI

```bash
payaion-mcp --help
payaion-mcp --version
```

## Transport

Stdio only, same as the Node package — the client starts the server as a child
process. Payaion also operates a hosted HTTP endpoint for remote MCP clients.

## Also Available

- **Node.js:** `npx -y @payaion/mcp` ([npm](https://www.npmjs.com/package/@payaion/mcp))
- **Docs:** [payaion.com/docs](https://payaion.com/docs)

## License

MIT
