GhostSwap Partners API

Build crypto-to-crypto swap flows into your product with a single Bearer-authenticated REST API. Server-to-server, idempotent, rate-limited, with a polled status lifecycle. No signing keys to manage — GhostSwap handles liquidity routing on your behalf.

Quickstart →

Five steps from credential to live swap. cURL + JavaScript.

Authentication →

How to issue, rotate, and protect your API credentials.

Swaps API →

Create, list, and inspect swaps. Idempotent by default.

End-to-end guide →

Full walkthrough: quote → validate → create → poll.

What you get

  • One Bearer token, one base URL. No JSON-RPC. No upstream key management.
  • Idempotent swap creation. Safe to retry. We deduplicate on (credential, Idempotency-Key) for 24 hours.
  • Generous rate limits — 120 RPS per source IP and 30 RPS per credential, both enforced today. Standard RateLimit-* headers on every response so your client can self-throttle. See Rate limits for retry guidance. We absorb upstream limits so your traffic stays smooth.
  • Real-time-ish status polling. Background workers update swap status every 30s upstream; poll every 10s while the user is watching and 30s in background/server-side jobs.
  • Per-organization attribution. Every swap is tagged with your org_id so commission tracking is automatic.

How a swap works

  1. Your server calls POST /v1/quotes with the pair and amount. We return the user-facing receive amount.
  2. Your server calls POST /v1/addresses/validate to check the user's payout wallet.
  3. Your server calls POST /v1/swaps with an Idempotency-Key. We return a deposit address.
  4. You display the deposit address to your user. They send the funds on chain.
  5. Your server polls GET /v1/swaps/:id until the status is terminal.
  6. On finished, you credit your user using the actual settlement fields (amountActualFrom, amountActualTo, hashes). We've already credited your commission ledger from the actual amount received.

Available integration

The server-to-server API is the production launch surface. Hosted widgets are temporarily unavailable while we harden the signed-session model.

Need help?

Ping us on Telegram for quick integration questions, or email support@ghostswap.io for anything else — credentials, payouts, paper-trail issues, or AML/KYC holds on individual swaps (these are routed to our compliance team). Partners with a dashboard login can also use /dashboard/help.