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

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

Limits

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

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:

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