Create Order

Places an order to purchase TRON energy or bandwidth from the best available provider. 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: MARKETLIMITPERIODICBROADCASTDefault: MARKET

amountnumberREQUIRED

Amount of resource units to purchaseMinimum 65000 for energy

duration_secnumberREQUIRED

Rental duration in seconds

target_addressstringREQUIRED

TRON address to receive delegated resources (valid base58)

max_price_sunnumberOPTIONAL

Max price per unit in SUN. MARKET fails if exceeded. LIMIT waits for price drop.

Minimum amount

Energy orders require a minimum of 65,000 units. Orders below this threshold are rejected with a 400 error.

Order types

MARKET - executes immediately at the best available price
LIMIT - waits until a provider price is at or below max_price_sun
PERIODIC - recurring order that re-executes at the specified interval
BROADCAST - fills across multiple providers to maximize availability

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",
  "resource_type": "ENERGY",
  "order_type": "MARKET",
  "amount": 100000,
  "duration_sec": 86400,
  "target_address": "TKVSaJQDWeKFSEXmA5ygozDhrq1RLNqxAP",
  "max_price_sun": 40,
  "created_at": "2026-03-29T12:05:00.000Z"
}

Response fields

idstringUnique order identifier (UUID)

statusstringCurrent order status

resource_typestringENERGY or BANDWIDTH

order_typestringMARKET, LIMIT, PERIODIC, or BROADCAST

amountnumberRequested resource amount

duration_secnumberRental duration in seconds

target_addressstringReceiving TRON address

created_atstringISO 8601 creation timestamp

Order lifecycle

After creation, an order transitions through the following statuses:

PENDING - order received, awaiting provider selection
EXECUTING - provider selected, delegation transaction in progress
FILLED - delegation confirmed on-chain, resources delivered
FAILED - execution failed after all retries exhausted

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"
  }
}