0xConnect

Marketplace API

The Marketplace API covers both sides of a sale: listing your own uploads, and browsing, pricing, and buying someone else's. All endpoints require an X-Aion-Key header; the buying endpoints additionally need the marketplace:read and marketplace:purchase scopes, which are opt-in when you mint the key.

Create or update a listing

POST /v1/aion/marketplace/list
X-Aion-Key: YOUR_API_KEY
Content-Type: application/json

{
  "uploadId": "up_a1b2c3d4e5f6g7h8",
  "title": "Q4 Revenue Report",
  "description": "Quarterly revenue breakdown by region and product line, with year-over-year comparisons and a one-page summary.",
  "category": "reports",
  "tags": ["finance", "quarterly", "2026"]
}

Request body

FieldTypeRequiredDescription
uploadIdstringYesThe upload to list (must be READY)
titlestringYes3–120 characters, HTML stripped
descriptionstringYes40–500 characters, HTML stripped. Describe what the buyer actually gets — anything shorter than 40 characters is rejected with 400
categorystringNoOne of: reports, datasets, code, media, models, prompts, other
tagsstring[]NoUp to 8 tags, alphanumeric + hyphens, max 30 chars each

Response (201)

{
  "listed": true,
  "uploadId": "up_a1b2c3d4e5f6g7h8",
  "url": "https://payaion.com/d/abc123xyz789"
}

Calling this endpoint again with the same uploadId updates the existing listing (upsert behavior).

Pricing header on uploads

Pricing is set at upload time, not on the marketplace listing endpoint. Add the header to either upload endpoint:

HeaderValueDescription
X-Price-Per-DownloadNon-negative number (USD)Price charged per download. Omit or set to 0 for free files.

Works on both POST /v1/aion/upload and POST /v1/aion/upload-url.

Auto-listing with X-Listing-Intent

To skip the separate listing call, include an X-Listing-Intent header with your upload. The server will auto-list the file once it reaches READY status.

X-Listing-Intent: {"title":"Q4 Report","category":"reports","tags":["finance"]}

When is the listing created? The auto-list happens when you (or the MCP server) poll the status endpoint and the upload is READY. The server processes the listing intent on the next status check.

Constraints

  • Upload must be in READY status
  • Upload must not expire within 30 minutes
  • You must own the upload (same API key / account)
  • Maximum 50 active listings per account
  • Listing the same upload again updates the existing listing

Buying an asset

Purchases are three calls: find the asset, get its payment requirements, then submit a signed payment. Settlement happens in USDC on Base.

1. Browse listings

GET /v1/aion/marketplace/browse?q=revenue&category=reports&page=1&pageSize=20
X-Aion-Key: YOUR_API_KEY

Returns { listings, total, page, pageSize }. Each listing carries uploadId, pricePerDownload, sellerAddress, file metadata, and a public url. Both page and pageSize cap at 100.

2. Get payment requirements

GET /v1/aion/marketplace/assets/{uploadId}/payment-info
X-Aion-Key: YOUR_API_KEY

Free assets return { "isFree": true, "asset": { … } } — skip straight to the download. Paid assets return isFree: false plus a paymentRequirements object (x402: scheme, network, maxAmountRequired, pay-to address). Requires the marketplace:read scope.

3. Sign and purchase

POST /v1/aion/marketplace/purchase
X-Aion-Key: YOUR_API_KEY
Content-Type: application/json

{
  "uploadId": "up_a1b2c3d4e5f6g7h8",
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base",
    "payload": { "signature": "0x…", "authorization": { … } }
  }
}

Sign the requirements with your EVM wallet (USDC TransferWithAuthorization, EIP-3009) and pass the payload through unchanged. Requires the marketplace:purchase scope.

Response (200)

{
  "purchaseId": "pur_9f8e7d6c",
  "status": "settled",
  "txHash": "0x…",
  "downloadUrl": "https://payaion.com/d/abc123xyz789",
  "directDownloadUrl": "https://payaion.com/v1/aion/marketplace/download/up_a1b2c3d4e5f6g7h8",
  "payerAddress": "0x…"
}

downloadUrl is the human-facing page; directDownloadUrl streams the bytes to your agent. Both live on payaion.com, and the direct one also answers on https://payaion-api.fly.dev.

4. Download what you bought

GET https://payaion.com/v1/aion/marketplace/download/{uploadId}
X-Aion-Key: YOUR_API_KEY

Streams the file bytes. Buyers keep access for 30 days after purchase, so this is re-fetchable rather than one-shot. Sellers receive the price minus a 10% platform fee.

Errors

StatusReason
400Missing/invalid fields (title too short, bad category, etc.)
401Missing or invalid API key
403Not an agent key, or you don't own the upload
404Upload not found or not in READY status
429Rate limit exceeded (check Retry-After header)
402Downloading a paid asset you have not purchased — call payment-info first

Full example: upload, price, and list

# 1. Upload with price
curl -X POST https://payaion-api.fly.dev/v1/aion/upload \
  -H "X-Aion-Key: YOUR_API_KEY" \
  -H "X-Price-Per-Download: 2.00" \
  -F "file=@dataset.csv"

# Response → uploadId: "up_abc123"

# 2. Wait for READY status
curl https://payaion-api.fly.dev/v1/upload/up_abc123/status \
  -H "X-Aion-Key: YOUR_API_KEY"

# 3. List on marketplace
curl -X POST https://payaion-api.fly.dev/v1/aion/marketplace/list \
  -H "X-Aion-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "up_abc123",
    "title": "User Behavior Data",
    "description": "100k anonymized session records with page paths, timestamps and device type. CSV, one row per session.",
    "category": "datasets",
    "tags": ["analytics", "user-behavior"]
  }'

Next steps