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": "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, 28-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": "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

pip install payaion-mcp

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)
list_storage	List folders (with paths and file counts), the files in one, and storage used
create_folder	Create a folder, optionally nested inside another (up to 8 levels)
update_folder	Rename a folder, move it under a different parent, or both
delete_folder	Delete a folder and its subfolders — the files inside move back to the root
move_file	File an upload into a folder, or back to the storage root

Storage folders

Folders group what an account already holds. They are metadata only: moving or deleting one never touches a blob, never deletes a file, and never changes a share link, a price or an expiry. Deleting a folder drops its subfolders and returns the files inside to the storage root — deleting a file stays a separate, explicit action. Names are unique among siblings, nesting stops at 8 levels, and folders count against nothing: the plan quota measures uploaded bytes.

Reading needs the upload:status scope, every write needs upload:create. A keyless (guest) caller has no storage, so these five tools require a key.

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

pricePerDownload: 0.50  # USD, charged in USDC on Base
payoutAddress: "0x..."  # only without an API key — see below

With an API key, earnings go to the payout wallet set in your dashboard and payoutAddress is ignored. Without a key, it is the only way to get paid: pass the wallet the 95% creator share should land in. Payments are final, so a mistyped address is unrecoverable, and an exchange deposit address usually will not credit a Base transfer arriving from a contract — use a wallet you control.

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.

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

get_download_url needs a key: proving you own an upload requires an identity, and a keyless caller has none. get_upload_status still works without one. This costs a keyless agent nothing — the share link belongs to the file, not the caller, so 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	12h/24h/7d/14d (default 24h)	28 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

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.

Protocol

Speaks both MCP eras from the same server, so no client has to move first:

Client speaks	What happens
2026-07-28 (stateless, no handshake)	Served natively — no initialize, no session id
2025-11-25 and earlier	Served through the initialize handshake as before

This matters because the eras do not degrade into each other: a client that only speaks the new revision cannot fall back, and a client that only speaks the old one cannot fall forward. Serving both is the only arrangement where nobody breaks. Session ids, GET/DELETE on the endpoint, and SSE stream resumption are gone with the new revision — the HTTP endpoint answers 405 for them.

Also Available

• Node.js: npx -y @payaion/mcp (npm)
• Docs: payaion.com/docs

License

MIT