Orders

The Orders endpoints allow you to create and manage cryptocurrency exchange orders using the simplified v2 API format.

List Orders

Retrieve a list of orders with v2 field format.

Request

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

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number for pagination (default: 1)
page_size	integer	No	Number of items per page (1-100, default: 20)

Response

Returns a paginated list of orders.

Response Fields:

Field	Type	Description
count	integer	Total number of orders
next	string/null	URL for next page
previous	string/null	URL for previous page
results	array	Array of order objects

Example Response:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "unique_reference": "ABCDEF",
      "side": "SELL",
      "withdraw_amount": "0.01000000",
      "deposit_amount": "500.00",
      "deposit_currency": "USDC",
      "withdraw_currency": "BTC",
      "status": "INITIAL",
      "created_on": "2023-10-15T10:30:00Z",
      "payment_window_minutes": 60,
      "fixed_rate_deadline": "2023-10-15T11:30:00Z",
      "rate": "50000.00",
      "deposit_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "deposit_address_extra_id": "",
      "withdraw_address": "",
      "withdraw_extra_id": "",
      "refund_address": "",
      "refund_address_extra_id": "",
      "deposit_transaction": "",
      "withdraw_transaction": ""
    }
  ]
}

Create Order

Create a new cryptocurrency exchange order using v2 simplified format.

Request

curl -X POST "https://api.n.exchange/en/api/v2/orders/" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-referral-token: your-referral-token" \
  -H "X-User-Timezone: GMT +04:00 (Asia/Dubai)"
  -d '{
    "side": "SELL",
    "withdraw_amount": "0.01000000",
    "deposit_currency": "USDC",
    "withdraw_currency": "BTC",
    "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  }'

Headers:

Header	Required	Description
x-referral-token	No	Referral token for identification
Authorization	Yes	Bearer token for additional authorization (e.g., "ApiKey api_key")
X-User-Timezone	Yes	GMT offset + IANA_Timezone (GMT ±HH:MM (IANA_Timezone)) wiki

Request Fields:

Field	Type	Required	Description
side	string	No	Order side: "BUY" or "SELL" (default: "SELL")
withdraw_amount	string	Yes*	Amount to withdraw (required if deposit_amount not provided)
deposit_amount	string	Yes*	Amount to deposit (required if withdraw_amount not provided)
deposit_currency	string	Yes	Currency code for deposit
withdraw_currency	string	Yes	Currency code for withdrawal
withdraw_address	string	No	Address where withdrawal should be sent (can be set later)
withdraw_extra_id	string	No	Extra ID for withdraw address
refund_address	string	No	Address for refunds (optional)
rate_id	string	No	Rate id (optional), could be retrieved from rate/ endpoint
refund_extra_id	string	No	Order with refund address extra ID (for currencies requiring memo/destination tag)
*Either withdraw_amount or deposit_amount must be provided.

Example Request Bodies:

Buy BTC with USDT:

{
  "side": "BUY",
  "deposit_amount": "500.00",
  "deposit_currency": {
    "code": "USDT",
    "network": "ETH"
  },
  "withdraw_currency": {
    "code": "BTC",
    "network": "BTC"
  },
  "rate_id": "waq1T39kPFn9LOETpzTnX6by7Yc-001ABB",
  "refund_extra_id": "12345"
}

or

{
  "side": "BUY",
  "deposit_amount": "500.00",
  "deposit_currency": "USDTERC",
  "withdraw_currency": "BTC",
}

Response

Returns the created order with deposit instructions and tracking information.

Response Fields:

Field	Type	Description
unique_reference	string	Unique order identifier for tracking
side	string	Order side - "BUY" or "SELL"
withdraw_amount	string	Amount being withdrawn (sent out)
deposit_amount	string	Amount being deposited (received)
deposit_currency	string or object	Currency code for the deposit (what you send to us), {code: USDT, network: EHT}
withdraw_currency	string or object	Currency code for the withdrawal (what we send to you), {code: USDT, network: EHT}
status	string	Current status of the order
created_on	string	Order creation timestamp
payment_window_minutes	integer	Time window for payment in minutes
fixed_rate_deadline	string/null	Deadline for fixed rate (if applicable)
deposit_address	string	Address where you must send your funds
deposit_address_extra_id	string	Extra ID for deposit address (memo, destination tag, etc.)
withdraw_address	string	Address where withdrawal will be sent
withdraw_extra_id	string	Extra ID for withdraw address
refund_address	string	Address for refunds if needed
refund_extra_id	string	Order with refund address extra ID (for currencies requiring memo/destination tag)
deposit_transaction	string	Transaction ID of the deposit
withdraw_transaction	string	Transaction ID of the withdrawal

Example Response:

{
  "unique_reference": "ABCDEF123456",
  "side": "SELL",
  "withdraw_amount": "0.01000000",
  "deposit_amount": "500.00",
  "deposit_currency": "USDC",
  "withdraw_currency": "BTC",
  "status": "INITIAL",
  "created_on": "2023-10-15T10:30:00Z",
  "payment_window_minutes": 60,
  "fixed_rate_deadline": "2023-10-15T11:30:00Z",
  "deposit_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "deposit_address_extra_id": "",
  "withdraw_address": "",
  "withdraw_extra_id": "",
  "refund_address": "",
  "refund_extra_id": "",
  "deposit_transaction": "",
  "withdraw_transaction": ""
}

Get Order Details

Retrieve detailed information about a specific order.

Request

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

Path Parameters:

Parameter	Type	Required	Description
unique_reference	string	Yes	Unique reference identifier for the order (pattern: ^[A-Za-z0-9_-]+$)

Authentication: Bearer token required

Response

Returns complete order information including transaction details.

Example Response:

{
  "unique_reference": "ABCDEF123456",
  "side": "SELL",
  "withdraw_amount": "0.01000000",
  "deposit_amount": "500.00",
  "deposit_currency": "USDC",
  "withdraw_currency": "BTC",
  "status": "UNCONFIRMED PAYMENT",
  "created_on": "2023-10-15T10:30:00Z",
  "payment_window_minutes": 60,
  "fixed_rate_deadline": "2023-10-15T11:30:00Z",
  "rate": "50000.00",
  "deposit_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "deposit_address_extra_id": "",
  "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "withdraw_extra_id": "",
  "refund_address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
  "refund_address_extra_id": "",
  "deposit_transaction": "a1b2c3d4e5f6...",
  "withdraw_transaction": ""
}

Update Order

Update specific fields of an order.

Request

curl -X PATCH "https://api.n.exchange/en/api/v2/orders/ABCDEF123456/" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey api_key" \
  -d '{
    "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  }'

Path Parameters:

Parameter	Type	Required	Description
unique_reference	string	Yes	Unique reference identifier for the order (pattern: ^[A-Za-z0-9_-]+$)

Update Fields:

Field	Type	Description
withdraw_address	string	Set the withdrawal address (only once, before processing)
withdraw_extra_id	string	Extra ID for withdraw address
marked_as_paid	boolean	Mark order as paid (true) or cancel payment (false)
deposit_transaction	string	Provide deposit transaction ID

Authentication: Bearer token required

Example Request Bodies:

Set withdraw address:

{
  "withdraw_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
}

Mark as paid with transaction:

{
  "marked_as_paid": true,
  "deposit_transaction": "a1b2c3d4e5f6789abcdef..."
}

Cancel payment:

{
  "marked_as_paid": false
}

Response

Returns the updated order information with the same structure as the create order response.

Order Status Lifecycle

Orders progress through several states during processing:

Status Values

Status Code	Status Name	Description
0	CANCELED	Deposit not received and order expired
11	INITIAL	Order created, awaiting deposit
12	UNCONFIRMED PAYMENT	Deposit detected but not confirmed
13	PAID	Deposit confirmed
14	PRE-RELEASE	Withdrawal transaction being created
15	RELEASED	Withdrawal transaction broadcasted
16	COMPLETED	Withdrawal transaction confirmed
6	INITIATED REFUND	Order refund process initiated
8	REFUNDED	Order refunded successfully
7	REFUND FAILED	Order refund failed
9	PENDING KYC	Waiting for additional due diligence

Typical order flow

✅ Success Flow:

INITIAL → UNCONFIRMED PAYMENT → PAID → PRE-RELEASE → RELEASED → COMPLETED

❌ Unpaid Flow:

INITIAL → CANCELED

🔍 KYC Success Flow:

INITIAL → UNCONFIRMED PAYMENT → PENDING KYC → PAID → PRE-RELEASE → RELEASED → COMPLETED

🔍 KYC Failure Flow:

INITIAL → UNCONFIRMED PAYMENT → PENDING KYC → INITIATED REFUND → REFUNDED

🔄 Refund Retry Flow:

INITIATED REFUND → REFUND FAILED → INITIATED REFUND → REFUNDED

Transaction statuses

Transaction objects are nested in order responses with their own state machine:

Status Code	Status Name	Description
-10	FAILED	Transaction failed
-5	DROPPED	Transaction dropped
-1	AUDIT_FAILED	Failed audit (withdrawal only)
0	CANCELED	Transaction canceled (withdrawal only)
1	INITIAL	Initial state (withdrawal only)
4	STAGED	Transaction staged (withdrawal only)
7	AUDITED	Transaction audited (withdrawal only)
10	UNCONFIRMED	Transaction broadcasted but unconfirmed
13	CONFIRMED	Transaction confirmed

Normal Withdrawal Flow:

INITIAL → STAGED → AUDITED → UNCONFIRMED → CONFIRMED

Deposit Transactions start at UNCONFIRMED status.

Key Changes from v1

Simplified Field Names

API v2 uses more descriptive field names:

• amount_base → withdraw_amount
• amount_quote → deposit_amount
• order_type → side (uses "BUY"/"SELL" strings)
• status_name[0][1] → status (flat string)
• payment_window → payment_window_minutes
• payment_deadline → fixed_rate_deadline

Flat Structure

v2 removes nested objects for simpler integration:

Transaction Fields

• transactions[].tx_id split into deposit_transaction and withdraw_transaction
• Direct string fields instead of nested transaction arrays

Error Responses

400 Bad Request

Returned for invalid input data.

Example:

{
  "detail": "Invalid input",
  "errors": {
    "deposit_currency": ["This field is required."],
    "withdraw_currency": ["This field is required."]
  }
}

401 Unauthorized

Returned when authentication credentials are missing or invalid.

Example:

{
  "detail": "Authentication credentials were not provided"
}

404 Not Found

Returned when the specified order doesn't exist.

Example:

{
  "detail": "Not found"
}

Next Steps

• Pre-screening - Compliance and validation checks
• Rates - Get current exchange rates
• Currencies - Learn about supported currencies

---