GhostSwap

ghostswap-agents

The official multi-LLM agent integration pack for GhostSwap — a no-KYC crypto-to-crypto swap engine supporting 1,600+ coins.

Drop the GhostSwap Partners API into any AI agent or coding assistant in one line — Claude, ChatGPT, Cursor, Windsurf, Gemini, GitHub Copilot, Continue.dev, OpenAI Agents SDK, LangChain, LlamaIndex, or any MCP-compatible client.

This repo bundles every common distribution surface in one place: an MCP server, a Claude Skill, an OpenAPI 3.1 spec for ChatGPT GPT Actions, project rules for Cursor, an AGENTS.md for the 23+ tools that follow that standard, and symlinked files for Copilot / Windsurf / others. Pick the section for your runtime below.

About GhostSwap: https://ghostswap.io is a no-KYC, non-custodial crypto-to-crypto exchange built on a partner-revenue-share model. Wallets, dApps, exchanges, and affiliate sites can integrate the Partners API to earn 0–4 % on every swap their users complete, with USDT payouts and no liquidity management on the partner's side.

No partner account? Start here. Point any MCP client at the hosted, no-key server https://mcp.ghostswap.io/mcp (Streamable HTTP; /sse also available) — or just open GhostSwap Chat and swap by typing, e.g. "swap 0.05 BTC to XMR". No account, no KYC.

Contents

• Quick install by runtime
• What's inside this repo
• Why ghostswap-agents
• Compared to similar projects
• Frequently asked questions
• What the API actually does
• What you'll need (the human parts)
• Affiliate / referral link — the no-code path
• Updating
• Links
• License

Quick install by runtime

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

What's inside this repo

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

Why ghostswap-agents

Compared to similar projects

Frequently asked questions

Which AI runtime should I pick?

If you're shipping in a chat-style assistant (Claude Desktop, ChatGPT, Cursor's chat), use the MCP server — it gives the agent typed tools instead of a wall of markdown. If you're embedding into a Custom GPT or a server-side LangChain pipeline, use the OpenAPI spec. If you're writing Claude Code workflows, use the SKILL.md. The README has copy-pasteable install snippets for all of them.

Do I need a partner account before I can run this?

To execute real swaps, yes — sign up at https://partners.ghostswap.io/sign-up, submit the application form, wait for admin approval (usually under 24 hours), then issue a credential from the dashboard. To just explore the OpenAPI spec, browse the SKILL.md, or run the MCP server's list_currencies tool (which doesn't require a partner-specific credential to discover), no account is needed.

What's the difference between this repo and the GhostSwap REST API itself?

This repo is a thin distribution layer — it does not host the API. The actual API lives at https://partners-api.ghostswap.io. Everything in this repo just wraps that API in formats different AI runtimes know how to consume.

Is the MCP server "official"?

Yes — published by the GhostSwap team to https://github.com/ghostswap1/ghostswap-agents and to npm as @ghostswapio/mcp. MIT-licensed.

Can I self-host the MCP server?

Yes. It runs over stdio (the standard MCP transport) and just calls the public REST API. Build it with cd mcp-server && npm install && npm run build && node dist/index.js. Forward your GHOSTSWAP_PUBLIC_KEY and GHOSTSWAP_SECRET env vars and you're set.

Does the OpenAPI spec auto-update when the API changes?

The canonical spec is served live at https://partners-api.ghostswap.io/openapi.json and reflects the deployed API. The copy in openapi/ of this repo is updated whenever the API changes; the GitHub Actions CI lints it on every PR. If you're consuming this for ChatGPT GPT Actions, point your GPT at the live URL rather than the repo so you get updates automatically.

How do I know if a swap is real?

Every POST /v1/swaps response includes a payinAddress — the deposit address the end-user funds. The swap progresses through statuses (waiting → confirming → exchanging → sending → finished) which you poll via GET /v1/swaps/{id}. The full lifecycle is documented in the SKILL.md and at https://partners.ghostswap.io/docs/concepts/status-lifecycle.

What happens if my agent retries create_swap after a network error?

Reuse the same Idempotency-Key you sent on the first attempt. GhostSwap deduplicates and returns the original swap — no duplicate is created. Regenerating the key on retry is the most common source of partner-side bugs; the MCP server's create_swap tool description and the SKILL.md both call this out explicitly.

How is GhostSwap different from a DEX or a self-custodial swap router?

A DEX requires the user to have a wallet, sign every transaction, and pay gas. GhostSwap is non-custodial in the sense that GhostSwap never holds user funds longer than the swap takes, but the user only needs to send a single on-chain transaction to a deposit address. No wallet integration, no signing flow, no gas-fee UX — that's why it's a popular choice for wallets and apps where the swap is a feature, not the product.

Does GhostSwap require KYC or an account?

No. GhostSwap is a no-KYC crypto exchange: end-users need no account, no email and no ID — they send to a one-time deposit address and receive the swapped coins in their own wallet. That covers privacy-coin swaps such as exchanging BTC to XMR (Monero) or BTC to ZEC (Zcash) as well as 1,600+ other coins. Partners set their own product terms for their own users. If a swap ever shows status hold, direct the user to support@ghostswap.io (see SKILL.md).

Which coins need a memo or destination tag?

Coins such as XRP, XLM, ATOM, HBAR and TON use a memo / destination tag / payment ID alongside the address. GET /v1/currencies marks them with requiresExtraId: true (plus a human label in extraIdName). Collect the tag and send it as extraId on POST /v1/swaps — without it the API returns missing_extra_id and no swap is created. If the user confirms their wallet has no tag, send extraIdNotRequired: true. All three MCP surfaces in this repo support these fields.

Can I show GhostSwap rates on my site without an API key?

Yes — GET https://partners-api.ghostswap.io/v1/public/quote?from=btc&to=xmr&amount=0.05 returns the standard public display rate with no credential. It's CORS-open and limited to 60 requests/minute per IP, so cache results for 10–30 s. Use the authenticated POST /v1/quotes + POST /v1/swaps to actually execute swaps.

How do I report a security issue?

Email support@ghostswap.io with the subject prefix [security] ghostswap-agents: — do not file a public GitHub issue. Full process in SECURITY.md.

What the API actually does

A server-to-server REST API for non-custodial crypto swaps. End-users send funds to a deposit address you return; the destination wallet receives the swapped funds. GhostSwap handles all upstream liquidity, signing, and clearing — you never hold signing keys. Partners earn a 0–4 % markup (set at application time) on every completed swap, paid out in USDT (≥ $100 threshold).

Full reference: https://partners.ghostswap.io/docs.

What you'll need (the human parts)

1. Sign up at https://partners.ghostswap.io/sign-up → fill the application (business name, website, expected monthly volume, chosen partner fee 0–4 %).
2. Wait for approval (admin reviews — usually <24 h). You'll get an email when activated.
3. Issue a credential at /dashboard/api-credentials → copy the gspk_live_… public key and gssk_live_… secret.
4. Set both as server-side env vars — never in browser code, never in git.

Once you have credentials, all the runtimes above work in <5 minutes.

Affiliate / referral link — the no-code path

If you don't want to integrate the API at all, every approved partner also gets a referral link:

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

End-users who click get a 30-day cookie attribution; any swap they complete on ghostswap.io credits you 1 % of the volume. No code on your end — just share the URL. Pick your slug from the dashboard after approval.

Updating

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

The OpenAPI spec at https://partners-api.ghostswap.io/openapi.json always reflects the live API. The SKILL.md and AGENTS.md are kept in sync with every GhostSwap docs deploy.

Links

License

MIT. Use it, fork it, ship it.