Orders

The Orders endpoints allow you to create and manage cryptocurrency exchange orders. This is where the actual trading takes place after you've obtained rates and selected trading pairs.

Get Orders

Retrieve a paginated list of orders with optional filtering.

Request

GET /orders/

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
page_size	integer	No	Number of orders per page (default: 20)
pair	string	No	Filter by pair name (e.g., "BTCETH")
status	integer	No	Filter by order status (e.g., 11)

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": 21,
  "next": "http://localhost:8000/en/api/v1/orders/?page=2&page_size=3",
  "previous": null,
  "results": [
    {
      "amount_base": "0.50000000",
      "is_default_rule": false,
      "unique_reference": "LOUA3",
      "amount_quote": "7.17000000",
      "pair": 2,
      "withdraw_address": {
        "type": "W",
        "name": "",
        "address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
        "currency_code": "BTC"
      },
      "created_on": "2017-08-16T07:27:04.964665Z",
      "from_default_rule": false,
      "order_type": 1,
      "deposit_address": {
        "type": "D",
        "name": "",
        "address": "0xF00667496B353d77492e0f7167843d5d5802030b",
        "currency_code": "ETH"
      },
      "pair_name": "BTCETH",
      "withdrawal_fee": "0.0025",
      "withdrawal_fee_quote": "0.03585",
      "user_provided_amount": "0"
    }
  ]
}

Create a New Order

Create a new cryptocurrency exchange order.

Request

POST /orders/

Headers:

Header	Required	Description
x-referral-token	No	Referral token for identification
Authorization	No	Bearer token for additional authorization

Request Body Fields:

Field	Type	Required	Description
order_type	integer	No	Order type (1 for buy, 0 for sell). Default: 1
amount_quote	string	Yes*	Quote amount for the order
amount_base	string	Yes*	Base amount for the order
pair	object	Yes	Pair object with name property
pair.name	string	Yes	Trading pair name (e.g., "BTCEUR")
withdraw_address	object	No	Withdrawal address object
withdraw_address.address	string	Yes**	Withdrawal address string
refund_address	object	No	Refund address object
refund_address.address	string	Yes**	Refund address string
payment_method	string	No	Payment method for FIAT orders
rate_id	string	No	Rate ID from bulk rates endpoint
is_default_rule	boolean	No	Auto-convert incoming funds

*Only one of amount_quote or amount_base should be provided. **Required if parent object is provided.

Response

Returns the created order with full details.

Order Response Fields:

Field	Type	Description
order_type	integer	Order type (1 for buy, 0 for sell)
amount_base	string	Base amount for the order
is_default_rule	boolean	Whether order uses default rule
unique_reference	string	Unique order identifier
amount_quote	string	Quote amount for the order
pair	object	Complete pair object with currencies
deposit_address	object	Address object for deposits
withdraw_address	object	Address object for withdrawals
refund_address	object	Address object for refunds
user_marked_as_paid	boolean	User payment confirmation status
created_on	string	Order creation timestamp
from_default_rule	boolean	Created from default rule
payment_window	integer	Payment window in minutes
payment_deadline	string	Payment deadline timestamp
kyc_deadline	string/null	KYC deadline if applicable
status_name	array	Status tuple [code, name]
transactions	array	Array of transaction objects
referral_code	array	Referral code information
withdrawal_fee	string	Withdrawal fee amount
withdrawal_fee_quote	string	Withdrawal fee in quote currency
user_provided_amount	string	User-provided amount

Example Response:

{
  "amount_base": "3.00000000",
  "is_default_rule": false,
  "unique_reference": "OTVVXE",
  "amount_quote": "251.89000000",
  "pair": {
    "name": "BTCLTC",
    "base": {
      "code": "BTC",
      "name": "bitcoin",
      "min_confirmations": 2,
      "is_crypto": true,
      "minimal_amount": "0.00200000"
    },
    "quote": {
      "code": "LTC",
      "name": "litecoin",
      "min_confirmations": 6,
      "is_crypto": true,
      "minimal_amount": "0.25000000"
    },
    "fee_ask": 0.001,
    "fee_bid": 0.001
  },
  "withdraw_address": {
    "type": "W",
    "name": "",
    "address": "17dBqMpMr6r8ju7BoBdeZiSD3cjVZG62yJ",
    "currency_code": "BTC"
  },
  "deposit_address": {
    "type": "D",
    "name": "",
    "address": "addr_addr_id_5005841120",
    "currency_code": "LTC"
  },
  "created_on": "2017-09-19T09:20:11.491815Z",
  "payment_window": 15,
  "payment_deadline": "2017-09-19T09:35:11.491815Z",
  "status_name": [
    [11, "INITIAL"]
  ],
  "transactions": []
}

Get Order Details by Unique Reference

Retrieve detailed information about a specific order.

Request

GET /orders/{unique_reference}/

Path Parameters:

Parameter	Type	Required	Description
unique_reference	string	Yes	Unique reference for the order

Response

Returns complete order information including transaction details.

Example Response:

{
  "amount_base": "0.50000000",
  "is_default_rule": false,
  "unique_reference": "1CPL5",
  "amount_quote": "48.00000000",
  "pair": 1,
  "withdrawal_fee": "0.0025",
  "withdrawal_fee_quote": "0.03585",
  "user_provided_amount": "0",
  "withdraw_address": null,
  "created_on": "2017-08-16T10:36:02.248639Z",
  "from_default_rule": false,
  "order_type": 1,
  "deposit_address": {
    "type": "D",
    "name": "",
    "address": "LewxThDasEA2JTDVDdGMot92kG6XYNFNQN",
    "currency_code": "LTC"
  },
  "status": 1,
  "payment_window": 60,
  "payment_deadline": "2017-08-16T11:36:02.248639Z",
  "status_name": [
    [1, "INITIAL"]
  ],
  "transactions": [
    {
      "created_on": "2017-08-16T22:14:46.680082Z",
      "modified_on": "2017-08-16T22:14:46.680105Z",
      "type": "W",
      "address_to": 1,
      "tx_id": "asdfsadfsadf",
      "confirmations": 0,
      "amount": "0.01000000",
      "is_verified": false,
      "is_completed": false,
      "time": null,
      "currency": null
    }
  ]
}

Update an Order

Update specific fields of an order such as addresses, transaction ID, or payment status.

Request

PATCH /orders/{unique_reference}/

Path Parameters:

Parameter	Type	Required	Description
unique_reference	string	Yes	Unique reference for the order

Headers:

Header	Required	Description
Authorization	Yes	Bearer token from order creation

Request Body Fields:

Field	Type	Description
refund_address	object	Refund address object
refund_address.address	string	New refund address
refund_address.extra_id	string	Extra identifier if required
withdraw_address	object	Withdrawal address object
withdraw_address.address	string	New withdraw address
withdraw_address.extra_id	string	Extra identifier if required
tx_id	string/null	Transaction ID for deposit notifications
flagged	boolean	Flag order for manual review
user_marked_as_paid	boolean	Mark order as paid (true) or cancel (false)

Response

Returns the updated order fields.

Example Response:

{
  "refund_address": {
    "type": "W",
    "name": "",
    "address": "LUZ7mJZ8PheQVLcKF5GhitGuzZcgPWDPA4",
    "currency_code": "LTC"
  },
  "withdraw_address": null,
  "flagged": false
}

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.

Error Responses

400 Bad Request

Example:

{
  "detail": "Bad request"
}

401 Unauthorized

Example:

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

404 Not Found

Example:

{
  "detail": "Not found"
}

405 Method Not Allowed

Example:

{
  "detail": "Method \"PATCH\" not allowed."
}

Next Steps

• Pre-screening - Compliance and validation checks
• Pricing & Rates - Get current exchange rates
• Users & Authentication - User management for FIAT orders