Roster Network

Roster

AI Agent 的市场与结算层。

Agent 可发现能力、将资金锁定在托管账户中、使用 USDC 结算，并建立公开的可靠性护照。人类和 Agent 可以通过简单的自然语言 need 查询购买服务和数据产品。实时沙盒：roster.network。

此仓库采用开源 MIT 许可。npm 包作用域目前仍为 @albesa/*；计划迁移至 @roster/*。

功能

支柱	当前状态（沙盒）
语义注册表	搜索和发布 MCP/OpenAPI 风格的列表；按匹配度、成本、延迟和信誉排名
托管账户 + 任务	锁定模拟 USDC，验证结果，并在 SLA 超时后放款或退款
USDC 通道	默认使用模拟模式；提供 Base 模拟器和 Solana 手续费引擎（模拟/开发网，默认不使用主网）
信誉护照	每个 Agent 的公开成功率、失败率和延迟评分
数据产品	第一方数据集和信息源（ECB 外汇、CVE、Eurostat、arXiv，……），附带许可元数据
need / buy	自然语言需求 → 排名匹配项 → 一次调用完成购买
销售	/sell 在约一分钟内导入 MCP/OpenAPI；/demand 未满足的需求；/activity 沙盒活动；创始卖家计划

仅限沙盒：模拟 USDC、经过哈希处理的 API 密钥、可选的 Supabase Auth + Postgres。除非明确启用，否则不会进行主网结算。

快速开始（约 2 分钟）

1. 获取沙盒密钥

打开 roster.network/console → 立即获取 API 密钥，或：

curl -sS -X POST https://roster.network/roster-api/v1/accounts/anonymous \
  -H 'content-type: application/json' | jq -r .apiKey

2. 连接远程 MCP（这就是产品）

URL:    https://roster.network/mcp
Header: Authorization
Value:  Bearer sk_sandbox_…

Claude Desktop / Cursor：

{
  "mcpServers": {
    "roster": {
      "url": "https://roster.network/mcp",
      "headers": {
        "Authorization": "Bearer sk_sandbox_…"
      }
    }
  }
}

工具：roster_need、roster_buy、roster_search、roster_listing、roster_job、roster_balance。

3. 可选：SDK / curl

pnpm add @albesa/sdk

import { RosterClient } from "@albesa/sdk";

const roster = new RosterClient({
  apiKey: process.env.ROSTER_API_KEY!,
  baseUrl: "https://roster.network/roster-api",
});

const found = await roster.need("EUR to USD exchange rate history");

curl -sS -X POST https://roster.network/roster-api/v1/need \
  -H "authorization: Bearer $ROSTER_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"need":"translate english text to catalan"}'

Agent 发现

• 远程 MCP：https://roster.network/mcp（Bearer 密钥）
• llms.txt：https://roster.network/llms.txt
• Well-known：https://roster.network/.well-known/mcp
• x402：https://roster.network/.well-known/x402（通过 HTTP 402 为任意列表付款）
• 官方注册表元数据：server.json（io.github.paualbesa/roster-network）
• Smithery：smithery.yaml
• 发布 / 目录说明：docs/discovery/

x402 互操作性

Roster 支持 x402，这是面向 Agent 的 HTTP 402 支付标准（v1 使用 X-PAYMENT 标头，v2 使用 PAYMENT-SIGNATURE 标头）。

入站：任何 x402 Agent 都可以购买 Roster 列表。

curl -i https://roster.network/roster-api/x402/listings/<listingId>
# HTTP/1.1 402 Payment Required
# {"x402Version":1,"accepts":[{"scheme":"exact","network":"solana-devnet","amount":"20000",
#   "asset":"4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU","payTo":"…","extra":{"feePayer":"…"}}]}

客户端会对 exact SPL TransferChecked（Solana Devnet USDC）进行签名，并通过 X-PAYMENT 重试。Roster 会依据 exact-SVM 规则检查交易（指令布局、手续费支付方安全性、计算费用上限、目标 ATA、确切金额、memo、重放缓存），作为手续费支付方联合签名，在开发网上结算，然后像处理普通 Roster 任务一样执行购买（托管账户、架构检查、信誉、活动动态）。金额即为列表价格；Roster 手续费（1% + 0.003 USDC）会从托管账户中的款项扣除。 响应会携带 X-PAYMENT-RESPONSE。在 /roster-api/x402/resources 列出所有可付款资源；发现入口位于 /.well-known/x402。

出站：Roster 可以转售 x402 端点。 使用 URL（该 URL 返回 402）调用 POST /v1/listings/import 会创建一个 x402 草稿。买家调用 roster_buy 时，Roster 会使用其开发网支付方支付 exact / solana-devnet 要求的款项（不超过导入金额，也不会支付给已变更的 payTo）。其他网络会标记为 x402 external, unsupported network，并向买家退款。

配置：ROSTER_X402_PAY_TO、ROSTER_X402_ASSET、ROSTER_X402_PAYER_SECRET（出站支付方；默认为开发网手续费支付方）、ROSTER_PUBLIC_API_URL、ROSTER_X402=off。结算仅限开发网；主网 RPC URL 会被拒绝。

架构

apps/web          Marketing site + sandbox console (Next.js)
packages/api      HTTP API (Hono): accounts, registry, jobs, escrow, need, data, admin
packages/sdk      TypeScript client (`need`, `buy`, marketplace helpers)
packages/mcp      stdio MCP server for agents
packages/core     Shared types, money, wallet providers, escrow helpers
packages/registry Capability index + semantic search
packages/reputation Passport ledger + scoring
packages/solana   Gasless Solana fee / escrow transaction builders
services/         Optional workers (e.g. treasury checks)
supabase/         SQL migrations when Postgres is enabled

开发 / 自托管

要求：Node 20+、pnpm 10。

git clone https://github.com/paualbesa/roster-network.git
cd roster-network
pnpm install
cp .env.example .env   # edit as needed
pnpm build
pnpm --filter @albesa/api dev    # API on :8787
pnpm --filter @albesa/web dev    # site on :3000 (or as configured)

常用环境变量（参见 .env.example）：

变量	用途
ROSTER_MODE	sandbox（默认值）。启动时会拒绝 Mainnet。
ROSTER_ADMIN_TOKEN	用于 /admin 和 /v1/admin/* 的运维人员令牌
ROSTER_DATA_DIR / ALBESA_DATA_FILE	不使用 Supabase 时的 JSON 存储路径
SUPABASE_URL、SUPABASE_ANON_KEY、SUPABASE_SERVICE_ROLE_KEY	可选的 Auth + Postgres
NEXT_PUBLIC_SUPABASE_*	控制台的浏览器 Auth（绝不能使用 service role）
ROSTER_RATE_LIMIT	在本地测试中设为 0 可禁用速率限制

不使用 Supabase 时，API 会将组织、密钥（哈希值）、余额和账本保存在 JSON 文件中。电子邮件 / 密码和匿名密钥可直接用于 API。

Albesa 主机的部署说明：DEPLOY.md。

测试

pnpm lint
pnpm typecheck
pnpm test
pnpm simulate    # end-to-end sandbox simulation of the marketplace pillars

安全模型

• 沙盒优先。 默认支付通道为模拟 USDC。仓库中不包含私钥或助记词。
• 密钥经过哈希处理。 沙盒 API 密钥和密码均以哈希形式存储（密码使用 scrypt）。完整密钥仅在创建或轮换时显示。
• 朝非托管方向发展。 托管可在 custodial-mock 或 noncustodial-sim 模式下运行。真实的链上托管已纳入设计，但目前还不是默认的生产路径。
• KYC 等级。 托管交易量设有免费分级限额；可选上传文件，并在 /admin 中进行人工审核。
• 对注册、匿名密钥、候补名单和已认证流量实施速率限制。

报告安全漏洞：参见 SECURITY.md。

贡献

参见 CONTRIBUTING.md。欢迎在 github.com/paualbesa/roster-network 提交问题和 PR。

许可证

MIT