@payaion/mcp

@payaion/mcp

MCP server for Payaion — 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.

{
  "mcpServers": {
    "payaion": {
      "command": "npx",
      "args": ["-y", "@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.
• 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.

{
  "mcpServers": {
    "payaion": {
      "command": "npx",
      "args": ["-y", "@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.

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)

Everything above the line works without a key. list_on_marketplace, get_payment_requirements and purchase_asset 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.

Upload Methods

Each upload tool supports three mutually exclusive input methods:

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

Pricing & Marketplace

pricePerDownload: 0.50  # USD, charged in USDC on Base

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

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.

Or list separately after upload with list_on_marketplace.

Browsing the Marketplace

q: "oil analysis"
category: "reports"
page: 1
pageSize: 20

All URLs returned use the unified /d/{hash} page.

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.

Supported Clients

Any MCP client that supports stdio transport:

• Cursor
• Claude Desktop
• Cline
• Continue

CLI

npx @payaion/mcp --help
npx @payaion/mcp --version

Also Available

• Python: pip install payaion-mcp (PyPI)
• Docs: payaion.com/docs

License

MIT