payaion-transfer

Transfer files via the Payaion REST API, set USDC per-download pricing on Base mainnet, and list on the marketplace. Use for agent-to-human, agent-to-agent, and agent-to-marketplace file flows.

Payaion Transfer (ClawHub / OpenClaw)

Audience: OpenClaw agents installed from ClawHub. This skill is curl/REST-only. For Cursor or Claude Code, use the separate payaion-agent skill (MCP-first).

Previously published as AgentVee Transfer, which passed 600+ downloads during the testnet phase. This is the production release: Base mainnet, live USDC, and PAYAION_API_KEY in place of AGENTVEE_API_KEY.

Transfer files between agents and humans. Upload from URL or local disk, set per-download pricing in USD (settled in USDC on Base mainnet), list on the Payaion marketplace, and share download links — all via the Payaion REST API.

API	https://payaion-api.fly.dev
Web	https://payaion.com
Chain	Base mainnet · USDC
Auth header	X-Aion-Key: $PAYAION_API_KEY

No API key needed to transfer. Omit the X-Aion-Key header entirely and the upload runs as a guest: 100 MB per file, 24-hour link, no account. A key raises the limits (500 MB, 2 GB stored, 28-day links). You can sell without a key too — see X-Payout-Address below.

Get one at payaion.com/dashboard, or have the agent mint its own by signing a message with a wallet it holds locally — three requests, no browser: payaion.com/docs/agent-flow.

Earnings go to a payout address set in the dashboard. No API key can read or change it, so a compromised agent key costs uploads, not money.

Three supported flows:

Flow	Description
Agent → Human	Upload a file, share the download link
Agent → Agent	Upload + share the uploadId or download URL
Agent → Marketplace	Upload with pricing, list publicly for paid downloads

---

Authentication

Optional for transfers. Send the header when a key is set, omit it entirely when it is not — the upload then runs as a guest.

text

X-Aion-Key: $PAYAION_API_KEY      # omit this line if PAYAION_API_KEY is unset

Listing on the marketplace and buying still require a key. Both fail with 403 insufficient_scope or forbidden without one.

Base URL (production): https://payaion-api.fly.dev

---

One-Shot API (recommended — single request does everything)

Upload + wait for ready + set price + list on marketplace — all in ONE curl call. The server handles polling internally and returns the final result.

Upload a local file with pricing and marketplace listing

bash

curl -s -X POST https://payaion-api.fly.dev/v1/aion/upload \
  -H "X-Aion-Key: $PAYAION_API_KEY" \
  -H "X-Wait-For-Ready: true" \
  -H "X-Price-Per-Download: 0.25" \
  -H 'X-Listing-Intent: {"title":"My Report","description":"Market analysis","category":"reports","tags":["market","analysis"]}' \
  -F "file=@/path/to/file.pdf"

Upload from URL with pricing and marketplace listing

bash

curl -s -X POST https://payaion-api.fly.dev/v1/aion/upload-url \
  -H "X-Aion-Key: $PAYAION_API_KEY" \
  -H "X-Wait-For-Ready: true" \
  -H "X-Price-Per-Download: 0.25" \
  -H 'X-Listing-Intent: {"title":"My Report","description":"Market analysis","category":"reports","tags":["market","analysis"]}' \
  -H "Content-Type: application/json" \
  -d '{"url": "URL_HERE"}'

Response (200 — everything done)

json

{
  "uploadId": "up_a1b2c3d4e5f6g7h8",
  "status": "READY",
  "ready": true,
  "downloadUrl": "https://payaion.com/d/abc123xyz789",
  "expiresAt": "2026-04-10T12:00:00.000Z",
  "pricePerDownload": "0.25",
  "url": "https://payaion.com/m/abc123xyz789"
}

If you get 202 instead of 200

202 means the file was accepted but is still processing — the server either had no wait slot free or wait mode is off ("waitUnavailable": true). This is the only case where polling is allowed: call the status endpoint below every few seconds until ready is true (give up after ~2 minutes and report the last status).

Headers explained

Header	Required	Description
X-Aion-Key	No	API key. Omit it to upload as a guest; required to list or buy
X-Wait-For-Ready	Always send	true — server waits until the file is READY (up to ~120s) and returns 200
X-Price-Per-Download	No	Price in USD (e.g. 0.25). Omit for free downloads. Above 0 requires a connected wallet
X-Listing-Intent	No	JSON string with marketplace listing data. Server auto-lists after READY. Needs a key with the marketplace:list scope — a keyless caller is refused with 403
X-Payout-Address	No	Keyless sellers only: the wallet a priced download pays out to (0x…, 40 hex characters). This is what lets an agent sell with no account. Ignored when a key is sent, because that account's payout address is a dashboard setting

X-Listing-Intent format

json

{
  "title": "string (3–120 chars, required)",
  "description": "string (40–500 chars, REQUIRED — what the buyer gets)",
  "category": "reports|datasets|code|media|models|prompts|other",
  "tags": ["tag1", "tag2"]
}

• description is required and must be at least 40 characters. A shorter or missing description fails the whole request with 422. Write a real sentence or two about what the buyer gets — never a placeholder.
• Tags: max 8, alphanumeric + hyphens only, max 30 chars each.
• A price above 0 needs somewhere to pay: a wallet on the account, or X-Payout-Address when uploading without a key. Otherwise the request fails with 400 wallet_required.
• Selling without a key gives the file a 14-day window rather than 24 hours — nobody can buy inside a day — and is capped to a few such uploads per day per network address.

If the user doesn't specify title/description/category/tags, generate them from the filename and context.

---

Browse marketplace

bash

curl -s "https://payaion-api.fly.dev/v1/aion/marketplace/browse" \
  -H "X-Aion-Key: $PAYAION_API_KEY"

With filters:

bash

curl -s "https://payaion-api.fly.dev/v1/aion/marketplace/browse?q=oil&category=reports&page=1&pageSize=10" \
  -H "X-Aion-Key: $PAYAION_API_KEY"

Query parameters

Param	Type	Default	Description
q	string	—	Search title and description (max 100 chars)
category	string	—	Filter: reports, datasets, code, media, models, prompts, other
page	int	1	Page number (1–100)
pageSize	int	20	Results per page (1–100)

Response (200)

json

{
  "listings": [
    {
      "uploadId": "up_a1b2c3d4e5f6g7h8",
      "title": "Oil Market Analysis",
      "description": "Crude oil trends",
      "category": "reports",
      "tags": ["oil", "market"],
      "fileName": "oil-market-analysis.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 51200,
      "pricePerDownload": "0.25",
      "sellerAddress": "0x7811…ac55",
      "listedAt": "2026-03-27T01:30:00.000Z",
      "url": "https://payaion.com/m/BiMHwpOqTrxa"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

• url — the market listing page (/m/<hash>), where a buyer sees the description and price

---

Other operations (use only when needed)

Check upload status

bash

curl -s https://payaion-api.fly.dev/v1/upload/UPLOAD_ID/status \
  -H "X-Aion-Key: $PAYAION_API_KEY"

Get a fresh download URL

bash

curl -s -X POST https://payaion-api.fly.dev/v1/upload/UPLOAD_ID/download-url \
  -H "X-Aion-Key: $PAYAION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete an upload

bash

curl -s -X DELETE https://payaion-api.fly.dev/v1/upload/UPLOAD_ID/delete \
  -H "X-Aion-Key: $PAYAION_API_KEY"

---

Storage folders

Folders group what the account already holds. They are metadata, not storage: a move never touches the file, and deleting a folder keeps every file inside it — the files drop back to the storage root with their share link, price and expiry unchanged. Deleting a file is the separate call above.

Nesting stops at 8 levels, sibling names must be unique and cannot contain slashes, and folders count against no quota. A key is required — a keyless (guest) caller has no storage to organise.

See what is there

bash

# every folder with its full path and file count, the files at the root,
# and bytes used against the plan limit
curl -s https://payaion-api.fly.dev/v1/storage \
  -H "X-Aion-Key: $PAYAION_API_KEY"

# the files inside one folder
curl -s "https://payaion-api.fly.dev/v1/storage?folderId=FOLDER_ID" \
  -H "X-Aion-Key: $PAYAION_API_KEY"

Create a folder

bash

curl -s -X POST https://payaion-api.fly.dev/v1/folders \
  -H "X-Aion-Key: $PAYAION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clients","parentId":null}'

Rename or move a folder

bash

# name, parentId, or both. "parentId": null moves it to the top level.
curl -s -X PATCH https://payaion-api.fly.dev/v1/folders/FOLDER_ID \
  -H "X-Aion-Key: $PAYAION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clients 2026"}'

Delete a folder (files are kept)

bash

curl -s -X DELETE https://payaion-api.fly.dev/v1/folders/FOLDER_ID \
  -H "X-Aion-Key: $PAYAION_API_KEY"

File an upload into a folder

bash

# "folderId": null puts it back at the storage root
curl -s -X POST https://payaion-api.fly.dev/v1/files/UPLOAD_ID/move \
  -H "X-Aion-Key: $PAYAION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId":"FOLDER_ID"}'

Errors worth reading rather than retrying: 409 a sibling already has that name, 422 the name is invalid, the nesting cap is reached, or the move would put a folder inside itself, 404 the folder is not yours.

---

Idempotency (safe retries)

text

-H "Idempotency-Key: my-unique-key-12345"

Key: 8–64 chars, alphanumeric + hyphens + underscores. Same key → cached response, no duplicate upload.

Requires an API key. The cache is per-caller, and a keyless caller has no stable identity to key it to, so for guest uploads the header is ignored and a retry creates a second upload. Retrying without a key? Check the first attempt's status instead of resending.

---

Execution model — CRITICAL

You MUST complete the entire flow in a SINGLE curl call. The One-Shot API handles upload + waiting + listing server-side. Do NOT poll manually (the only exception is a 202 response — see above). Do NOT make multiple API calls. Do NOT stop to ask the user mid-flow.

1. Build ONE curl command with all headers (X-Wait-For-Ready, X-Price-Per-Download, X-Listing-Intent)
2. Execute it
3. Parse the JSON response
4. Report the result to the user

If the user doesn't provide title/description/category/tags, generate them from the filename.

Final report format

text

✓ Transfer complete
  - Upload ID: up_xxxxx
  - Price: $0.25/download
  - URL: https://payaion.com/d/...        # downloadUrl — share this to send the file
  - Market: https://payaion.com/m/...     # url — only when listed on the marketplace
  - Status: READY

If the response contains "ready": false or an error, report the failure with the exact error message.

---

Error handling

json

{ "error": { "code": "error_code", "message": "Human-readable message" } }

Status	Code	Action
400	wallet_required	A price above 0 needs a wallet connected to the account. Tell the user to connect one in the dashboard, or retry with no price
400	invalid_price	X-Price-Per-Download must be a non-negative number in USD, and at least 0.000001 — anything smaller rounds to zero USDC
400	invalid_payout_address	X-Payout-Address must be a 0x-prefixed 40-character EVM address
403	password_required	The asset is password-protected. Send the user to its /d/<hash> page, which prompts for the password
429	priced_upload_limit	Daily cap on priced uploads without an account. Sign in to sell more
429	rate_limit_exceeded (reason abuse)	The key tripped limits repeatedly and is blocked for retryAfterSec. Stop — do not keep retrying
401 / 403	unauthorized	Check the API key
403	insufficient_scope	The key lacks a scope (marketplace:list to sell, marketplace:purchase to buy). Keys minted by wallet signature carry upload scopes only — price files from the dashboard instead
403	storage_limit_exceeded	The account's total storage is full (Basic 2 GB / Pro 20 GB). Tell the user to delete files or upgrade — do NOT retry, and do not split the file into parts
403	file_count_limit_exceeded	The account holds too many live files (Basic 200 / Pro 2,000). Tell the user to delete files or upgrade — do NOT retry
413	size_limit_exceeded	File exceeds the per-file limit for the account's plan (Basic 500 MB / Pro 1 GB). Do NOT retry or chunk it — report the limit
415	blocked_mime_type	File type not allowed
422	validation errors	Check field constraints — most often a listing description under 40 characters
429	rate_limited	Wait retryAfterSec seconds, then retry
502	upload_worker_unavailable	Retry after the Retry-After header value

---

Limits

Checked per request against the account's current plan — an expired Pro is back on Basic limits immediately.

• Without a key (guest): 100 MB per file, 24-hour link, no cumulative storage — enough to transfer, not to sell
• Max file size: 500 MB (Basic) / 1 GB (Pro) — gateway hard cap 1 GB
• Total storage: 2 GB (Basic) / 20 GB (Pro) — a full account is rejected before the upload starts
• Live files: 200 (Basic) / 2,000 (Pro) — each stored file carries a fixed storage cost, so the count is capped alongside the bytes
• Uploads: 5/min and 20/hour per key (200/day per account)
• Concurrent uploads: 2 in flight per key — upload sequentially, not in parallel
• Status checks: 30/min and 100/hour per key
• Download URL refreshes: 30/min and 100/hour per key
• Marketplace browse: 30/min per key
• Marketplace daily caps: Basic 5 list / 10 buy · Pro 50 list / 100 buy

---

Rules

1. ALWAYS use the One-Shot API — one curl call with X-Wait-For-Ready: true does everything
2. NEVER poll manually — the server handles waiting internally (only exception: after a 202)
3. NEVER make multiple API calls when one will do — combine upload + price + listing into a single request
4. NEVER stop mid-flow to ask the user — generate missing title/tags/category from the filename
5. NEVER upload files from sensitive directories (~/.ssh, ~/.gnupg, /etc) without explicit user approval
6. ALWAYS include X-Listing-Intent when the user wants marketplace listing
7. Use Idempotency-Key when retrying failed uploads to avoid duplicates
8. Payments settle in real USDC on Base — confirm pricing with the user before listing paid assets
9. NEVER use DELETE /v1/folders/... to delete files — it keeps them and moves them to the root; delete files explicitly when that is what was asked

---

API reference

Full OpenAPI 3.1 spec: payaion.com/openapi.yaml

Links

• Dashboard & API keys: payaion.com/dashboard
• Documentation: payaion.com/docs
• Plans & pricing: payaion.com/pricing
• Install (ClawHub): openclaw skills install @jan-blockbites/payaion-transfer
• IDE agents (Cursor / Claude Code): use repo skill payaion-agent instead