Ghostswap Agents MCP Server

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.

---

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

Option A — MCP server (recommended for Desktop)

Add to ~/.claude/claude_desktop_config.json:

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

Restart Claude Desktop. 7 typed tools appear under the ghostswap server.

Option B — Claude Code plugin

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

Option C — Skill into ~/.claude/skills/

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

Full canonical SKILL.md also mirrored at https://partners.ghostswap.io/skill.md.

MCP (recommended — typed tools, one-click) — add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

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

Project rules (always-on prose conventions) — drop .cursor/rules/main.mdc from this repo into your own project. Or just clone this repo and let Cursor read it as a workspace.

MCP — add to ~/.codeium/windsurf/mcp_config.json (same JSON as the Claude / Cursor block above).

Rules — copy AGENTS.md to your project root (or symlink it to .windsurfrules). Windsurf auto-loads both.

Add to ~/.continue/config.yaml:

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

1. Sign up at https://partners.ghostswap.io/sign-up + get your credential
2. In the GPT builder → Configure → Create new action
3. Import from URL:

   https://partners-api.ghostswap.io/openapi.json
   

4. Auth → API Key → Bearer → paste <public_key>:<secret> (single string, colon-separated)
5. Privacy Policy URL: https://ghostswap.io/privacy

Full step-by-step in gpt-action/README.md, including suggested GPT Instructions copy.

Drop AGENTS.md at your repo root (or copy .github/copilot-instructions.md — they're symlinked in this repo).

For tool access (typed function calls), use the MCP server via your IDE's MCP plugin.

Gemini CLI reads AGENTS.md natively — drop AGENTS.md at your repo root.

For Gemini Code Assist, copy AGENTS.md to .gemini/styleguide.md.

For tool access, use the MCP server (Gemini API + Vertex AI added MCP support in March 2026).

In your project's .aider.conf.yml:

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

Aider auto-loads it as read-only context every session.

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.',
});

Via OpenAPI (the simpler path):

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
)

Via MCP (cleaner — uses the @ghostswapio/mcp server):

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()

Or use the OpenAPI spec with RestAPIToolSpec.

The server is a standard stdio MCP server. Any client that speaks MCP v2024-11-05 works:

npx -y @ghostswapio/mcp

Pass GHOSTSWAP_PUBLIC_KEY and GHOSTSWAP_SECRET via env vars.

Or, for HTTP-style integrations, use the OpenAPI spec directly:

• JSON: https://partners-api.ghostswap.io/openapi.json
• YAML: https://partners-api.ghostswap.io/openapi.yaml

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

Paste into the chat with "Build me a Node.js integration based on this." — the SKILL.md is plain markdown with a ~120-line working reference proxy. Works in any LLM.

---

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
└── 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.

What about regulatory compliance?

End-users transact with GhostSwap directly through the deposit address. Partners are responsible for their own jurisdiction's compliance posture (terms of service, AML/KYC if their product otherwise requires it, etc.). For high-volume or unusual transaction patterns, GhostSwap may place a swap on hold for AML review — the SKILL.md describes how to surface this state to end-users (direct them to support@ghostswap.io).

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.