GhostSwap

ghostswap-agents

适用于 GhostSwap 的官方多 LLM Agent 集成包——一个无需 KYC 的加密货币兑换引擎，支持 1,600 多种币种。

只需一行，即可将 GhostSwap Partners API 接入任何 AI Agent 或编码助手——Claude、ChatGPT、Cursor、Windsurf、Gemini、GitHub Copilot、Continue.dev、OpenAI Agents SDK、LangChain、LlamaIndex，或任何兼容 MCP 的客户端。

此仓库将所有常见的分发方式汇集于一处：MCP 服务、Claude Skill、用于 ChatGPT GPT Actions 的 OpenAPI 3.1 规范、Cursor 项目规则、适用于遵循该标准的 23 种以上工具的 AGENTS.md，以及供 Copilot / Windsurf / 其他工具使用的符号链接文件。请在下方选择适合你运行环境的部分。

关于 GhostSwap：https://ghostswap.io 是一个无需 KYC、非托管的加密货币兑换平台，采用合作伙伴收入分成模式。钱包、dApp、交易所和联盟网站可以接入 Partners API，从用户完成的每笔兑换中赚取 0–4 %，以 USDT 结算，合作伙伴无需管理流动性。

**没有合作伙伴账户？从这里开始。**将任何 MCP 客户端连接到托管的免密钥服务 https://mcp.ghostswap.io/mcp（Streamable HTTP；也提供 /sse）——或者直接打开 GhostSwap Chat，输入指令进行兑换，例如 “将 0.05 BTC 兑换为 XMR”。无需账户，无需 KYC。

目录

• 按运行环境快速安装
• 此仓库包含什么
• 为什么选择 ghostswap-agents
• 与类似项目的比较
• 常见问题
• API 实际功能
• 你需要准备什么（人工操作部分）
• 联盟 / 推荐链接——无需编码的方式
• 更新
• 链接
• 许可证

按运行环境快速安装

{
  "mcpServers": {
    "ghostswap": { "url": "https://mcp.ghostswap.io/mcp" }
  }
}

{
  "mcpServers": {
    "ghostswap": {
      "command": "npx",
      "args": ["-y", "@ghostswapio/mcp"],
      "env": {
        "GHOSTSWAP_PUBLIC_KEY": "gspk_live_...",
        "GHOSTSWAP_SECRET": "gssk_live_..."
      }
    }
  }
}

/plugin marketplace add ghostswap1/ghostswap-agents
/plugin install ghostswap-partners-api@ghostswap1/ghostswap-agents

git clone https://github.com/ghostswap1/ghostswap-agents.git
cp -r ghostswap-agents/skills/ghostswap-partners-api ~/.claude/skills/

{
  "mcpServers": {
    "ghostswap": {
      "command": "npx",
      "args": ["-y", "@ghostswapio/mcp"],
      "env": {
        "GHOSTSWAP_PUBLIC_KEY": "gspk_live_...",
        "GHOSTSWAP_SECRET": "gssk_live_..."
      }
    }
  }
}

mcpServers:
  - name: ghostswap
    command: npx
    args: ["-y", "@ghostswapio/mcp"]
    env:
      GHOSTSWAP_PUBLIC_KEY: gspk_live_...
      GHOSTSWAP_SECRET: gssk_live_...

read: AGENTS.md  # or wherever you've placed this file

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

ghostswap_mcp = MCPServerStdio(
    params={
        "command": "npx",
        "args": ["-y", "@ghostswapio/mcp"],
        "env": {
            "GHOSTSWAP_PUBLIC_KEY": "gspk_live_...",
            "GHOSTSWAP_SECRET": "gssk_live_...",
        },
    },
)

agent = Agent(
    name="SwapBot",
    mcp_servers=[ghostswap_mcp],
    instructions="You help users execute crypto-to-crypto swaps.",
)

import { experimental_createMCPClient, generateText, openai } from 'ai';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';

const client = await experimental_createMCPClient({
  transport: new Experimental_StdioMCPTransport({
    command: 'npx',
    args: ['-y', '@ghostswapio/mcp'],
    env: { GHOSTSWAP_PUBLIC_KEY: '…', GHOSTSWAP_SECRET: '…' },
  }),
});

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: await client.tools(),
  prompt: 'Quote a 0.01 BTC → ETH swap for me.',
});

import yaml, requests
from langchain_community.agent_toolkits.openapi.toolkit import OpenAPIToolkit
from langchain_community.tools.json.tool import JsonSpec

spec = yaml.safe_load(requests.get("https://partners-api.ghostswap.io/openapi.yaml").text)
toolkit = OpenAPIToolkit.from_llm(
    llm=...,
    json_spec=JsonSpec(dict_=spec),
    requests_wrapper=...,  # add your Authorization: Bearer header here
)

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "ghostswap": {
        "command": "npx",
        "args": ["-y", "@ghostswapio/mcp"],
        "env": {
            "GHOSTSWAP_PUBLIC_KEY": "gspk_live_...",
            "GHOSTSWAP_SECRET": "gssk_live_...",
        },
        "transport": "stdio",
    }
})
tools = await client.get_tools()

from llama_index.tools.mcp import McpToolSpec, BasicMCPClient

mcp_client = BasicMCPClient(
    "npx", args=["-y", "@ghostswapio/mcp"],
    env={"GHOSTSWAP_PUBLIC_KEY": "...", "GHOSTSWAP_SECRET": "..."},
)
tools = McpToolSpec(client=mcp_client).to_tool_list()

npx -y @ghostswapio/mcp

curl https://partners.ghostswap.io/skill.md | pbcopy

本仓库包含的内容

ghostswap-agents/
├── README.md                                       ← you are here
├── AGENTS.md                                       ← Source of truth (agents.md standard, 23+ tools)
├── CLAUDE.md → AGENTS.md                           ← symlink for Claude Code
├── .github/
│   └── copilot-instructions.md → ../AGENTS.md      ← symlink for GitHub Copilot
├── .windsurfrules → AGENTS.md                      ← symlink for Windsurf
├── .cursor/
│   ├── rules/main.mdc                              ← Cursor project rules
│   └── mcp.json                                    ← Cursor MCP config
├── .claude-plugin/
│   └── plugin.json                                 ← Claude Code plugin manifest
├── skills/
│   └── ghostswap-partners-api/
│       └── SKILL.md                                ← Claude Agent Skill (mirror of /skill.md)
├── openapi/
│   ├── openapi.yaml                                ← OpenAPI 3.1 (source of truth)
│   └── openapi.json                                ← Same, JSON
├── mcp-server/                                     ← Published as @ghostswapio/mcp on npm
│   ├── src/index.ts
│   ├── package.json
│   ├── manifest.json                               ← DXT/MCPB for one-click Claude Desktop
│   └── README.md
├── remote-mcp/                                     ← Hosted MCP at mcp.ghostswap.io (Cloudflare Worker)
│   ├── src/index.ts
│   └── server.json                                 ← MCP registry entry (io.github.ghostswap1/mcp)
├── chat/                                           ← GhostSwap Chat at chat.ghostswap.io (Cloudflare Worker)
│   ├── src/index.ts
│   └── public/                                     ← index.html, llms.txt, robots.txt, sitemap.xml
└── gpt-action/
    └── README.md                                   ← Step-by-step for ChatGPT GPT builder

为什么选择 ghostswap-agents

与类似项目的对比

常见问题

我应该选择哪种 AI 运行时？

如果你要在聊天式助手（Claude Desktop、ChatGPT、Cursor 的聊天功能）中部署，请使用 MCP 服务——它会为 Agent 提供类型化工具，而不是一大段 Markdown。如果要嵌入 Custom GPT 或服务端 LangChain 工作流，请使用 OpenAPI 规范。如果要编写 Claude Code 工作流，请使用 SKILL.md。README 提供了所有方式的可直接复制粘贴的安装代码片段。

运行之前需要先注册合作伙伴账号吗？

要执行真实兑换，需要——请前往 https://partners.ghostswap.io/sign-up 注册，提交申请表，等待管理员批准（通常不到 24 小时），然后从控制面板创建凭证。如果只是想查看 OpenAPI 规范、浏览 SKILL.md，或运行 MCP 服务的 list_currencies 工具（发现可用币种无需合作伙伴专属凭证），则无需账号。

这个代码仓库与 GhostSwap REST API 本身有什么区别？

这个代码仓库只是一个轻量分发层——它不托管 API。实际 API 位于 https://partners-api.ghostswap.io。仓库中的所有内容都只是将该 API 封装成不同 AI 运行时可使用的格式。

这个 MCP 服务是“官方”的吗？

是的——由 GhostSwap 团队发布至 https://github.com/ghostswap1/ghostswap-agents，并以 @ghostswapio/mcp 的名称发布到 npm。采用 MIT 许可证。

我可以自托管 MCP 服务吗？

可以。它通过 stdio（MCP 的标准传输方式）运行，并且只调用公开的 REST API。使用 cd mcp-server && npm install && npm run build && node dist/index.js 构建即可。转发你的 GHOSTSWAP_PUBLIC_KEY 和 GHOSTSWAP_SECRET 环境变量后即可使用。

API 变更时，OpenAPI 规范会自动更新吗？

规范的权威版本实时托管在 https://partners-api.ghostswap.io/openapi.json，反映已部署的 API。本仓库 openapi/ 中的副本会在 API 变更时更新；GitHub Actions CI 会在每个 PR 上对其进行 lint 检查。如果你要将其用于 ChatGPT GPT Actions，请让 GPT 指向实时 URL，而不是仓库中的副本，这样就能自动获取更新。

如何确认一次兑换是真实的？

每个 POST /v1/swaps 响应都包含一个 payinAddress，也就是终端用户存入资金的地址。兑换会依次经历以下状态（waiting → confirming → exchanging → sending → finished），你可以通过 GET /v1/swaps/{id} 轮询查询。完整生命周期见 SKILL.md 和 https://partners.ghostswap.io/docs/concepts/status-lifecycle。

如果网络错误后，Agent 重试 create_swap，会发生什么？

重用首次尝试时发送的同一个 Idempotency-Key。GhostSwap 会进行去重并返回原兑换，不会创建重复兑换。重试时重新生成密钥是合作伙伴端最常见的 bug 来源；MCP 服务的 create_swap 工具说明和 SKILL.md 都明确提醒了这一点。

GhostSwap 与 DEX 或自托管兑换路由器有何不同？

DEX 要求用户拥有钱包、为每笔交易签名并支付 gas。GhostSwap 是非托管式的，因为 GhostSwap 持有用户资金的时间不会超过完成兑换所需的时间，但用户只需向一个存款地址发送一笔链上交易。无需集成钱包，无需签名流程，也无需处理 gas 费用相关的用户体验——因此，对于将兑换作为一项功能而非核心产品的钱包和应用来说，GhostSwap 是一个热门选择。

GhostSwap 是否要求 KYC 或账户？

不需要。GhostSwap 是一家无需 KYC 的加密货币交易所：终端用户无需账户、电子邮件或身份证件，只需向一次性存款地址转账，即可在自己的钱包中收到兑换后的币种。这适用于隐私币兑换，例如将 BTC 兑换为 XMR（Monero）或 BTC 兑换为 ZEC（Zcash），也适用于其他 1,600 多种币种。合作伙伴可自行为其用户设定产品条款。如果某次兑换的状态显示为 hold，请引导用户联系 [email protected]（见 SKILL.md）。

哪些币种需要备注或目标标签？

XRP、XLM、ATOM、HBAR 和 TON 等币种需要同时提供地址和备注、目标标签或付款 ID。GET /v1/currencies 会通过 requiresExtraId: true 标记这些币种（并在 extraIdName 中提供易懂的标签）。收集该标签，并在 POST /v1/swaps 中将其作为 extraId 发送——如果缺少该字段，API 会返回 missing_extra_id，且不会创建兑换。如果用户确认其钱包没有标签，请发送 extraIdNotRequired: true。本仓库中的三个 MCP 接入方式都支持这些字段。

我可以不使用 API 密钥，在自己的网站上展示 GhostSwap 汇率吗？

可以——GET https://partners-api.ghostswap.io/v1/public/quote?from=btc&to=xmr&amount=0.05 无需凭证即可返回标准公开展示汇率。该接口允许 CORS，每个 IP 的请求速率限制为每分钟 60 次，因此请将结果缓存 10–30 秒。实际执行兑换时，请使用经过身份验证的 POST /v1/quotes 和 POST /v1/swaps。

如何报告安全问题？

发送电子邮件至 [email protected]，并在主题前缀中使用 [security] ghostswap-agents:——请勿提交公开的 GitHub issue。完整流程见 SECURITY.md。

API 的实际功能

用于非托管加密货币兑换的服务器到服务器 REST API。最终用户将资金发送到你返回的存款地址；目标钱包会收到兑换后的资金。GhostSwap 负责所有上游流动性、签名和结算——你永远不会持有签名密钥。合作伙伴每笔成功完成的兑换可赚取 0–4 % 的加价（申请时设定），以 USDT 支付（最低门槛为 ≥ $100）。

完整参考文档：https://partners.ghostswap.io/docs。

你需要准备的事项（人工操作部分）

1. 注册：访问 https://partners.ghostswap.io/sign-up → 填写申请（企业名称、网站、预计月交易量、选择的合作伙伴费用 0–4 %）。
2. 等待批准（管理员审核——通常 <24 h）。激活后你会收到电子邮件。
3. 在 /dashboard/api-credentials 创建凭证 → 复制 gspk_live_… 公钥和 gssk_live_… 密钥。
4. 将两者设置为服务端环境变量——切勿放在浏览器代码中，也不要提交到 git。

获得凭证后，上述所有运行时都能在 5 分钟内使用。

联盟 / 推荐链接——无需代码的方式

如果你完全不想集成 API，每位获批的合作伙伴也会获得一个推荐链接：

https://ghostswap.io/?ref=<your-slug>

点击链接的最终用户会获得 30 天的 Cookie 归因；他们在 ghostswap.io 完成的任何兑换都会按交易量的 1 % 为你计入收益。你无需编写任何代码——只需分享 URL。获批后，可在控制面板中选择你的专属标识。

更新

git pull            # in your local clone
# Or, for the npm package:
npm update -g @ghostswapio/mcp
# Or, for the Claude Code plugin:
/plugin update ghostswap-partners-api

https://partners-api.ghostswap.io/openapi.json 上的 OpenAPI 规范始终反映实时 API。每次部署 GhostSwap 文档时，SKILL.md 和 AGENTS.md 都会同步更新。

链接

许可证

MIT。随意使用、派生并发布。