开发者接入路径

在任意 AI 渠道里接住购物意图

SellToAI 是商家进入 AI 场域的桥。把下面对应你 Agent 宿主的 SDK / SKILL / MCP / OpenAPI 片段复制进去，SellToAI 就会把每一句购物对话翻译成结构化 intent，让你的店用真实 offer 回答——不是链接。生产环境调用 `/v1/*` 时，去开发者控制台创建 Bearer API key。

先看效果 在用户试玩页跑一遍 一句话需求 → /v1/recommend → 排序卡片 + 归因链接，30 秒看完链路。打开 /try → 拿一把 key 在控制台创建 Bearer API key 注册、验证邀请码、生成生产环境调用 /v1/* 用的 key。打开 /developers → 看协议 直读 OpenAPI / Agent Card / SKILL 四种协议接入面整页排开 — 选你的栈已经会讲的那一种。打开 /reference →

还没安装或配置这些宿主？先看官方文档：

OpenClaw 安装 Hermes 安装下载 Cursor Claude Code 设置 Codex CLI 文档 Claude Desktop MCP ChatGPT Actions Gemini 函数调用

先选最适合你渠道的接法

大多数团队只需要先接一层。先选你已经在用的宿主或协议，复制第一段即可；只有在需要 merchant-side negotiation 时，再往更深的 workflow 走。

Skill 宿主

适合 Cursor、Claude Code 的技能目录。OpenClaw 与 Hermes 在「本地 Agent 宿主」分区；每张卡片都先给出安装命令。

打开 Skill 宿主

OpenAPI 应用

适合 ChatGPT 和 Gemini。贴一个 manifest URL，就能在托管工具体系里直接调用网关。

打开 OpenAPI 应用

MCP 宿主

适合 Codex 和 Claude Desktop。加一段 `mcpServers` 配置，就能把 SellToAI 当本地工具调用。

打开 MCP 配置

Hermes / A2A 客户端

Hermes 与 OpenClaw 同在「本地 Agent 宿主」分区。若只需要原始 REST，完成宿主配置后可跳到文末「Anything else」。

打开 Hermes / A2A 流程

通用入口

这一页所有渠道化指南，背后共用的都是下面这些入口。

OpenAPI manifest

https://selltoai.ai/openapi.json

A2A Agent Card

https://selltoai.ai/.well-known/agent-card.json

Skill 安装脚本

https://selltoai.ai/skills/install.sh

REST 基址

https://selltoai.ai/v1

本地 Agent 宿主（OpenClaw · Hermes）

OpenClaw

一行 curl 把 SellToAI Shop 技能丢进 OpenClaw。新会话即用。

协议

SKILL

可直接复制的片段

先安装 OpenClaw（一键）

来自 openclaw.ai 的官方安装脚本。若已能运行 `openclaw --version` 可跳过。

curl -fsSL https://openclaw.ai/install.sh | bash

# Already have Node 22+? Alternative:
# npm install -g openclaw@latest

安装技能（一行命令）

会把 SKILL.md 装到各 Agent 技能目录（含 OpenClaw / Cursor / Claude / Codex）。`curl … | bash` 在 fish、zsh、bash 下均可使用。

curl -fsSL https://selltoai.ai/skills/install.sh | bash

或手动复制技能文件

如果团队不允许把 curl 直接管道给 bash，把文件存到技能目录即可。

mkdir -p ~/.openclaw/skills/moras-shop && \
  curl -fsSL https://selltoai.ai/skills/moras-shop/SKILL.md \
  -o ~/.openclaw/skills/moras-shop/SKILL.md

验证可用

在 OpenClaw 里开一段新对话，试试下面的 prompt。第一次显式点名技能来强制激活；后续购物类 prompt 应该会自动触发。

use the moras-shop skill: recommend a small birthday gift for a 5 year old kid

Hermes

与 OpenClaw「丢一份 SKILL.md」不同，Hermes 走 A2A：用 Agent Card URL 把 SellToAI 登记为远程 Agent，再调 message/send 并在 metadata 里带 skill_id；若不想接 JSON-RPC，也可像普通 HTTP 客户端一样直接 GET /v1/recommend。

协议

A2ASSE

可直接复制的片段

先安装 Hermes Agent（一键）

NousResearch 官方一键脚本。若 `hermes --version` 已可用可跳过。Windows 请用 WSL2。

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

在 Hermes 里启用 SellToAI（不是装 SKILL 文件）

下面的 curl 用来验收协议。Hermes 侧请把「Agent Card URL」配成远程 A2A Agent 的发现地址（菜单位置以 NousResearch 文档为准），运行时就能读到 skill id；之后由你的编排/CLI 发与 curl 相同的 JSON-RPC。

1) Register — In Hermes (or your CrewAI / AutoGen / LangGraph setup), add the Agent Card URL below as the Moras agent discovery endpoint. Exact setting name is in NousResearch docs; it is not a file path like ~/.openclaw/skills/.

2) Discover — Hermes fetches the JSON; shopping uses skill_id "recommend_products" (see "skills" in that file).

3) Invoke — POST https://selltoai.ai/a2a with jsonrpc "message/send" and message.metadata.skill_id (example in the next block). For async tasks, poll SSE as in the final block.

Shortcut — Same gateway: GET https://selltoai.ai/v1/recommend?intent=...&channel=hermes (no JSON-RPC).

Agent Card URL（发现入口）

https://selltoai.ai/.well-known/agent-card.json

启动异步推荐任务（JSON-RPC 2.0）

它和 /v1/recommend 走的是同一条 recommend_products 主链路，只是通过 A2A task runtime 触发。

curl -X POST https://selltoai.ai/a2a \
  -H "Content-Type: application/json" \
  -H "X-Channel: hermes" \
  -d '{
    "jsonrpc":"2.0",
    "id":"req-1",
    "method":"message/send",
    "params":{
      "message":{
        "role":"user",
        "parts":[{"kind":"text","text":"recommend a small birthday gift for a 5 year old kid"}],
        "metadata":{"skill_id":"recommend_products","async":true,"limit":3}
      }
    }
  }'

通过 SSE 订阅 task 事件

把 TASK_ID 替换成 message/send 返回的 task id。

curl -N https://selltoai.ai/a2a/tasks/TASK_ID/events

Skill 宿主

Cursor

Cursor 从 ~/.cursor/skills 加载 Agent 技能。与 OpenClaw 使用同一行命令。

协议

SKILL

可直接复制的片段

安装技能

与 OpenClaw 区块相同的一键脚本，会写入所有已支持 Agent 的技能目录。

curl -fsSL https://selltoai.ai/skills/install.sh | bash

在对话框里试一下

> use the moras-shop skill — find me a portable blender

Claude Code

Claude Code 技能位于 ~/.claude/skills。相同安装脚本，目标目录不同。

协议

SKILL

可直接复制的片段

安装技能

与 OpenClaw 区块相同的一键脚本，会写入所有已支持 Agent 的技能目录。

curl -fsSL https://selltoai.ai/skills/install.sh | bash

试一下

recommend trending pet products on TikTok Shop

OpenAPI 应用

ChatGPT (Apps SDK / Custom GPT)

ChatGPT 直接吃 OpenAPI 3.0 manifest。把这个 URL 贴进 Custom GPT 或 Apps SDK 配置后，再配置 Bearer auth。

协议

OPENAPIREST

可直接复制的片段

OpenAPI manifest URL

在 ChatGPT → Configure → Actions → Import from URL 里粘贴。

https://selltoai.ai/openapi.json

鉴权

/v1/* 调用使用 Bearer 鉴权。先在开发者控制台创建 key，再配置到 Action 的 auth settings。

Authentication type: API Key
Auth type: Bearer
Header: Authorization: Bearer MA2A.xxx

建议的 system instructions

When the user asks for a product recommendation, gift idea, or "what should I buy",
call recommendProducts with the user's intent paraphrased into one short English line.
Return each card's cta.primary.url verbatim — never rewrite the buy link.

Gemini Extension

Gemini Extension / Gems 也支持 OpenAPI。同一个 manifest URL；受保护的 /v1/* 调用配置 Bearer auth。

协议

OPENAPIREST

可直接复制的片段

OpenAPI manifest URL

https://selltoai.ai/openapi.json

在 Gemini AI Studio 里测试

Tools → Function Calling → Import OpenAPI → 粘贴上面的 URL。

recommend a small birthday gift for a 5 year old

MCP 宿主

Codex / Claude Desktop (MCP)

Codex 和 Claude Desktop 可以把 SellToAI MCP 包装当作 stdio 子进程拉起。把下面这段加到 MCP 配置里。

协议

MCP

可直接复制的片段

mcpServers 配置项

加到 ~/.codex/config.json 或 claude_desktop_config.json 的 "mcpServers" 段。

{
  "mcpServers": {
    "moras-shop": {
      "command": "npx",
      "args": ["-y", "moras-a2a-mcp@latest"],
      "env": {
        "MORAS_A2A_BASE_URL": "https://selltoai.ai",
        "MORAS_A2A_CHANNEL": "codex"
      }
    }
  }
}

或者从克隆的仓库里直接跑

Use your own deployment path instead of a public clone URL.

cd /path/to/moras-A2A && npm install
MORAS_A2A_BASE_URL=https://selltoai.ai node bin/mcp.js

原生 Workflow

Anything else (raw REST)

可以直接调 REST：既覆盖买方 discovery，也覆盖商家侧的 exchange 对象。

协议

RESTA2A

可直接复制的片段

按意图推荐

curl 'https://selltoai.ai/v1/recommend?intent=birthday%20gift%20for%205%20year%20old&limit=3' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: my-agent'

创建开发者账号

登录后验证邀请码，再在开发者控制台创建 API key。

curl -X POST https://selltoai.ai/v1/developers/register \
  -H 'Content-Type: application/json' \
  -d '{"display_name":"My Agent","contact_email":"[email protected]","password":"change-me-now","company":"Example Labs"}'

查看 keys 与请求日志

curl https://selltoai.ai/v1/developers/me \
  -H 'Authorization: Bearer moras_dev_xxx'

curl 'https://selltoai.ai/v1/developers/logs?limit=20' \
  -H 'Authorization: Bearer moras_dev_xxx'

创建一等 Intent

curl -X POST https://selltoai.ai/v1/intents \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: my-agent' \
  -d '{"raw_query":"birthday gift for a 5 year old","region":"US","audience":"parent","budget_range":{"max":35,"currency":"USD"}}'

保存返回的 registration_token；后续 heartbeat、更新和提交 proposal 都要用到它。

curl -X POST https://selltoai.ai/v1/merchant/register \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: merchant-onboarding' \
  -d '{"merchant_id":"mch_demo","agent_endpoint":"https://example.com/webhook","subscription_tags":["outdoor"],"capabilities":["stock_check"],"regions":["US"]}'

注册任意 Commerce Agent

通用 Registry 覆盖 payment、logistics、creator、demand-side、merchant 和 SellToAI-core Agent。

curl -X POST https://selltoai.ai/v1/agents/register \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: agent-registry' \
  -d '{"agent_id":"payment_demo","agent_type":"payment","endpoint":"https://example.com/a2a","protocols":["a2a-jsonrpc","webhook"],"auth_methods":["intent_mandate"],"capability_profile":{"payment":{"create_checkout":true}}}'

列出已注册 Commerce Agents

curl 'https://selltoai.ai/v1/agents?agent_type=payment&status=active' \
  -H 'Authorization: Bearer MA2A.xxx'

提交 Merchant Proposal

需要携带注册时返回的 X-Merchant-Token。

curl -X POST https://selltoai.ai/v1/proposals \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Merchant-Token: mrt_xxx' \
  -d '{"merchant_agent_id":"mch_demo","intent_id":"int_xxx","product_id":"123456789","offer_title":"Trail-ready lantern bundle","price":29.99,"inventory_status":"in_stock","shipping_commitment":{"eta_days":3}}'

用 intent + proposals 创建 Match Session

curl -X POST https://selltoai.ai/v1/match \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: my-agent' \
  -d '{"intent_id":"int_xxx","proposal_ids":["prp_xxx","prp_yyy"],"limit":3}'

运行 Commerce Runtime loop

一次可审计调用创建关联的 Intent、Proposal、Match Session、Match Token 和 runtime_trace。

curl -X POST https://selltoai.ai/v1/commerce-runtime \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ***' \
  -H 'X-Channel: my-agent' \
  -d '{"runtime_session":{"entry_agent_id":"my-agent","mode":"assisted_commerce"},"commerce_budget":{"max_merchant_queries":3,"require_user_confirmation_before_payment":true},"skill_refs":["enterprise_gifting_sop"],"intent":{"raw_query":"birthday gift for a 5 year old","region":"US","audience":"parent"},"proposal":{"merchant_agent_id":"moras-core","product_id":"demo-gift","offer_title":"Curated birthday gift bundle","price":29.99}}'

接受 Proposal 并铸造 Match Token

Turns buyer-agent intent into a signed intent → merchant proposal → MatchToken → confirmation transaction plan. This is transaction protocol, not sponsored placement.

curl -X POST https://selltoai.ai/v1/agentic-checkout \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ***' \
  -H 'X-Channel: my-agent' \
  -d '{"buyer_agent_id":"gpt-shopper-agent","raw_query":"birthday gift for a 3 year old nephew under $40","region":"US","commerce_budget":{"max":40,"currency":"USD"},"proposal":{"merchant_agent_id":"toy-merchant-agent","product_id":101,"title":"Montessori Wooden Animal Puzzle","price":28.5,"currency":"USD","checkout_url":"https://merchant.example/checkout/puzzle-101","commission_plan":{"type":"success_fee","rate_bps":1200,"currency":"USD"}}}'

按 id 获取 Match Token

Requires explicit consent, verifies the signed MatchToken, proposal id, amount and currency, then returns a merchant handoff with transaction proof and settlement evidence.

curl -X POST https://selltoai.ai/v1/agentic-checkout/chk_xxx/confirm \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ***' \
  -H 'X-Channel: my-agent' \
  -d '{"match_token_id":"mtk_xxx","proposal_id":"prp_xxx","expected_amount":28.5,"currency":"USD","buyer_confirmation":{"confirmed_by":"gpt-shopper-agent","consent":true,"user_visible_summary":"Buy Montessori Wooden Animal Puzzle for $28.50."}}'

记录体验决策事件

当买家或用户 Agent pick、reject、remix、confirm 或查看体验预览后调用。

curl -X POST https://selltoai.ai/v1/match/mch_xxx/accept \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: my-agent' \
  -d '{"proposal_id":"prp_xxx"}'

准备主动体验 Feed

基于 taste signals 和 inspiration refs 返回 ready-to-experience proposal shells。

curl https://selltoai.ai/v1/match-tokens/mtk_xxx \
  -H 'Authorization: Bearer MA2A.xxx'

签发 Intent Mandate

仅在 SellToAI 已为你的集成开通凭证签发能力后使用；适用于有额度边界的 checkout/payment 授权链路。

curl -X POST https://selltoai.ai/v1/decision-events \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: my-agent' \
  -d '{"event_type":"proposal.remixed","intent_id":"int_xxx","proposal_id":"prp_xxx","action":"change_color","from":"black","to":"cream","reason":"prefers warm minimalist tone","actor_agent_id":"user-agent"}'

按 recId 查卡

Returns ready-to-experience proposal shells from taste signals and inspiration references.

curl -X POST https://selltoai.ai/v1/experience-feed \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -H 'X-Channel: my-agent' \
  -d '{"agent_id":"user-agent","taste_profile":{"visual_preferences":["warm minimalist","cream palette"],"negative_preferences":["glossy plastic"]},"inspiration_refs":[{"source":"pinterest","url":"https://example.test/pin/1","scene":"small apartment"}],"limit":3}'

获取达人 showcase

Use only after Moras has enabled mandate signing for your integration. Designed for bounded checkout/payment authorization flows.

curl -X POST https://selltoai.ai/v1/intent-mandates/sign \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer MA2A.xxx' \
  -d '{"product_id":"3003","amount_limit":129.99}'

提示 — 带上 X-Channel 用于归因

给你的 Agent 起个短 slug 即可。带 channel-key 时配额 5 倍，不带也能正常用 1 倍。

curl https://selltoai.ai/v1/cards/rec_xxxxxxxx \
  -H 'Authorization: Bearer MA2A.xxx'

Fetch a creator showcase

curl 'https://selltoai.ai/v1/creators/eva_creator/showcase?limit=6' \
  -H 'Authorization: Bearer MA2A.xxx'

Tip — set X-Channel for attribution

Pick any short slug for your agent. Channel-tagged traffic gets a 5× rate-limit if you ask for a key, otherwise 1× still works.

X-Channel: <your-agent-slug>