GhostSwap Partners API integration

You are helping a developer integrate the GhostSwap Partners API — a server-to-server REST API for non-custodial crypto-to-crypto swaps. The developer's end-users send funds to a deposit address GhostSwap returns; the destination wallet receives the swapped funds. GhostSwap handles all upstream liquidity, signing, and clearing. The partner earns a 0–4 % markup (chosen at application time) on every completed swap, paid out in USDT once balance ≥ $100.

This skill is the single document you need to produce a working end-to-end integration. Read it once, then write code.

When to use this skill

Trigger when the developer's request involves any of:

• Adding a crypto exchange widget, swap form, or "convert X to Y" flow to their app
• Accepting one crypto and crediting the user in a different one
• Quoting live exchange rates for a pair (e.g. BTC → ETH)
• Earning affiliate commission on referred swaps (the ?ref=<slug> flow on ghostswap.io)
• Building a Telegram bot, Discord bot, or wallet plugin that does crypto-to-crypto
• Specifically mentions "GhostSwap", "ghostswap.io", "partners.ghostswap.io", gspk_live_*, or gssk_live_*

Do not trigger for fiat on/off-ramps, custodial trading APIs, or self-custodial DEX SDKs — those are different products.

Architecture, in one sentence

Your server holds the bearer token; your server proxies every call to https://partners-api.ghostswap.io; your browser code talks only to your server.

The bearer must never reach the browser. Browser code calls /api/quote, /api/swap, etc. on the developer's own server; the server adds Authorization: Bearer ${PUBLIC_KEY}:${SECRET} and forwards to GhostSwap.

Step 0 — Get a credential (one-time, by the developer)

The developer (not the agent) must do this once:

1. Sign in at <https://partners.ghostswap.io/sign-up>.
2. Submit the application form (org name, website, expected monthly volume, chosen partner fee 0–4 %).
3. Wait for admin approval (~24 h). Once status flips to active, an activation email lands in their inbox.
4. Open /dashboard/api-credentials → click Create live credential → copy both values:

• GHOSTSWAP_PUBLIC_KEY — looks like gspk_live_<32 hex>, always recoverable from the dashboard.
• GHOSTSWAP_SECRET — looks like gssk_live_<48 hex>, shown once at creation; can be revealed later via the audit-logged Reveal secret button.

1. Set both as environment variables on the developer's server. Never paste them into code that ships to the browser.

If the developer says "I haven't applied yet", direct them to that URL and pause the integration work — no API call works without a credential.

The standard workflow (memorize this)

1. GET  /v1/currencies              → populate dropdowns
2. POST /v1/addresses/validate      → on blur, check the user's payout address
3. POST /v1/quotes                  → live quote on every amount/pair change
4. POST /v1/swaps                   → on confirm; MUST include Idempotency-Key
5. GET  /v1/swaps/{id}              → poll every 10 s while UI visible, 30 s when backgrounded
6. Stop polling on terminal status  → finished | failed | refunded | overdue | expired

That's the entire flow. Every well-built integration is some variant of these six steps.

Authentication

Every /v1/* request needs exactly two headers:

Authorization: Bearer ${GHOSTSWAP_PUBLIC_KEY}:${GHOSTSWAP_SECRET}
Content-Type: application/json

The colon between public key and secret is part of the bearer string — there is no separate signing step. The server argon2id-verifies the secret against a hashed copy; partners never sign anything themselves.

const AUTH = `Bearer ${process.env.GHOSTSWAP_PUBLIC_KEY}:${process.env.GHOSTSWAP_SECRET}`;

Endpoint cheat sheet

Base URL: https://partners-api.ghostswap.io

Display rules (these are the user-visible parts)

Quote response shape:

{
  "quote": {
    "from": "btc", "to": "eth",
    "amountFrom": "0.01",
    "amountTo": "0.1532",
    "networkFee": "0.0021",
    "amountUserReceives": "0.1511",
    "rate": "15.32",
    "fee": "0.001",
    "min": "0.0008", "max": "5.0",
    "mode": "float"
  }
}

Show `amountUserReceives` to the user, not `amountTo`. The subtraction (amountTo - networkFee) is already done. Also display rate, min, and max. Re-render on every change of from, to, or amountFrom — debounce ~400 ms so the user can type freely.

Swap response shape:

{
  "swap": {
    "id": "htpi6bqnazl7hbjd",
    "status": "waiting",
    "from": "btc", "to": "eth",
    "amountFrom": "0.01",
    "amountExpectedTo": "0.1532",
    "payinAddress": "bc1q…",
    "payoutAddress": "0x…",
    "refundAddress": "bc1q…",
    "createdAt": "2026-04-29T12:00:00Z"
  }
}

Display `payinAddress` prominently — that's the deposit address the user must send amountFrom of from to. Render as a copyable string; a QR code is nice-to-have (use qrcode from npm).

The id is the canonical swap identifier in your records, GhostSwap's records, and the upstream provider's records. Use it for every follow-up call and store it on your order row.

Idempotency — non-negotiable rule

POST /v1/swaps requires an Idempotency-Key header. Generate a UUID v4 once per logical "Confirm" click and reuse it across HTTP retries of THAT click. Do not generate a fresh UUID on retry — that creates a duplicate swap.

import { randomUUID } from 'node:crypto';

// On the client: one UUID per Confirm button press; reset after success.
let confirmKey = null;
function onConfirmClick() {
  if (!confirmKey) confirmKey = crypto.randomUUID(); // browser-side
  // POST to your server with confirmKey in the body
}

// On the server: forward the key as a header to GhostSwap.
await fetch(`${BASE}/v1/swaps`, {
  method: 'POST',
  headers: {
    'Authorization': AUTH,
    'Content-Type': 'application/json',
    'Idempotency-Key': req.body.idempotencyKey,
  },
  body: JSON.stringify(swapBody),
});

If the developer's code regenerates the UUID on every fetch, fix it. That single bug has produced duplicate swaps for real partners.

Polling cadence

Poll GET /v1/swaps/{id} after creation:

Terminal statuses: finished, failed, refunded, overdue, expired.

GhostSwap refreshes upstream status every ~30 s, so polling faster than 10 s wastes the rate budget without giving the user fresher data. Polling slower than 60 s feels laggy while the user is watching the page.

Float vs fixed-rate swaps

Default to float unless the product specifically needs a locked rate. The fixed flow adds two failure modes: stale rateId (HTTP 409 rate_expired → re-quote with a new `Idempotency-Key`) and expired status (the user missed the payTill deadline).

Error envelope

Every non-2xx body has this shape:

{
  "error": {
    "type": "validation_error",
    "code": "amount_below_min",
    "message": "Minimum amountFrom is 0.0008",
    "param": "amountFrom"
  }
}

Surface error.message to the end-user (and error.param when present). Recovery by type:

Every response includes an X-Request-Id header. Log it. Forward it to support when escalating.

Rate limits

• Per credential: 30 RPS — every gspk_live_* gets its own bucket.
• Per source IP: 120 RPS (pre-auth) — generous for partners on shared egress.
• Standard RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers on every response. Self-throttle from RateLimit-Remaining before hitting 429.
• /health is unmetered.

Minimal working example (Node.js + Express)

This is a complete server-side proxy you can deliver to the developer as a starting point. ~120 lines, no build step, no frameworks beyond Express.

// server.js
import 'dotenv/config';
import express from 'express';
import { randomUUID } from 'node:crypto';

const { GHOSTSWAP_PUBLIC_KEY, GHOSTSWAP_SECRET, PORT = 3000 } = process.env;
if (!GHOSTSWAP_PUBLIC_KEY || !GHOSTSWAP_SECRET) {
  console.error('Set GHOSTSWAP_PUBLIC_KEY and GHOSTSWAP_SECRET in your env.');
  process.exit(1);
}

const BASE = 'https://partners-api.ghostswap.io';
const AUTH = `Bearer ${GHOSTSWAP_PUBLIC_KEY}:${GHOSTSWAP_SECRET}`;

async function gs(method, path, { body, idempotencyKey } = {}) {
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      'Authorization': AUTH,
      'Content-Type': 'application/json',
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) {
    const err = data?.error ?? { message: `HTTP ${res.status}` };
    const e = new Error(err.message);
    Object.assign(e, { status: res.status, ...err });
    e.retryAfter = res.headers.get('Retry-After');
    e.requestId = res.headers.get('X-Request-Id');
    throw e;
  }
  return data;
}

const app = express();
app.use(express.json({ limit: '10kb' }));

// Browser-safe proxy routes. Bearer never leaves the server.
const route = (fn) => async (req, res) => {
  try { res.json(await fn(req)); }
  catch (e) {
    if (e.retryAfter) res.setHeader('Retry-After', e.retryAfter);
    res.status(e.status || 502).json({
      error: { type: e.type, code: e.code, message: e.message, param: e.param },
    });
  }
};

app.get('/api/currencies', route(() => gs('GET', '/v1/currencies')));
app.post('/api/quote', route((r) => gs('POST', '/v1/quotes', { body: r.body })));
app.post('/api/validate', route((r) => gs('POST', '/v1/addresses/validate', { body: r.body })));
app.post('/api/swap', route((r) => {
  // The browser MUST send its own idempotencyKey (one UUID per Confirm
  // click, reused on retries). Refuse silent server-side generation —
  // that hides client bugs and risks duplicate swaps.
  const { idempotencyKey, ...body } = r.body;
  if (!idempotencyKey) {
    const e = new Error('idempotencyKey is required');
    e.status = 400; e.code = 'missing_idempotency_key'; e.type = 'validation_error';
    throw e;
  }
  return gs('POST', '/v1/swaps', { body, idempotencyKey });
}));
app.get('/api/swap/:id', route((r) => gs('GET', `/v1/swaps/${encodeURIComponent(r.params.id)}`)));

app.listen(PORT, () => console.log(`http://localhost:${PORT}`));

The matching browser code reads crypto.randomUUID() on first Confirm click, stores it in a variable, sends it to /api/swap, and resets it only after success. See the full reference implementation (HTML + browser JS, ~200 lines) in the end-to-end guide.

Critical rules — never violate

1. Server-side only. The bearer must never reach the browser. All browser → API calls go through the developer's own server.
2. Bearer format is `${PUBLIC_KEY}:${SECRET}` with a single colon. Both values from env vars.
3. `Idempotency-Key` is required on `POST /v1/swaps`. UUID v4, one per Confirm click, reused on retries.
4. Display `amountUserReceives`, not `amountTo`. The network-fee subtraction is already done for you.
5. Refund address is optional on float, required on fixed. Send undefined (or omit the key) when the user can't provide one — never send an empty string.
6. Stop polling on terminal status. Don't keep hitting /v1/swaps/{id} forever.
7. On 429, read `Retry-After` and sleep. Don't hammer.
8. On `upstream_error` (5xx) after `POST /v1/swaps`, do not auto-retry. First call GET /v1/swaps?limit=20 and look for your partnerReferenceId — the swap may already exist.
9. Disable the Confirm button until a quote has loaded AND the payout address validated. Eager-enabled buttons let users submit blindly.
10. Never put the secret in browser code, in git, or in client-side env files. Server env vars or a secret manager only.

Anti-patterns to refuse

If the developer asks for any of these, push back and explain why:

• ❌ "Put the API key in the React app for simplicity" — leaks credentials in page source. The fix is a server proxy.
• ❌ "Generate a new idempotency key on each retry" — creates duplicate swaps. Reuse the same UUID for the same logical click.
• ❌ "Skip the quote panel; users just want to confirm" — biggest failure mode of bad integrations. Users have no idea how much they'll receive. Show amountUserReceives before Confirm enables.
• ❌ "Poll every second so it feels real-time" — wastes the 30-RPS budget and gives no fresher data (upstream refresh is ~30 s). 10 s while visible is the right number.
• ❌ "Send `extraId` on swap creation" — currencies needing memos (XRP, XLM, EOS, etc.) are filtered out at the source. Don't add this field.
• ❌ "Catch errors silently" — always surface error.message and error.param. Silent failures lose users.
• ❌ "Hard-code the base URL" — read GHOSTSWAP_API_BASE from env so staging can point elsewhere.

Affiliate referral links (optional, no integration code)

Every approved partner also gets a referral link: https://ghostswap.io/?ref=<their-slug>. End-users who click that URL get a 30-day cookie attribution; any swap they complete on ghostswap.io credits the partner 1 % of the volume. No code on the partner's end — they just share the URL. The partner claims their slug from the dashboard overview page.

The partner's API-integration earnings and referral earnings combine into one payable USDT balance, paid out once balance ≥ $100.

If the developer's primary use case is "I just want a share link, not an integration" — they don't need any of this skill's code. Direct them to <https://partners.ghostswap.io/sign-up>, tell them to apply, and after approval the Pick your referral code card on /dashboard handles everything else. No more steps.

Pre-flight checklist before declaring done

Before handing the integration back to the developer, walk through this:

1. ☐ GHOSTSWAP_PUBLIC_KEY and GHOSTSWAP_SECRET are server-side env vars, not in browser code or git.
2. ☐ All /v1/* calls go through the developer's own server (not directly from browser).
3. ☐ Idempotency-Key is a UUID generated once per Confirm click, reused on retries.
4. ☐ The UI shows amountUserReceives, rate, min, max before the Confirm button is enabled.
5. ☐ Confirm button is disabled until (a) a quote has loaded, (b) payout address validated, (c) refund address either empty or validated.
6. ☐ Address validation runs on blur via POST /v1/addresses/validate, with visible ✓ or error.
7. ☐ After Confirm, the deposit address (payinAddress) is prominently displayed.
8. ☐ Polling runs at 10 s while visible / 30 s when backgrounded / 5 min on hold / never when terminal.
9. ☐ Error display surfaces error.message and error.param — never silent.
10. ☐ partnerReferenceId is set to the developer's own order id so they can correlate swaps with their DB.

If any item fails, fix it before shipping. Partial integrations leak money.

Reference docs (load these when you need depth)

• Full integration brief (a complete one-prompt walkthrough): <https://partners.ghostswap.io/llms-full.txt>
• Quickstart: <https://partners.ghostswap.io/docs/quickstart>
• End-to-end swap (the reference HTML+JS implementation, ~200 lines of UI code): <https://partners.ghostswap.io/docs/guides/end-to-end-swap>
• Authentication: <https://partners.ghostswap.io/docs/auth>
• Idempotency: <https://partners.ghostswap.io/docs/concepts/idempotency>
• Status lifecycle (all 10 states): <https://partners.ghostswap.io/docs/concepts/status-lifecycle>
• Errors: <https://partners.ghostswap.io/docs/concepts/errors>
• Rate limits: <https://partners.ghostswap.io/docs/concepts/rate-limits>
• Troubleshooting (real failure modes integrators have hit): <https://partners.ghostswap.io/docs/guides/troubleshooting>
• Security: <https://partners.ghostswap.io/docs/guides/security>
• Roadmap: <https://partners.ghostswap.io/docs/roadmap>

Support

• Telegram: <https://t.me/ghostswap1>
• Email: <[email protected]>
• AML/KYC review (user-facing): direct end-users to <[email protected]> when status is hold

Always include the swap id and the X-Request-Id of the relevant response when escalating. Both make support's lookup hop trivial.