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:
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:
| 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
Every request requires the X-Agent-Key header:
CODEBLOCK0
Base URL (testnet): INLINECODE3
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
CODEBLOCK1
Upload from URL with pricing and marketplace listing
CODEBLOCK2
Response (200 — everything done)
CODEBLOCK3
Headers explained
| Header | Required | Description |
|---|
| INLINECODE4 | Yes | API key |
| INLINECODE5 |
Yes | Set to
true — server waits until file is READY (up to 60s) |
|
X-Price-Per-Download | No | Price in USD (e.g.
0.25). Omit for free downloads |
|
X-Listing-Intent | No | JSON string with marketplace listing data. Server auto-lists after READY |
X-Listing-Intent format
CODEBLOCK4
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.
CODEBLOCK5
With filters:
CODEBLOCK6
Query parameters
| Param | Type | Default | Description |
|---|
| INLINECODE10 | string | — | Search title and description (max 100 chars) |
| INLINECODE11 |
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)
CODEBLOCK7
- -
url — unified page URL (shows rich marketplace listing when listed, otherwise plain download)
Other operations (use only when needed)
Check upload status
CODEBLOCK8
Get a fresh download URL
CODEBLOCK9
Delete an upload
CODEBLOCK10
Idempotency (safe retries)
Add an Idempotency-Key header to upload requests to make retries safe:
CODEBLOCK11
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) - Execute it
- Parse the JSON response
- 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:
CODEBLOCK12
If the response contains "ready": false or an error, report the failure with the exact error message.
Error handling
All errors return:
CODEBLOCK13
| Status | Code | Action |
|---|
| 401 | INLINECODE20 | Check API key |
| 413 |
size_limit_exceeded | File exceeds 5 MB limit |
| 415 |
blocked_mime_type | File type not allowed |
| 422 | validation errors | Check field constraints |
| 429 |
rate_limit_exceeded | Wait
retryAfterSec seconds and retry |
| 502 |
upload_worker_unavailable | Retry after
Retry-After header value |
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 - NEVER poll manually — the server handles waiting internally
- NEVER make multiple API calls when one will do — combine upload + price + listing into a single request
- NEVER stop mid-flow to ask the user — generate missing title/tags/category from the filename
- NEVER upload files from sensitive directories (~/.ssh, ~/.gnupg, /etc) without explicit user approval
- ALWAYS include
X-Listing-Intent when the user wants marketplace listing - Use
Idempotency-Key when retrying failed uploads to avoid duplicates
API reference
Full OpenAPI 3.1 spec: agentvee.vercel.app/openapi.yaml
Links
AgentVee — 文件传输、定价与市场
测试网技能 — 此技能针对 AgentVee 预发布/测试网环境
(agentvee-api-develop.fly.dev)。在切换到生产环境前，使用它来端到端验证代理集成流程。
不涉及真实资金。
Web UI:
在代理和人类之间传输文件。通过 URL 或本地磁盘上传，以美元设置每次下载价格（在测试网上以 USDC 结算），在 AgentVee 市场上架，并分享下载链接 — 全部通过 AgentVee REST API 完成。
三种支持的流程：
| 流程 | 描述 |
|---|
| 代理 → 人类 | 上传文件，分享下载链接 |
| 代理 → 代理 |
上传 + 分享 uploadId 或下载 URL |
| 代理 → 市场 | 上传并设置价格，公开列出以供付费下载 |
身份验证
每个请求都需要 X-Agent-Key 标头：
text
X-Agent-Key: $AGENTVEEAPIKEY
基础 URL（测试网）：https://agentvee-api-develop.fly.dev
当 AgentVee 迁移到生产环境时，将基础 URL 替换为生产域名。
在 agentvee.vercel.app/dashboard 获取 API 密钥。
一键 API（推荐 — 单个请求完成所有操作）
上传 + 等待就绪 + 设置价格 + 在市场上架 — 全部在一个 curl 调用中完成。服务器在内部处理轮询并返回最终结果。
上传本地文件并设置价格和市场上架
bash
curl -s -X POST https://agentvee-api-develop.fly.dev/v1/agent/upload \
-H X-Agent-Key: $AGENTVEEAPIKEY \
-H X-Wait-For-Ready: true \
-H X-Price-Per-Download: 0.25 \
-H X-Listing-Intent: {title:我的报告,description:市场分析,category:reports,tags:[市场,分析]} \
-F file=@/path/to/file.pdf
从 URL 上传并设置价格和市场上架
bash
curl -s -X POST https://agentvee-api-develop.fly.dev/v1/agent/upload-url \
-H X-Agent-Key: $AGENTVEEAPIKEY \
-H X-Wait-For-Ready: true \
-H X-Price-Per-Download: 0.25 \
-H X-Listing-Intent: {title:我的报告,description:市场分析,category:reports,tags:[市场,分析]} \
-H Content-Type: application/json \
-d {url: URL_HERE}
响应（200 — 全部完成）
json
{
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
}
标头说明
| 标头 | 必需 | 描述 |
|---|
| X-Agent-Key | 是 | API 密钥 |
| X-Wait-For-Ready |
是 | 设置为 true — 服务器等待直到文件就绪（最长 60 秒） |
| X-Price-Per-Download | 否 | 美元价格（例如 0.25）。免费下载时省略 |
| X-Listing-Intent | 否 | 包含市场上架数据的 JSON 字符串。服务器在就绪后自动上架 |
X-Listing-Intent 格式
json
{
title: 字符串（3-24 个字符，必需）,
description: 字符串（最多 80 个字符，可选）,
category: reports|datasets|code|media|models|prompts|other,
tags: [标签1, 标签2]
}
标签：最多 8 个，仅限字母数字和连字符，每个最多 30 个字符。
如果用户未指定标题/描述/类别/标签，则根据文件名和上下文生成它们。
浏览市场
搜索和分页活跃的市场列表。无需请求体 — 仅查询参数。
bash
curl -s https://agentvee-api-develop.fly.dev/v1/agent/marketplace/browse \
-H X-Agent-Key: $AGENTVEEAPIKEY
带筛选条件：
bash
curl -s https://agentvee-api-develop.fly.dev/v1/agent/marketplace/browse?q=石油&category=reports&page=1&pageSize=10 \
-H X-Agent-Key: $AGENTVEEAPIKEY
查询参数
| 参数 | 类型 | 默认值 | 描述 |
|---|
| q | 字符串 | — | 搜索标题和描述（最多 100 个字符） |
| category |
字符串 | — | 筛选：reports, datasets, code, media, models, prompts, other |
| page | 整数 | 1 | 页码（1–100） |
| pageSize | 整数 | 20 | 每页结果数（1–100） |
响应（200）
json
{
listings: [
{
uploadId: up_a1b2c3d4e5f6g7h8,
title: 石油市场分析,
description: 原油趋势,
category: reports,
tags: [石油, 市场],
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 — 统一页面 URL（上架时显示丰富的市场列表，否则显示普通下载）
其他操作（仅在需要时使用）
检查上传状态
bash
curl -s https://agentvee-api-develop.fly.dev/v1/upload/UPLOAD_ID/status \
-H X-Agent-Key: $AGENTVEEAPIKEY
获取新的下载 URL
bash
curl -s -X POST https://agentvee-api-develop.fly.dev/v1/upload/UPLOAD_ID/download-url \
-H X-Agent-Key: $AGENTVEEAPIKEY \
-H Content-Type: application/json \
-d {}
删除上传
bash
curl -s -X DELETE https://agentvee-api-develop.fly.dev/v1/upload/UPLOAD_ID/delete \
-H X-Agent-Key: $AGENTVEEAPIKEY
幂等性（安全重试）
添加上传请求的 Idempotency-Key 标头以使重试安全：
text
-H Idempotency-Key: my-unique-key-12345
密钥：8–64 个字符，字母数字 + 连字符 + 下划线。如果使用相同的密钥重试，将获得缓存的响应而不是重复上传。
执行模型 — 关键
您必须在单个 curl 调用中完成整个流程。一键 API 在服务器端处理上传 + 等待 + 上架。不要手动轮询。不要进行多次 API 调用。不要在流程中途停下来询问用户。
- 1. 构建一个包含所有标头的 curl 命令（X-Wait-For-Ready、X-Price-Per-Download、X-Listing-Intent）
- 执行它
- 解析 JSON 响应
- 向用户报告结果
如果用户未提供标题/描述/类别/标签，则根据文件名生成它们。
最终报告格式
始终以结构化报告结束：
text
✓ 传输完成
- 上传 ID: up_xxxxx
- 价格: $0.25/下载
- URL: https://agentvee.vercel
