Skip to main content
Version: v2

Quickstart

Create your first exchange order in five minutes: quote → create → pay → track.

Prerequisites​

  • An API key and referral token — create both from your personal dashboard on n.exchange (Authentication explains how each is used).
  • curl or any HTTP client.

1. Quote the pair​

Ask for a rate for the exact pair and amount the user wants. Always pass a pairs filter — never fetch the unfiltered catalogue in production (why).

curl -X GET "https://api.n.exchange/en/api/v2/rate/?pairs=BTCUSDC&deposit_amount=500" \
  -H "Accept: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "x-referral-token: YOUR_REFERRAL_TOKEN"
[
  {
    "pair": "BTCUSDC",
    "from": "USDC",
    "to": "BTC",
    "rate": "45000.00",
    "withdrawal_fee": "0.00050000",
    "rate_id": "abc123-000000",
    "min_deposit_amount": "50.00",
    "max_deposit_amount": "500000.00",
    "min_withdraw_amount": "0.00100000",
    "max_withdraw_amount": "10.00000000",
    "expiration_time_unix": "1697365800",
    "withdraw_amount": "0.01061111"
  }
]

Because we passed deposit_amount with a single pair, the row includes withdraw_amount — the exact receive amount to display. Note rate_id and expiration_time_unix: quotes expire within tens of seconds (Rates & Pricing).

2. Create the order​

Bind the order to the quote by passing its rate_id:

curl -X POST "https://api.n.exchange/en/api/v2/orders/" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "x-referral-token: YOUR_REFERRAL_TOKEN" \
  -d '{
    "deposit_amount": "500.00",
    "deposit_currency": "USDC",
    "withdraw_currency": "BTC",
    "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "refund_address": "0xYourUsersSourceAddress",
    "rate_id": "abc123-000000"
  }'

A 201 returns the created order. (For DeFi orders a 200 can come back instead, meaning a matching open order already existed — see 201 vs 200.)

{
  "unique_reference": "ABCDEF123456",
  "created_on": "2026-05-18T10:15:30Z",
  "side": "BUY",
  "status": "INITIAL",
  "deposit_amount": "500.00000000",
  "withdraw_amount": "0.01061111",
  "deposit_currency": "USDC",
  "withdraw_currency": "BTC",
  "deposit_address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
  "deposit_address_extra_id": "",
  "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "withdraw_address_extra_id": "",
  "refund_address": "0xYourUsersSourceAddress",
  "refund_address_extra_id": "",
  "payment_window_minutes": 60,
  "fixed_rate_deadline": "2026-05-18T11:15:30Z",
  "rate": "45000.00000000",
  "deposit_transaction": "",
  "withdraw_transaction": ""
}

3. Show payment instructions​

Display deposit_address (and deposit_address_extra_id if non-empty — it's mandatory then), the exact deposit_amount, and a countdown to fixed_rate_deadline. UX patterns: Building a Payment UI.

4. Track to completion​

curl -X GET "https://api.n.exchange/en/api/v2/orders/ABCDEF123456/" \
  -H "Accept: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Poll every 30–60 seconds while the order is active (Order Tracking), or receive push updates via Webhooks. The status progresses INITIAL → UNCONFIRMED PAYMENT → PAID → PRE-RELEASE → RELEASED → COMPLETED; every status and edge case (KYC review, refunds, expiry) is defined in Order Lifecycle.

Where to go next​