Claude Desktop / Claude Code / claude.ai

\n\n**Option A — MCP server (recommended for Desktop)**\n\nAdd to `~/.claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"ghostswap\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ghostswapio/mcp\"],\n \"env\": {\n \"GHOSTSWAP_PUBLIC_KEY\": \"gspk_live_...\",\n \"GHOSTSWAP_SECRET\": \"gssk_live_...\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. 7 typed tools appear under the `ghostswap` server.\n\n**Option B — Claude Code plugin**\n\n```bash\n/plugin marketplace add ghostswap1/ghostswap-agents\n/plugin install ghostswap-partners-api@ghostswap1/ghostswap-agents\n```\n\n**Option C — Skill into `~/.claude/skills/`**\n\n```bash\ngit clone https://github.com/ghostswap1/ghostswap-agents.git\ncp -r ghostswap-agents/skills/ghostswap-partners-api ~/.claude/skills/\n```\n\nFull canonical SKILL.md also mirrored at .\n\n

\n\n

Cursor

\n\n**MCP** (recommended — typed tools, one-click) — add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):\n\n```json\n{\n \"mcpServers\": {\n \"ghostswap\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ghostswapio/mcp\"],\n \"env\": {\n \"GHOSTSWAP_PUBLIC_KEY\": \"gspk_live_...\",\n \"GHOSTSWAP_SECRET\": \"gssk_live_...\"\n }\n }\n }\n}\n```\n\n**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.\n\n

\n\n

Windsurf

\n\n**MCP** — add to `~/.codeium/windsurf/mcp_config.json` (same JSON as the Claude / Cursor block above).\n\n**Rules** — copy [`AGENTS.md`](https://github.com/ghostswap1/ghostswap-agents/blob/main/AGENTS.md) to your project root (or symlink it to `.windsurfrules`). Windsurf auto-loads both.\n\n

\n\n

Continue.dev

\n\nAdd to `~/.continue/config.yaml`:\n\n```yaml\nmcpServers:\n - name: ghostswap\n command: npx\n args: [\"-y\", \"@ghostswapio/mcp\"]\n env:\n GHOSTSWAP_PUBLIC_KEY: gspk_live_...\n GHOSTSWAP_SECRET: gssk_live_...\n```\n\n

\n\n

ChatGPT (Custom GPT / GPT Action)

\n\n1. Sign up at + get your credential\n2. In the [GPT builder](https://chatgpt.com/gpts/editor) → Configure → **Create new action**\n3. **Import from URL**:\n ```\n https://partners-api.ghostswap.io/openapi.json\n ```\n4. **Auth** → API Key → Bearer → paste `:` (single string, colon-separated)\n5. **Privacy Policy URL**: `https://ghostswap.io/privacy`\n\nFull step-by-step in [`gpt-action/README.md`](https://github.com/ghostswap1/ghostswap-agents/blob/main/gpt-action/README.md), including suggested GPT Instructions copy.\n\n

\n\n

GitHub Copilot

\n\nDrop [`AGENTS.md`](https://github.com/ghostswap1/ghostswap-agents/blob/main/AGENTS.md) at your repo root (or copy [`.github/copilot-instructions.md`](https://github.com/ghostswap1/ghostswap-agents/blob/main/.github/copilot-instructions.md) — they're symlinked in this repo).\n\nFor tool access (typed function calls), use the MCP server via your IDE's MCP plugin.\n\n

\n\n

Gemini Code Assist / Gemini CLI

\n\nGemini CLI reads `AGENTS.md` natively — drop [`AGENTS.md`](https://github.com/ghostswap1/ghostswap-agents/blob/main/AGENTS.md) at your repo root.\n\nFor Gemini Code Assist, copy [`AGENTS.md`](https://github.com/ghostswap1/ghostswap-agents/blob/main/AGENTS.md) to `.gemini/styleguide.md`.\n\nFor tool access, use the MCP server (Gemini API + Vertex AI added MCP support in March 2026).\n\n

\n\n

Aider

\n\nIn your project's `.aider.conf.yml`:\n\n```yaml\nread: AGENTS.md # or wherever you've placed this file\n```\n\nAider auto-loads it as read-only context every session.\n\n

\n\n

OpenAI Agents SDK (Python)

\n\n```python\nfrom agents import Agent, Runner\nfrom agents.mcp import MCPServerStdio\n\nghostswap_mcp = MCPServerStdio(\n params={\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ghostswapio/mcp\"],\n \"env\": {\n \"GHOSTSWAP_PUBLIC_KEY\": \"gspk_live_...\",\n \"GHOSTSWAP_SECRET\": \"gssk_live_...\",\n },\n },\n)\n\nagent = Agent(\n name=\"SwapBot\",\n mcp_servers=[ghostswap_mcp],\n instructions=\"You help users execute crypto-to-crypto swaps.\",\n)\n```\n\n

\n\n

Vercel AI SDK (TypeScript)

\n\n```ts\nimport { experimental_createMCPClient, generateText, openai } from 'ai';\nimport { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';\n\nconst client = await experimental_createMCPClient({\n transport: new Experimental_StdioMCPTransport({\n command: 'npx',\n args: ['-y', '@ghostswapio/mcp'],\n env: { GHOSTSWAP_PUBLIC_KEY: '…', GHOSTSWAP_SECRET: '…' },\n }),\n});\n\nconst { text } = await generateText({\n model: openai('gpt-4o'),\n tools: await client.tools(),\n prompt: 'Quote a 0.01 BTC → ETH swap for me.',\n});\n```\n\n

\n\n

LangChain (Python / JS)

\n\n**Via OpenAPI** (the simpler path):\n\n```python\nimport yaml, requests\nfrom langchain_community.agent_toolkits.openapi.toolkit import OpenAPIToolkit\nfrom langchain_community.tools.json.tool import JsonSpec\n\nspec = yaml.safe_load(requests.get(\"https://partners-api.ghostswap.io/openapi.yaml\").text)\ntoolkit = OpenAPIToolkit.from_llm(\n llm=...,\n json_spec=JsonSpec(dict_=spec),\n requests_wrapper=..., # add your Authorization: Bearer header here\n)\n```\n\n**Via MCP** (cleaner — uses the @ghostswapio/mcp server):\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient({\n \"ghostswap\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@ghostswapio/mcp\"],\n \"env\": {\n \"GHOSTSWAP_PUBLIC_KEY\": \"gspk_live_...\",\n \"GHOSTSWAP_SECRET\": \"gssk_live_...\",\n },\n \"transport\": \"stdio\",\n }\n})\ntools = await client.get_tools()\n```\n\n

\n\n

LlamaIndex

\n\n```python\nfrom llama_index.tools.mcp import McpToolSpec, BasicMCPClient\n\nmcp_client = BasicMCPClient(\n \"npx\", args=[\"-y\", \"@ghostswapio/mcp\"],\n env={\"GHOSTSWAP_PUBLIC_KEY\": \"...\", \"GHOSTSWAP_SECRET\": \"...\"},\n)\ntools = McpToolSpec(client=mcp_client).to_tool_list()\n```\n\nOr use the [OpenAPI spec](https://github.com/ghostswap1/ghostswap-agents/blob/main/openapi/openapi.yaml) with `RestAPIToolSpec`.\n\n

\n\n

Generic MCP client / any other runtime

\n\nThe server is a standard stdio MCP server. Any client that speaks MCP v2024-11-05 works:\n\n```bash\nnpx -y @ghostswapio/mcp\n```\n\nPass `GHOSTSWAP_PUBLIC_KEY` and `GHOSTSWAP_SECRET` via env vars.\n\nOr, for HTTP-style integrations, use the OpenAPI spec directly:\n- JSON: \n- YAML: \n\n

\n\n

Paste into any chat (ChatGPT free, Gemini, Perplexity, etc.)

\n\n```bash\ncurl https://partners.ghostswap.io/skill.md | pbcopy\n```\n\nPaste 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.\n\n

\n\n---\n\n## What's inside this repo\n\n```\nghostswap-agents/\n├── README.md ← you are here\n├── AGENTS.md ← Source of truth (agents.md standard, 23+ tools)\n├── CLAUDE.md → AGENTS.md ← symlink for Claude Code\n├── .github/\n│ └── copilot-instructions.md → ../AGENTS.md ← symlink for GitHub Copilot\n├── .windsurfrules → AGENTS.md ← symlink for Windsurf\n├── .cursor/\n│ ├── rules/main.mdc ← Cursor project rules\n│ └── mcp.json ← Cursor MCP config\n├── .claude-plugin/\n│ └── plugin.json ← Claude Code plugin manifest\n├── skills/\n│ └── ghostswap-partners-api/\n│ └── SKILL.md ← Claude Agent Skill (mirror of /skill.md)\n├── openapi/\n│ ├── openapi.yaml ← OpenAPI 3.1 (source of truth)\n│ └── openapi.json ← Same, JSON\n├── mcp-server/ ← Published as @ghostswapio/mcp on npm\n│ ├── src/index.ts\n│ ├── package.json\n│ ├── manifest.json ← DXT/MCPB for one-click Claude Desktop\n│ └── README.md\n└── gpt-action/\n └── README.md ← Step-by-step for ChatGPT GPT builder\n```\n\n---\n\n## Why ghostswap-agents\n\n| | |\n|---|---|\n| **Built-in to 13+ runtimes out of the box** | Claude (Desktop / Code / .ai), Cursor, Windsurf, Continue.dev, ChatGPT (Custom GPT + GPT Actions), GitHub Copilot, Gemini (Code Assist + CLI), Aider, OpenAI Agents SDK, Vercel AI SDK, LangChain, LlamaIndex, plus any generic MCP client. One repo covers everything. |\n| **MIT-licensed, vendor-controlled** | The pack is open source. Fork it, modify it, vendor it inside your own integration. No \"developer-tier\" tax, no plan-gated tools. |\n| **The integration is non-custodial** | GhostSwap routes liquidity and signs upstream. Partners never custody user funds and never hold signing keys. The credential proves \"this swap counts towards your commission\" — nothing else. |\n| **Partner revenue from the first swap** | Set your fee 0–4 % at application time. Earn USDT on every completed swap your integration generates, paid once the balance reaches $100. No upfront cost, no minimum volume. |\n| **Production-quality machine-readable surface** | The OpenAPI 3.1 spec covers every endpoint with full request/response schemas, `x-openai-isConsequential` flags, and documented `Idempotency-Key` + `RateLimit-*` headers. ChatGPT GPT Actions, LangChain, LlamaIndex, and openapi-generator-based SDKs all consume it directly. |\n| **Mirrors the GhostSwap brand on every surface** | Every install path links back to and — same docs, same vocabulary, same error envelope, regardless of which runtime the developer is on. |\n\n---\n\n## Compared to similar projects\n\n| | ghostswap-agents | Generic OpenAPI proxy | Self-hosted swap bot |\n|---|---|---|---|\n| Multi-LLM coverage (MCP + OpenAPI + SKILL + AGENTS) | ✅ Bundled | ⚠️ OpenAPI only | ❌ Hand-written |\n| No-KYC swap engine behind it | ✅ 1,600+ coins | ❌ Bring-your-own | ❌ Bring-your-own |\n| Partner revenue share | ✅ 0–4 % | ❌ | ❌ |\n| USDT payouts handled for you | ✅ | ❌ | ❌ |\n| Idempotency baked in | ✅ `Idempotency-Key` required | ⚠️ Depends on origin | ❌ DIY |\n| Live OpenAPI URL for ChatGPT GPT Actions | ✅ | ⚠️ Host it yourself | ❌ |\n| MIT-licensed | ✅ | ⚠️ Varies | ⚠️ Varies |\n\n---\n\n## Frequently asked questions\n\n### Which AI runtime should I pick?\n\nIf 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.\n\n### Do I need a partner account before I can run this?\n\nTo execute real swaps, yes — sign up at , 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.\n\n### What's the difference between this repo and the GhostSwap REST API itself?\n\nThis repo is a thin distribution layer — it does not host the API. The actual API lives at . Everything in this repo just wraps that API in formats different AI runtimes know how to consume.\n\n### Is the MCP server \"official\"?\n\nYes — published by the GhostSwap team to and to npm as [`@ghostswapio/mcp`](https://www.npmjs.com/package/@ghostswapio/mcp). MIT-licensed.\n\n### Can I self-host the MCP server?\n\nYes. 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.\n\n### Does the OpenAPI spec auto-update when the API changes?\n\nThe canonical spec is served live at 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.\n\n### How do I know if a swap is real?\n\nEvery `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 .\n\n### What happens if my agent retries `create_swap` after a network error?\n\nReuse 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.\n\n### How is GhostSwap different from a DEX or a self-custodial swap router?\n\nA 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.\n\n### What about regulatory compliance?\n\nEnd-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 ).\n\n### How do I report a security issue?\n\nEmail with the subject prefix `[security] ghostswap-agents:` — do not file a public GitHub issue. Full process in [SECURITY.md](https://github.com/ghostswap1/ghostswap-agents/blob/main/SECURITY.md).\n\n---\n\n## What the API actually does\n\nA 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).\n\n| | |\n|---|---|\n| **Supported coins** | 1,600+ |\n| **Auth** | Bearer (`gspk_live_…:gssk_live_…`) |\n| **Modes** | Float-rate (default) and fixed-rate (locked) |\n| **Rate limits** | 30 RPS per credential, 120 RPS per IP |\n| **Idempotency** | `Idempotency-Key` header required on `POST /v1/swaps` |\n| **Status polling** | `GET /v1/swaps/{id}` — terminal: `finished` / `failed` / `refunded` / `overdue` / `expired` |\n| **Refund** | Optional for float, required for fixed |\n| **Payouts** | USDT, $100 minimum, 1–3 business-day admin review |\n\nFull reference: .\n\n---\n\n## What you'll need (the human parts)\n\n1. **Sign up** at → fill the application (business name, website, expected monthly volume, chosen partner fee 0–4 %).\n2. **Wait for approval** (admin reviews — usually <24 h). You'll get an email when activated.\n3. **Issue a credential** at `/dashboard/api-credentials` → copy the `gspk_live_…` public key and `gssk_live_…` secret.\n4. **Set both as server-side env vars** — never in browser code, never in git.\n\nOnce you have credentials, all the runtimes above work in <5 minutes.\n\n---\n\n## Affiliate / referral link — the no-code path\n\nIf you don't want to integrate the API at all, every approved partner also gets a referral link:\n\n```\nhttps://ghostswap.io/?ref=\n```\n\nEnd-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.\n\n---\n\n## Updating\n\n```bash\ngit pull # in your local clone\n# Or, for the npm package:\nnpm update -g @ghostswapio/mcp\n# Or, for the Claude Code plugin:\n/plugin update ghostswap-partners-api\n```\n\nThe OpenAPI spec at always reflects the live API. The SKILL.md and AGENTS.md are kept in sync with every GhostSwap docs deploy.\n\n---\n\n## Links\n\n| Surface | URL |\n|---|---|\n| 🔗 Live docs | |\n| 🔗 OpenAPI 3.1 spec (JSON) | |\n| 🔗 OpenAPI 3.1 spec (YAML) | |\n| 🔗 Anthropic Agent Skill | |\n| 🔗 LLM index | |\n| 🔗 Full corpus for context-stuffing | |\n| 🔗 Sign up | |\n| 💬 Telegram | |\n| 📧 Email | |\n\n---\n\n## License\n\n[MIT](https://github.com/ghostswap1/ghostswap-agents/blob/main/LICENSE). Use it, fork it, ship it.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_113":114,"_115":116,"_117":118,"_119":120,"_121":122,"_123":124},"requiredSecrets",[],"tags",[98,99,100,101,102,103,104,105,106,107,108,109,110,111,112],"assets",[],"stats",{"_96":85,"_97":85},"ratingAvg","reviewCount","agents-md","ai-agent","chatgpt","claude","claude-skill","crypto-swap","cryptocurrency","cursor","cursor-rules","defi","ghostswap","github-copilot","gpt-actions","langchain","llamaindex","topics",[98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,125,126,127,128,129],"license","MIT","language","TypeScript","registryName","io.github.ghostswap1/mcp","homepage","https://ghostswap.io","packages",[],"mcp","mcp-server","no-kyc","openapi","windsurf","ENV",{"_132":133,"_134":135,"_136":137},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]