MCP Server

The Payaion MCP server exposes 9 tools: uploading files, checking status, fetching download URLs, and both sides of the marketplace — listing your own files and browsing, pricing, and buying someone else's. Available as an npm package (@payaion/mcp) and a Python package (payaion-mcp).

Available tools

transferRecommended

One-shot file transfer with optional pricing and marketplace listing. Returns a shareable download URL in a single call.

Parameter	Type	Description
`filePath`	string?	Local file path (stdio mode only, zero tokens)
`url`	string?	Public URL for the server to fetch
`content`	string?	Base64-encoded file content (fallback)
`fileName`	string?	Override the file name
`mimeType`	string?	Override the MIME type
`pricePerDownload`	number?	USD price per download (0 = free)
`listingTitle`	string?	Marketplace title (3–120 chars). Auto-lists when set.
`listingDescription`	string?	What the buyer gets, 40–500 chars. Required once `listingTitle` is set
`listingCategory`	string?	reports, datasets, code, media, models, prompts, other
`listingTags`	string[]?	Up to 8 tags for discovery
`idempotencyKey`	string?	Prevent duplicate uploads on retry

Exactly one of filePath, url, or content is required. Use filePath for local files (most efficient — zero token cost).

upload_file

Low-level upload — returns immediately with an upload ID. Use get_upload_status to poll for completion.

Parameter	Type	Description
`filePath`	string?	Local file path (stdio only)
`content`	string?	Base64-encoded content
`fileName`, `mimeType`	string?	Optional overrides
`pricePerDownload`	number?	USD price per download
`idempotencyKey`	string?	Prevent duplicate uploads

upload_from_url

Upload a file from a public URL. Returns immediately — poll for status.

Parameter	Type	Description
`url`	string	Public HTTPS URL to fetch (required)
`fileName`	string?	Optional file name override
`pricePerDownload`	number?	USD price per download
`idempotencyKey`	string?	Prevent duplicate uploads

get_upload_status

Check the processing status of an upload. Returns status, ready flag, and timestamp.

Parameter	Type	Description
`uploadId`	string	The upload ID to check (required)

get_download_url

Get a fresh, shareable download URL for a completed upload.

Parameter	Type	Description
`uploadId`	string	The upload ID (required)

list_on_marketplace

List a READY upload on the marketplace for public discovery and purchase.

Parameter	Type	Description
`uploadId`	string	Upload to list (required, must be READY)
`title`	string	Listing title, 3–120 chars (required)
`description`	string	What the buyer gets, 40–500 chars (required)
`tags`	string[]?	Up to 8 discovery tags
`category`	string?	reports, datasets, code, media, models, prompts, other

browse_marketplace

Search active listings. Returns title, price, seller address, file info and the page URL for each hit.

Parameter	Type	Description
`q`	string?	Keyword, matched against title and description (max 100 chars)
`category`	string?	reports, datasets, code, media, models, prompts, other
`page`, `pageSize`	number?	Defaults 1 and 20; both cap at 100

get_payment_requirements

Step one of buying. Tells you whether an asset is free and, if it is paid, returns the x402 payment requirements your wallet needs to sign.

Parameter	Type	Description
`uploadId`	string	The listed asset to price (required)

Returns isFree, an asset summary, and for paid assets a paymentRequirements object. Requires the marketplace:read scope.

purchase_asset

Step two. Submits the signed payment, settles it on Base, and returns a receipt with a download URL.

Parameter	Type	Description
`uploadId`	string	The asset to buy (required)
`paymentPayload`	object	`x402Version`, `scheme: "exact"`, `network`, and the signed `payload`

The receipt's directDownloadUrl can be fetched straight away with your X-Aion-Key header. Requires the marketplace:purchase scope.

Input methods

Upload tools accept exactly one of three input methods:

filePathRecommended

Local file path. Stdio mode only. Most efficient — the file is streamed directly without base64 encoding, using zero tokens.

url

Public HTTPS URL. The server fetches the file directly. No token cost.

content

Base64-encoded file content. Fallback for HTTP transport mode where local file access is not available. Uses tokens proportional to file size.

Transport

Both packages speak stdio, the transport every MCP client supports: npx @payaion/mcp for Node and payaion-mcp for Python. Because the server runs on your machine, filePath streams a local file straight through without spending tokens on base64.

Streamable HTTP transport is not shipped in either package. If you need a remote MCP endpoint — for a hosted agent that cannot spawn a local process — run the server yourself from apps/mcp in the repository. Over HTTP the server has no access to your filesystem, so use url or content instead of filePath.

Environment variables

Variable	Required	Default	Description
`PAYAION_API_KEY`	Yes	—	Your API key
`PAYAION_API_BASE_URL`	No	https://payaion-api.fly.dev	API base URL

Next steps

MCP Quickstart — Setup in under 2 minutes
Marketplace & Pricing — Sell files via the marketplace
Marketplace API — Listing endpoint reference