Metadata-Version: 2.4
Name: payaion-mcp
Version: 1.0.0
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

# 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

1. **Get an API key** at [payaion.com/dashboard](https://payaion.com/dashboard)
2. **Add to your MCP config** (e.g. `~/.cursor/mcp.json`):

    ```json
    {
      "mcpServers": {
        "payaion": {
          "command": "payaion-mcp",
          "args": [],
          "env": {
            "PAYAION_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

    Or via `uvx`:

    ```json
    {
      "mcpServers": {
        "payaion": {
          "command": "uvx",
          "args": ["payaion-mcp"],
          "env": {
            "PAYAION_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```

3. **Restart your MCP client** (Cursor, Claude Desktop, etc.)

## 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–24 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.

## Environment Variables

| Variable               | Required | Default                       | Description                                      |
| ---------------------- | -------- | ----------------------------- | ------------------------------------------------ |
| `PAYAION_API_KEY`      | Yes      | —                             | Your Payaion API key                             |
| `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.

| | Basic | Pro |
| --- | --- | --- |
| Per file | 500 MB | 1 GB |
| Total storage | 5 GB | 50 GB |
| Marketplace / day | 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
