API documentation

Overview

JSON over HTTPS. Coin amounts are decimal strings in coin units ("0.015"), never floats. US dollar values are numbers. Times are ISO 8601 strings in UTC. A coin on a particular network is a method, with an id such as btc, eth-base or usdt-tron: use those ids for from and to.

Sandbox

A build running in sim mode is the sandbox: every chain is simulated and no real coins move. The same endpoints work, plus two developer helpers that only exist outside mainnet: POST /api/dev/deposit sends a test deposit to an order (with a clean, high_risk or sanctioned scenario) and POST /api/dev/mine mines blocks so it confirms. GET /api/v1/meta tells you which mode you are talking to.

BASE=http://localhost:4200
curl -s -X POST "$BASE/api/dev/deposit" -H "content-type: application/json" \
  -d '{"orderId":"ORDER_ID","scenario":"clean"}'
curl -s -X POST "$BASE/api/dev/mine" -H "content-type: application/json" -d '{"blocks":3}'

Authentication

Partner requests carry an API key in the x-api-key header (Authorization: Bearer also works). Keys look like pxk_<prefix>_<secret>, are created in the admin console and are shown only once. Requests without a key are treated as a regular visitor with no commission. A wrong or switched-off key gets 401 invalid_api_key.

End-user IP

Country rules apply to the person swapping, not to your server. With an API key, every request that prices or creates something must send that person's public IP address in x-user-ip. Requests without it fail with user_ip_required, and private or reserved addresses with user_ip_invalid.

Rate limits

Limits count requests per IP address (your end user's, with an API key). Going over returns HTTP 429 with the code rate_limited. Endpoints not listed here have no fixed limit, but cache /api/v1/coins: it changes rarely.

Two more limits protect the service: at most 10 new orders per device per hour (velocity_limit), and at most 6 open live streams per IP address (too_many_streams).

Endpoints

Request and response fields are in the OpenAPI document. The TypeScript types live in src/lib/api-types.ts in this project.

Fixed-rate flow

Lock the price first, then create the order within the quote's lifetime. The user must send exactly depositAmount, and receives exactly settleAmount: network fees are already taken off. You can quote by the amount sent (depositAmount) or by the amount received (settleAmount), not both.

curl -s "$BASE/api/v1/quotes" \
  -H "content-type: application/json" \
  -H "x-api-key: $PX_KEY" \
  -H "x-user-ip: 203.0.113.7" \
  -d '{"from":"btc","to":"usdt-tron","depositAmount":"0.005"}'

{
  "id": "q_zp4h32n4f18gsz53",
  "from": "btc",
  "to": "usdt-tron",
  "depositAmount": "0.005",
  "settleAmount": "407.417394",
  "rate": "81831.8587259",
  "expiresAt": "2026-10-13T15:58:54.958Z",
  "fees": {
    "receiveFeeUsd": 0.3, "sendFeeUsd": 1.44, "totalNetworkFeesUsd": 1.74,
    "sendFeeInSettle": "1.441572", "networkFeesInSettle": "1.741899",
    "spreadBps": 180, "commissionBps": 0,
    "spreadParts": { "tierBps": 150, "fixedBps": 30, "volatilityBps": 0, "surchargeBps": 0, "nudgeBps": 0, "minEarningsBps": 0 }
  }
}

curl -s "$BASE/api/v1/orders" \
  -H "content-type: application/json" \
  -H "x-api-key: $PX_KEY" \
  -H "x-user-ip: 203.0.113.7" \
  -d '{
    "type": "fixed",
    "quoteId": "q_zp4h32n4f18gsz53",
    "settleAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "refundAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    "payoutDestination": "self_hosted",
    "acceptTerms": true
  }'

The response holds order (show order.depositAddress, order.depositMemo when set, and order.expectedDeposit) and orderToken. When depositAddress is null, the user must verify their identity first: start it with POST /api/v1/orders/:id/kyc.

Variable-rate flow

No quote. Create the order with from and to. The user can send any amount between order.depositMin and order.depositMax; the rate is set when each deposit confirms. GET /api/v1/pair with an amount gives an estimate to show beforehand.

curl -s "$BASE/api/v1/orders" \
  -H "content-type: application/json" \
  -H "x-api-key: $PX_KEY" \
  -H "x-user-ip: 203.0.113.7" \
  -d '{"type":"variable","from":"eth","to":"sol","settleAddress":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","acceptTerms":true}'

Payouts to an exchange account: send "payoutDestination": "exchange". If the swap can reach the travel-rule threshold, also send beneficiary: { name, vaspName }, the account holder's full name and the exchange's name. See the compliance policy for the threshold.

Order token

orderToken is returned once, when the order is created. Store it with the order. Send it as x-order-token to set a refund address, cancel, start identity verification or send travel-rule details. Anyone with the order id can read the order, with addresses shortened; the token holder (or the partner whose key created the order) sees them in full and can change the order.

Order statuses

Follow an order with the event stream (GET /api/v1/orders/:id/stream, an order event with the full order on connect and on every change), by polling GET /api/v1/orders/:id every few seconds, or with webhooks. When a deposit leaves the normal path, deposit.reason names why and deposit.reasonText explains it in plain English. Reviews with manualDecision: true have no automatic refund deadline: a person decides.

Payment links

A payment link says pay me exactly 25 USDT on Tron at this address. Whoever pays can use any coin we support: they get a fixed-rate quote for exactly that amount, and their payment is a normal fixed-rate swap whose payout goes to the link's address. The payer pays our spread and the network fees; the recipient gets the stated amount. Links created with your API key belong to you and send payment_link.* webhooks.

curl -s -X POST "$BASE/api/v1/payment-links" \
  -H "content-type: application/json" \
  -H "x-api-key: $PX_KEY" \
  -H "x-user-ip: 203.0.113.7" \
  -d '{
    "title": "Invoice 1042",
    "settleMethodId": "usdt-tron",
    "settleAmount": "25",
    "settleAddress": "TBFQ4wTTgtsK4SvFuBNVCbhHJPbWdxE9zN",
    "expiresIn": "7d",
    "payoutDestination": "self_hosted"
  }'

The response has link, payUrl (share it) and manageToken with manageUrl (shown once: keep them private). One-payment links (the default) take one payment at a time and are paid once it settles; reusable links ("reusable": true) take any number of full payments. Expiry: 1h, 24h, 7d, 30d or never.

curl -s -X POST "$BASE/api/v1/payment-links/pl_pztpm3f8c04ez2/quote" \
  -H "content-type: application/json" -d '{"from":"btc"}'

curl -s -X POST "$BASE/api/v1/payment-links/pl_pztpm3f8c04ez2/orders" \
  -H "content-type: application/json" \
  -d '{"from":"btc","quoteId":"q_h9tga45ztbr27xdk","refundAddress":"bc1q...","acceptTerms":true}'

curl -s "$BASE/api/v1/payment-links/pl_pztpm3f8c04ez2/payments" -H "x-link-token: $MANAGE_TOKEN"
curl -s -X POST "$BASE/api/v1/payment-links/pl_pztpm3f8c04ez2/cancel" -H "x-link-token: $MANAGE_TOKEN"

GET /api/v1/payment-links/:id is public (no secrets, no payer details). Its availability says whether a payment can start now and, if not, why: paid, expired, cancelled, payment_open (someone else has an open order, with retryAfter), payment_in_progress or unavailable. Every payer goes through the same country rules, limits and screening as any other swap.

Webhooks

Set a webhook URL on your partner account. We POST JSON to it for these events. Each body is { "event", "createdAt", "data" }.

{
  "event": "deposit.settled",
  "createdAt": "2026-10-13T15:40:02.114Z",
  "data": { "orderId": "82mvk6s12m9sz0", "depositId": "d_ac88wy833k5h8tb4", "message": "Sent 0.0033 ETH to your address." }
}

{
  "event": "payment_link.paid",
  "createdAt": "2026-10-13T20:02:30.101Z",
  "data": {
    "linkId": "pl_pztpm3f8c04ez2", "status": "paid", "title": "Invoice 1042",
    "settleMethodId": "usdt-tron", "settleAmount": "25", "amountReceived": "25.000112",
    "orderId": "d29k7x4wbq5psa", "depositId": "d_f9wvve7nksmtjwc0",
    "settleTxid": "634b39ce...", "paidAt": "2026-10-13T20:02:25.573Z"
  }
}

Every request carries x-px-signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of t + "." + body using your webhook secret. Check it against the raw body before you parse it, and reject old timestamps. Answer with any 2xx status within 8 seconds; failed deliveries are retried with growing gaps, up to 10 attempts over several hours, so the same event can arrive twice. Use the ids to ignore repeats.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyPlaxswapSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Embeddable widget

Put a small swap box on your own site. It shows two coins, an amount and the live rate. There is no address field in it: Continue opens the swap page in a new tab with the pair and amount filled in, where your visitor adds their address and checks every detail. Pass your referral code with ref.

URL: /widget?from=btc&to=eth&amount=0.01&theme=auto&ref=CODE. from and to take method ids or coins, theme is light, dark or auto (follows your visitor's system setting). A frame of about 400 by 460 pixels fits it.

<iframe
  src="https://plaxswap.com/widget?from=btc&amp;to=eth&amp;amount=0.01"
  title="Crypto swap"
  width="400" height="460"
  style="border:0;border-radius:20px;max-width:100%"
  loading="lazy"
  sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox"
></iframe>

Errors

Errors use HTTP status codes and a JSON body: { "error": { "code", "message", "details" } }. The message is plain English and safe to show to your user. Codes you will see most:

The full list for each endpoint is in the OpenAPI document.