DocumentationBrowse sections

Create Order

Places an order to purchase TRON energy or bandwidth at the current executable MERX quote. This is the primary endpoint for executing trades on Merx.

POST/api/v1/ordersRequires authentication
Requires create_orders permission

Headers

X-API-KeystringREQUIRED
Your API key
Content-TypestringREQUIRED
Must be application/json
Idempotency-KeystringOPTIONAL
Unique key to prevent duplicate orders. Same key within 24 hours returns the original response.

Request body

resource_typestringREQUIRED
Type of resource to purchaseOne of: ENERGYBANDWIDTH
order_typestringOPTIONAL
Order execution strategyOne of: MARKETDefault: MARKET
amountnumberREQUIRED
Amount of resource units to purchaseMinimum 65000 for energy
duration_secnumberREQUIRED
Fixed rental duration in secondsOne of: 12030060090018003600108002160086400
target_addressstringREQUIRED
TRON address to receive delegated resources (valid base58)
max_price_sunnumberOPTIONAL
Your offered price per unit in SUN, with precision up to 0.001 SUN. Below-current offers are rejected; equal or higher offers execute at this submitted price. Omit to use the current best price.
quote_idstringOPTIONAL
Optional UUID returned by GET /orders/preview. It is retained for compatibility and correlation; the price is always checked again at submission.
Minimum amount
Energy orders require a minimum of 65,000 units. Orders below this threshold are rejected with a 400 error.

Order type

Request examples

curl -X POST https://merx.exchange/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "Idempotency-Key: ord_abc123" \
  -d '{
    "resource_type": "ENERGY",
    "order_type": "MARKET",
    "amount": 100000,
    "duration_sec": 86400,
    "target_address": "TKVSaJQDWeKFSEXmA5ygozDhrq1RLNqxAP",
    "max_price_sun": 40
  }'

Response

201Order created
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "PENDING",
  "quoted_cost_sun": "4000000",
  "max_activation_fee_sun": "0",
  "max_total_cost_sun": "4000000",
  "total_fee_sun": "0",
  "quote_id": "8ff52c20-9e16-4a88-b7d9-c1382157c927",
  "duration_sec": 86400,
  "created_at": "2026-03-29T12:05:00.000Z"
}

Response fields

idstringUnique order identifier (UUID)
statusstringCurrent order status
quoted_cost_sunstringAccepted resource charge in SUN
max_activation_fee_sunstringMaximum reserved activation charge in SUN
max_total_cost_sunstringMaximum reserved total in SUN
total_fee_sunstringSeparate MERX fee in SUN
quote_idstringCompatibility quote UUID used for correlation
duration_secnumberRental duration in seconds
created_atstringISO 8601 creation timestamp

Order lifecycle

After creation, an order transitions through the following statuses:

Use GET /orders/:id to poll the current status, or configure a webhook to receive status change notifications in real time.

Error responses

400Validation error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount must be at least 65000 for energy orders",
    "details": { "field": "amount", "min": 65000 }
  }
}
402Insufficient balance
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Account balance too low for this order"
  }
}