API documentation

Overview

Base URL: https://anonchange.com/api/partner/v1

• Every endpoint is a POST with a JSON body and Content-Type: application/json. Send {} when an endpoint has no fields. Unknown fields are rejected.
• Every request is signed with your API secret (see Authentication).
• Success responses are plain JSON. Errors are { "error": "message" } with an HTTP status code.
• Amounts are decimal strings ("0.01"), never numbers, in whole coins. Percentages and counts are numbers. Times are ISO 8601 in UTC.
• Coins are identified by their code from currencies, for example BTC, XMR or USDT_SOL (USDT on Solana).

Retry 429 and 503 later with a new nonce and timestamp. Rarely, a 429 or 503 comes from our proxy as plain text instead of JSON.

Getting started

• Create a partner account (or log in to an existing one). It is self-service and needs only a password: your account ID is your username. Store both safely, a lost password cannot be reset.
• You get an API key and an API secret. The secret is shown once; you can replace it with a new one in your dashboard at any time (the old one then stops working).
• Call currencies and price to test your signature, then create orders and poll their status.

Authentication

Every request carries four headers:

Signed stringCopy

${timestamp}\n${nonce}\nPOST\n${path}\n${idempotencyKey}\n${sha256hex(body)}

• \n is a single newline character, with no newline at the end.
• nonce is the exact X-API-NONCE header. idempotencyKey is the exact Idempotency-Key header, or an empty string when absent. Keep that empty line in the signature. Generate a new nonce and signature for retries, keeping the same idempotency key.
• path is the request path including /api/partner/v1, for example /api/partner/v1/price: exactly the path you request. Send no query string and no trailing slash. The method is always POST.
• sha256hex(body) is the lowercase hex SHA-256 of the exact body bytes you send. Serialize the JSON once and send that same string: re-serializing can change spacing or key order and break the signature.

A complete signed request (the Node.js and Python versions define a call helper used below):

curlNode.jsPython

Copy

API_KEY="ak_your_api_key"
API_SECRET="your_api_secret"
REQ_PATH="/api/partner/v1/price"
BODY='{"from":"BTC","to":"XMR","rateType":"float","amount":"0.01"}'

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
IDEMPOTENCY_KEY=""
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIGN=$(printf '%s\n%s\nPOST\n%s\n%s\n%s' "$TS" "$NONCE" "$REQ_PATH" "$IDEMPOTENCY_KEY" "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -sS -X POST "https://anonchange.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "X-API-TIMESTAMP: $TS" \
  -H "X-API-NONCE: $NONCE" \
  -H "X-API-SIGN: $SIGN" \
  --data-binary "$BODY"

OpenAPI and Postman

The whole API as an OpenAPI 3.1 spec (for code generators and API tools) and as a Postman collection.

• Postman: import the collection, then set the collection variables apiKey and apiSecret. Its pre-request script signs every request, so they work as they are.
• Generated clients from the OpenAPI spec still need to sign each request as described in Authentication.

Postman pre-request script (included in the collection)Copy

const body = pm.request.body && pm.request.body.raw ? pm.variables.replaceIn(pm.request.body.raw) : "";
const timestamp = String(Math.floor(Date.now() / 1000));
const path = "/" + pm.request.url.path.join("/");
const nonce = CryptoJS.lib.WordArray.random(16).toString();
const idempotencyKey = pm.variables.replaceIn(pm.request.headers.get("Idempotency-Key") || "");
const signed = timestamp + "\n" + nonce + "\nPOST\n" + path + "\n" + idempotencyKey + "\n" + CryptoJS.SHA256(body).toString();
pm.request.body.update(body);
pm.request.headers.upsert({ key: "X-API-KEY", value: pm.variables.get("apiKey") });
pm.request.headers.upsert({ key: "X-API-TIMESTAMP", value: timestamp });
pm.request.headers.upsert({ key: "X-API-NONCE", value: nonce });
pm.request.headers.upsert({ key: "X-API-SIGN", value: CryptoJS.HmacSHA256(signed, pm.variables.get("apiSecret")).toString() });

Currencies

All coins with their limits. Body: {}. Only coins with enabled: true can be exchanged right now.

Response 200Copy

[
  {
    "coin": "BTC",
    "name": "Bitcoin",
    "decimals": 8,
    "enabled": true,
    "minDeposit": "0.0002",
    "confirmations": 2,
    "networkFee": "0.00003",
    "usd": "67012.4",
    "reserve": "1.84213"
  },
  {
    "coin": "XMR",
    "name": "Monero",
    "decimals": 12,
    "enabled": true,
    "minDeposit": "0.02",
    "confirmations": 10,
    "networkFee": "0.0002",
    "usd": "163.21",
    "reserve": "412.5"
  }
]

Pairs

Every pair of enabled coins and the rate types it supports. Body: {}.

Response 200Copy

[
  {
    "from": "BTC",
    "to": "XMR",
    "rateTypes": [
      "float",
      "fixed"
    ]
  },
  {
    "from": "XMR",
    "to": "BTC",
    "rateTypes": [
      "float",
      "fixed"
    ]
  }
]

Price

A quote for a pair. Nothing is reserved: create the order to get a deposit address.

RequestCopy

{
  "from": "BTC",
  "to": "XMR",
  "rateType": "fixed",
  "amount": "0.01"
}

Response 200Copy

{
  "from": "BTC",
  "to": "XMR",
  "rateType": "fixed",
  "amountIn": "0.01",
  "amountOut": "4.044423745",
  "rate": "410.6217",
  "feePercent": 1.5,
  "networkFee": "0.0002",
  "minDeposit": "0.0002",
  "maxDeposit": "0.45",
  "rateLockMinutes": 10,
  "maxRateDriftPercent": 1.2
}

• amountOut is what the customer receives, after feePercent and networkFee. rate is our exchange rate before fees.
• feePercent already includes your own markup (see Affiliate program), so show it as it is.
• minDeposit and maxDeposit are the deposit limits for this pair right now; the maximum follows our reserve of the receiving coin.
• rateLockMinutes (fixed only): how long a fixed rate stays locked after the order is created. maxRateDriftPercent: how far the market may move against the quote before the customer is asked (see Order lifecycle).

Create an order

Optional header Idempotency-Key: 8-128 characters (A-Z, a-z, 0-9, - and _), unique per order on your side. If a create times out, send it again with the same key: you get the order made the first time, with status 200 instead of 201. The retry's body is not compared, so use a new key for every new order.

RequestCopy

{
  "from": "BTC",
  "to": "XMR",
  "rateType": "fixed",
  "amount": "0.01",
  "payoutAddress": "<customer's XMR address>",
  "refundAddress": "<customer's BTC address>"
}

Response 201Copy

{
  "id": "3f6c1a52-8d1e-4b7a-9c35-2f0e6b9d4a17",
  "status": "awaiting_deposit",
  "from": "BTC",
  "to": "XMR",
  "rateType": "fixed",
  "depositAddress": "<BTC deposit address>",
  "payoutAddress": "<customer's XMR address>",
  "refundAddress": "<customer's BTC address>",
  "quote": {
    "amountIn": "0.01",
    "amountOut": "4.044423745",
    "rate": "410.6217"
  },
  "amountIn": null,
  "amountOut": null,
  "rate": null,
  "feePercent": 1.5,
  "networkFee": "0.0002",
  "requiredConfirmations": 2,
  "deposits": [],
  "payout": null,
  "pendingDeposit": null,
  "continuing": false,
  "actions": {
    "continue": false,
    "refund": false
  },
  "refund": null,
  "note": null,
  "guarantee": "-----BEGIN PGP SIGNED MESSAGE-----\n…\n-----END PGP SIGNATURE-----",
  "rateLockedUntil": "2026-10-19T12:10:00.000Z",
  "expiresAt": "2026-10-19T12:10:00.000Z",
  "createdAt": "2026-10-19T12:00:00.000Z",
  "completedAt": null,
  "viewKey": "<view key>",
  "url": "https://anonchange.com/order/3f6c1a52-8d1e-4b7a-9c35-2f0e6b9d4a17#key=<view key>"
}

• The response is the order (fields under Order status) plus viewKey and url.
• url is the customer's order page. The key after #key= stays in the browser and lets it show the order's addresses and transactions; without the key these are hidden after 36 hours. Give the link to your customer or build your own status page.
• viewKey and url are returned only on the first 201 response. A retry with the same Idempotency-Key returns the order without them, so store them right away.
• Show the customer depositAddress, the amount to send and expiresAt. Only the from coin on its own network is credited.

curlNode.jsPython

Copy

API_KEY="ak_your_api_key"
API_SECRET="your_api_secret"
REQ_PATH="/api/partner/v1/create"
BODY='{"from":"BTC","to":"XMR","rateType":"fixed","amount":"0.01","payoutAddress":"<customer XMR address>","refundAddress":"<customer BTC address>"}'

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
IDEMPOTENCY_KEY="checkout-1234"
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIGN=$(printf '%s\n%s\nPOST\n%s\n%s\n%s' "$TS" "$NONCE" "$REQ_PATH" "$IDEMPOTENCY_KEY" "$BODY_HASH" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')

curl -sS -X POST "https://anonchange.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "X-API-TIMESTAMP: $TS" \
  -H "X-API-NONCE: $NONCE" \
  -H "X-API-SIGN: $SIGN" \
  -H "Idempotency-Key: checkout-1234" \
  --data-binary "$BODY"

Order status

The current state of one of your orders. Body: { "id": "3f6c1a52-8d1e-4b7a-9c35-2f0e6b9d4a17" }. You always get the full order, with addresses, transaction IDs and the letter of guarantee.

Response 200Copy

{
  "id": "3f6c1a52-8d1e-4b7a-9c35-2f0e6b9d4a17",
  "status": "completed",
  "from": "BTC",
  "to": "XMR",
  "rateType": "fixed",
  "depositAddress": "<BTC deposit address>",
  "payoutAddress": "<customer's XMR address>",
  "refundAddress": "<customer's BTC address>",
  "quote": {
    "amountIn": "0.01",
    "amountOut": "4.044423745",
    "rate": "410.6217"
  },
  "amountIn": "0.01",
  "amountOut": "4.044423745",
  "rate": "410.6217",
  "feePercent": 1.5,
  "networkFee": "0.0002",
  "requiredConfirmations": 2,
  "deposits": [
    {
      "txid": "<deposit txid>",
      "amount": "0.01",
      "confirmations": 2,
      "credited": true,
      "seenAt": "2026-10-19T12:04:12.000Z"
    }
  ],
  "payout": {
    "status": "confirmed",
    "amount": "4.044423745",
    "txid": "<payout txid>",
    "broadcastAt": "2026-10-19T12:31:40.000Z",
    "confirmedAt": "2026-10-19T12:52:03.000Z"
  },
  "pendingDeposit": null,
  "continuing": false,
  "actions": {
    "continue": false,
    "refund": false
  },
  "refund": null,
  "note": null,
  "guarantee": "-----BEGIN PGP SIGNED MESSAGE-----\n…\n-----END PGP SIGNATURE-----",
  "rateLockedUntil": "2026-10-19T12:10:00.000Z",
  "expiresAt": "2026-10-19T12:10:00.000Z",
  "createdAt": "2026-10-19T12:00:00.000Z",
  "completedAt": "2026-10-19T12:52:03.000Z"
}

List orders

Your API orders, newest first. While more is true, ask for the next page with before set to the last id you got. Your dashboard also lists the orders from your referral link and exports everything as CSV.

RequestCopy

{
  "limit": 2
}

Response 200Copy

{
  "orders": [
    {
      "id": "3f6c1a52-8d1e-4b7a-9c35-2f0e6b9d4a17",
      "status": "completed",
      "from": "BTC",
      "to": "XMR",
      "rateType": "fixed",
      "amountIn": "0.01",
      "amountOut": "2.93811204",
      "feePercent": 1.5,
      "markupPercent": 0.5,
      "source": "api",
      "earningUsd": "4.84",
      "createdAt": "2026-10-19T10:02:11.000Z",
      "completedAt": "2026-10-19T10:31:40.000Z"
    },
    {
      "id": "9b2e7c40-1f3a-4d6e-8a51-7c0d2e4f6a18",
      "status": "awaiting_deposit",
      "from": "LTC",
      "to": "XMR",
      "rateType": "float",
      "amountIn": null,
      "amountOut": null,
      "feePercent": 1.5,
      "markupPercent": 0,
      "source": "api",
      "earningUsd": null,
      "createdAt": "2026-10-19T09:48:03.000Z",
      "completedAt": null
    }
  ],
  "more": true
}

earningUsd is set once an order completes. Orders from your referral link belong to their customers: in the dashboard and CSV they have no id or amounts and only the date.

Continue or refund

If the market rate moves against the quote by more than maxRateDriftPercent before the deposit is confirmed, the order stops in refund_required and waits for the customer. Ask them, then call one of these with { "id": "…" }. A deposit that cannot be exchanged (below the minimum, or too small to pay out) also stops in refund_required, with only actions.refund.

• continue (when actions.continue is true): exchange at the market rate. The order shows continuing: true (both actions false) until it settles at a price fetched after the call, usually within a minute.
• refund (when actions.refund is true): send the deposit back to the order's refund address, minus the network fee. Only possible if the order has a refund address.

Status while waiting (excerpt)Copy

{
  "id": "3f6c1a52-8d1e-4b7a-9c35-2f0e6b9d4a17",
  "status": "refund_required",
  "continuing": false,
  "actions": {
    "continue": true,
    "refund": true
  },
  "note": "Market rate moved by 1.6% since your quote"
}

Both return the updated order (after continue still refund_required, with continuing: true). When the matching action is false you get 409. If neither action is true, the order needs our support team. After continue the order goes on like any other (it can still be held for review).

Webhooks

Pass webhookUrl to create and we POST the order to it right after creation, whenever its status changes and when its deposit is first seen, instead of you polling status. The order is the same JSON as status returns.

Webhook bodyCopy

{
  "event": "order.updated",
  "order": {
    "id": "3f6c1a52-8d1e-4b7a-9c35-2f0e6b9d4a17",
    "status": "confirming",
    "from": "BTC",
    "to": "XMR",
    "rateType": "fixed",
    "depositAddress": "<BTC deposit address>",
    "payoutAddress": "<customer's XMR address>",
    "refundAddress": "<customer's BTC address>",
    "quote": {
      "amountIn": "0.01",
      "amountOut": "4.044423745",
      "rate": "410.6217"
    },
    "amountIn": null,
    "amountOut": null,
    "rate": null,
    "feePercent": 1.5,
    "networkFee": "0.0002",
    "requiredConfirmations": 2,
    "deposits": [],
    "payout": null,
    "pendingDeposit": null,
    "continuing": false,
    "actions": {
      "continue": false,
      "refund": false
    },
    "refund": null,
    "note": null,
    "guarantee": "-----BEGIN PGP SIGNED MESSAGE-----\n…\n-----END PGP SIGNATURE-----",
    "rateLockedUntil": "2026-10-19T12:10:00.000Z",
    "expiresAt": "2026-10-19T12:10:00.000Z",
    "createdAt": "2026-10-19T12:00:00.000Z",
    "completedAt": null
  }
}

• Check the signature with your API secret and reject old timestamps (for example more than 5 minutes), then answer any 2xx within 10 seconds. Treat each delivery as “the order changed”: they can arrive late or more than once, and a status that passed quickly can be skipped, so use the order's status, not the order of arrival.
• Failed deliveries (no answer within 10 seconds, or not 2xx) are retried with growing pauses for about 12 hours, then given up.
• Deliveries stop after completed or refunded was delivered, and 7 days after creation. An expired order is still watched (every 10 minutes) because a late deposit moves it on.
• Only https URLs on port 443 with a public address; redirects are not followed. Deliveries come from changing IP addresses: verify the signature instead of allowlisting IPs.
• After rotating your API secret, new deliveries are signed with the new one.

Node.jsPython

Copy

// Express: keep the raw body, check the signature and the time, then answer 2xx quickly.
import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/hooks/anonchange", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Webhook-Timestamp");
  const expected = crypto
    .createHmac("sha256", process.env.ANONCHANGE_API_SECRET)
    .update(`${timestamp}\n${req.body}`)
    .digest("hex");
  const given = Buffer.from(req.get("X-Webhook-Sign") ?? "");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  if (!fresh || given.length !== expected.length || !crypto.timingSafeEqual(given, Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { order } = JSON.parse(req.body);
  // update your copy of order.id with order.status ...
  res.sendStatus(204);
});

Order lifecycle

The usual path is awaiting_deposit → confirming → exchanging → sending → completed. An order that received a deposit ends completed or refunded.

Float and fixed rates

• Float: the customer gets the market rate at the moment the deposit is confirmed; the quote is an estimate. If that rate is more than maxRateDriftPercent worse than the quote, the order stops for the customer's decision (see Continue or refund).
• Fixed: the quoted rate is locked for rateLockMinutes (10 minutes by default, see rateLockedUntil) for a deposit of up to the quoted amount. A larger deposit gets the market rate or the fixed one, whichever is lower; a later deposit gets the market rate (either stops for the customer's decision like a float order if that rate moved too far). If the market moves so sharply that the locked rate cannot be paid, the order is held for review.

Review and refunds

• review means a manual check by our team, for example for a large amount. After it the order is completed or refunded.
• Refunds go to the order's refundAddress, minus the network fee. Always pass a refund address: without one the customer has to contact support.
• A deposit below the minimum is not exchanged: the order stops in refund_required for a refund.
• A float order waits 60 minutes (by default) for the deposit, a fixed one as long as its rate lock (see expiresAt). After that it is expired, but a late deposit is still exchanged at the market rate.

Limits and polling

Requests per API key per minute:

• Unpaid open orders (awaiting_deposit) per partner are capped. Above the cap, create returns 503 until older orders are paid or expire.
• On top of that, up to 3000 requests per minute per IP address reach the partner API.
• A 429 carries a Retry-After header (seconds). currencies and pairs change slowly: cache them for a minute.
• Poll status every 15-30 seconds while an order is open, and stop once it is completed or refunded. Or skip polling with webhooks.

Common errors and fixes

Every error is { "error": "message" }. These are the messages integrations run into most, as the API sends them, and what to change.

Mistakes without an error

Stuck? Log the exact signed string and the headers you sent (never the secret) and compare them with the curl example in Authentication, which is known to work.

Letter of guarantee

Every order comes with a letter of guarantee in its guarantee field: a PGP cleartext-signed text with the order's terms (amounts, rate, fees, addresses, validity). It states that:

• the order is either completed on the terms in the letter or refunded;
• no KYC: we never ask for identity documents or personal information;
• we do not freeze funds; some orders need a manual check, after which they are completed or refunded;
• refunds go to the refund address, minus the network fee (an amount too small to cover it cannot be refunded).

Anyone can verify it with GnuPG:

bashCopy

curl -s https://anonchange.com/pgp.txt | gpg --import
# save the order's "guarantee" field as letter.asc, e.g.
jq -r .guarantee order.json > letter.asc
gpg --verify letter.asc

Compare the fingerprint gpg shows with the one on our PGP key page. You can pass the letter on to your customers as it is.

Affiliate program

One partner account covers both referral links and the API.

• Referral links: share https://anonchange.com/?ref=YOUR_CODE with your code from the dashboard. The visitor's browser keeps the referral for 30 days, and the visitor pays the normal site price.
• API orders: you earn a share of our fee plus your own optional markup. Set the markup in your dashboard, or per request with markupPercent (it is capped); it is included in feePercent.
• Your share, the markup cap and the minimum payout are shown in your dashboard.
• Earnings are counted in USD when an order completes.
• Request a payout in the dashboard in any supported coin once your balance is above the minimum. We send it after a check, minus that coin's network fee.

Swap widget

No code needed: paste the widget on your site. Visitors see a live quote; Exchange opens the swap on AnonChange in a new tab with your referral, so it earns like your referral link. Your dashboard has the code with your referral filled in.

HTMLCopy

<iframe
  src="https://anonchange.com/widget?ref=YOUR_CODE&from=BTC&to=XMR"
  title="AnonChange swap"
  width="100%"
  height="400"
  style="border:0;max-width:456px"
></iframe>

If you sandbox the iframe, allow allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox so the swap can open.

Support

Questions about the integration or an order? Contact us on Telegram or Signal (anonchange.83) with the order ID.