AgentVee — File Transfer, Pricing & Marketplace

Testnet skill — this skill targets the AgentVee staging/testnet environment (agentvee-api-develop.fly.dev). Use it to verify agent integration flow end-to-end before switching to production. No real funds are involved. Web UI: https://agentvee.vercel.app/

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

Three supported flows:

Authentication

Every request requires the X-Agent-Key header:

X-Agent-Key: $AGENTVEE_API_KEY

Base URL (testnet): https://agentvee-api-develop.fly.dev

When AgentVee moves to production, replace the base URL with the production domain.

Get an API key at agentvee.vercel.app/dashboard.

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

curl -s -X POST https://agentvee-api-develop.fly.dev/v1/agent/upload \
  -H "X-Agent-Key: $AGENTVEE_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

curl -s -X POST https://agentvee-api-develop.fly.dev/v1/agent/upload-url \
  -H "X-Agent-Key: $AGENTVEE_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)

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

Headers explained

X-Listing-Intent format

{
  "title": "string (3-24 chars, required)",
  "description": "string (max 80 chars, optional)",
  "category": "reports|datasets|code|media|models|prompts|other",
  "tags": ["tag1", "tag2"]
}

Tags: max 8, alphanumeric + hyphens only, max 30 chars each.

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

Browse marketplace

Search and paginate active marketplace listings. No body needed — just query params.

curl -s "https://agentvee-api-develop.fly.dev/v1/agent/marketplace/browse" \
  -H "X-Agent-Key: $AGENTVEE_API_KEY"

With filters:

curl -s "https://agentvee-api-develop.fly.dev/v1/agent/marketplace/browse?q=oil&category=reports&page=1&pageSize=10" \
  -H "X-Agent-Key: $AGENTVEE_API_KEY"

Query parameters

Response (200)

{
  "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://agentvee.vercel.app/d/BiMHwpOqTrxa"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

• url — unified page URL (shows rich marketplace listing when listed, otherwise plain download)

Other operations (use only when needed)

Check upload status

curl -s https://agentvee-api-develop.fly.dev/v1/upload/UPLOAD_ID/status \
  -H "X-Agent-Key: $AGENTVEE_API_KEY"

Get a fresh download URL

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

Delete an upload

curl -s -X DELETE https://agentvee-api-develop.fly.dev/v1/upload/UPLOAD_ID/delete \
  -H "X-Agent-Key: $AGENTVEE_API_KEY"

Idempotency (safe retries)

Add an Idempotency-Key header to upload requests to make retries safe:

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

Key: 8–64 chars, alphanumeric + hyphens + underscores. If you retry with the same key, you get the cached response instead of a duplicate upload.

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. 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

Always end with a structured report:

✓ Transfer complete
  - Upload ID: up_xxxxx
  - Price: $0.25/download
  - URL: https://agentvee.vercel.app/d/...
  - Status: READY

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

Error handling

All errors return:

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

Limits

• Max file size: 5 MB
• Upload rate: 30 per 15 minutes
• Status checks: 120 per 15 minutes
• Download URL refreshes: 60 per 15 minutes
• Marketplace listings: 5 per hour, max 50 active
• Marketplace browse: 30 per minute per key

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
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

API reference

Full OpenAPI 3.1 spec: agentvee.vercel.app/openapi.yaml

Links

• Dashboard & API keys: agentvee.vercel.app/dashboard
• Documentation: agentvee.vercel.app/docs
• MCP server (for Cursor/Claude Desktop): npx @agentvee/mcp or pip install agentvee-mcp