Partner API

Integrate CoinSwap's aggregated exchange routes into your own product. Four endpoints: list currencies, compare routes, create an exchange, track an order.

Authentication

Every request needs an API key sent in the X-Api-Key header. Keys look like cs_live_… and are issued by our team — requests without a valid key get a 401 response.

Rate limits & errors

Rate quotes are limited to 60 requests per minute per key and exchange creation to 20 per minute. Errors always come back as a JSON error object with code and message fields. Routes are anonymous — you only ever see stable numeric route IDs, never provider names.

Want an API key? Reach out via the contact details in the FAQ and we will set you up.

Endpoint reference

GET/api/v1/currencies

List all supported currencies (symbol + canonical network slug).

Request

curl https://coinswap.now/api/v1/currencies \
  -H 'X-Api-Key: cs_live_YOUR_KEY'

Response 200

{
  "currencies": [
    { "symbol": "BTC", "network": "bitcoin", "name": "Bitcoin", "networkName": "Bitcoin" },
    { "symbol": "ETH", "network": "ethereum", "name": "Ethereum", "networkName": "Ethereum" }
  ]
}

POST/api/v1/rate

Compare all available routes for a pair and amount. Routes are anonymized numeric IDs; "best" points at the highest payout. All amounts are decimal strings. Limit: 60 req/min per key.

Request

curl -X POST https://coinswap.now/api/v1/rate \
  -H 'X-Api-Key: cs_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": { "symbol": "BTC", "network": "bitcoin" },
    "to":   { "symbol": "ETH", "network": "ethereum" },
    "amount": "0.5",
    "rateType": "float"
  }'

Response 200

{
  "routes": [
    {
      "routeId": 2,
      "kind": "cex",
      "rateType": "float",
      "toAmount": "9.87654321",
      "etaSeconds": 600,
      "expiresAt": "2026-07-19T12:34:56.000Z",
      "tags": ["best"]
    }
  ],
  "best": 2
}

POST/api/v1/exchange

Create an exchange. Same body as /rate plus payout details. Omit routeId to auto-pick the best route. v1 supports walletless (CEX-style) routes only — DEX routes return error code "route_not_supported". Limit: 20 req/min per key.

Request

curl -X POST https://coinswap.now/api/v1/exchange \
  -H 'X-Api-Key: cs_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": { "symbol": "BTC", "network": "bitcoin" },
    "to":   { "symbol": "ETH", "network": "ethereum" },
    "amount": "0.5",
    "rateType": "float",
    "toAddress": "0xYourPayoutAddress",
    "refundAddress": "bc1qYourRefundAddress",
    "routeId": 2
  }'

Response 200

{
  "orderId": "CSABCDE12345",
  "deposit": {
    "address": "bc1q…",
    "memo": null,
    "amount": "0.5",
    "expiresAt": "2026-07-19T13:00:00.000Z"
  }
}

GET/api/v1/order/{id}

Track an order. Statuses: awaiting_deposit → confirming → exchanging → sending → completed (or refunded / failed / expired / hold_kyc).

Request

curl https://coinswap.now/api/v1/order/CSABCDE12345 \
  -H 'X-Api-Key: cs_live_YOUR_KEY'

Response 200

{
  "order": {
    "id": "CSABCDE12345",
    "type": "cex",
    "routeId": 2,
    "routeNumber": 2,
    "providerTitle": "Route 2",
    "from": { "symbol": "BTC", "network": "bitcoin", "amount": "0.5" },
    "to": { "symbol": "ETH", "network": "ethereum", "expectedAmount": "9.87654321", "address": "0x…" },
    "status": "awaiting_deposit",
    "depositAddress": "bc1q…",
    "depositMemo": null,
    "payoutTxHash": null,
    "expiresAt": "2026-07-19T13:00:00.000Z",
    "createdAt": "2026-07-19T12:35:00.000Z",
    "timeline": [{ "at": "2026-07-19T12:35:00.000Z", "status": "awaiting_deposit" }]
  }
}

Embed widget

Drop the CoinSwap swap widget into your site with an iframe or a one-line script. It works with no developer key at all, at our standard rate. Add your cs_live_ key only if you want your own markup and order attribution.

No key required — it just works

Embed the widget without an apiKey and it runs immediately at CoinSwap's standard rate: real anonymized routes, real orders, no signup. We keep our usual platform markup, so there is nothing to configure.

Optional: publishable embed key

Add your cs_live_ key to apply your own markup on top and attribute orders to your account. The apiKey in an embed URL is visible to visitors by design — it only fetches quotes with your markup and creates attributed orders; it cannot read your orders, change settings, or issue keys. Use a separate key per site so you can disable it on its own. An invalid or disabled key shows an "unavailable" state — remove it to fall back to the keyless widget.

URL parameters

`apiKey`	Optional. Your publishable cs_live_ embed key — applies your markup and attributes orders. Omit it and the widget works at our standard rate.
`from`	Default "send" asset symbol, e.g. BTC.
`to`	Default "receive" asset symbol, e.g. ETH.
`amount`	Pre-filled send amount (decimal string).
`rateType`	float \| fixed. Default float.
`side`	send \| receive. Default send.
`theme`	auto \| light \| dark. Default auto (follows the device).
`layout`	compact \| list \| horizontal. Default compact — controls the widget height.
`lang`	en \| zh \| ru \| es. Default en.
`accent`	Hex colour to override the accent for white-label, e.g. #7c3aed.

layout controls the widget's height: compact (default) shows just the best rate with a tap to compare routes, list stacks the routes, and horizontal shows them as one scrolling row.

Option A — plain iframe

Paste this where the widget should appear. Set from and to to your default pair; visitors can change them.

HTML — no key (our standard rate)

<iframe
  src="https://coinswap.now/embed?from=BTC&to=ETH"
  style="width:100%;max-width:480px;height:640px;border:0"
  title="CoinSwap swap widget"
></iframe>

HTML — with your key (your markup + attribution)

<iframe
  src="https://coinswap.now/embed?apiKey=cs_live_YOUR_KEY&from=BTC&to=ETH"
  style="width:100%;max-width:480px;height:640px;border:0"
  title="CoinSwap swap widget"
></iframe>

Option B — script loader

The loader finds every element with data-coinswap-embed and injects a responsive iframe that auto-resizes to its content.

HTML

<div
  data-coinswap-embed
  data-from="BTC"
  data-to="ETH"
  data-theme="auto"
  data-lang="en"
></div>
<script src="https://coinswap.now/embed.js" async></script>

The widget reports its height to the parent page and the loader resizes the iframe to match, so there is no inner scrollbar.