Create Trade

POST

/ver1/trades

Permission: SMART_TRADES_WRITE

Security: SIGNED

Creates a new trade.

This endpoint supports creating market and limit trades, including optional conditional triggers, trailing stops, timeouts, and leverage settings (for OKX Futures).

---

Request Parameters

account_idintegerrequired

ID of the exchange account. Use GET /ver1/accounts to retrieve available accounts.

pairstringrequired

Trading pair in format like USDT_BTC.

orderobjectrequired

Details of the trade order.

Hide child parametersShow child parameters

typestringrequired

Order type: market or limit.

sidestringrequired

Order direction: buy or sell.

strategystring

Optional time-in-force strategy: gtc, ioc, fok, or post_only. Defaults to gtc.

position_sidestring

Position direction: both (One-Way mode), or long/short (Hedge mode).

reduce_onlyboolean

Set to true to only reduce an existing position.

unitsobjectrequired

Amount to buy or sell.

Hide child parametersShow child parameters

valuenumberrequired

Trade quantity.

priceobject

Price settings, required for limit orders.

Hide child parametersShow child parameters

valuenumberrequired

Limit price value.

conditionalobjectrequired

Optional conditional order configuration.

Hide child parametersShow child parameters

enabledbooleanrequired

Whether the trade uses a conditional trigger.

valuestring

Trigger condition: less, less_or_equal, greater, or greater_or_equal.

priceobject

Conditional price trigger.

Hide child parametersShow child parameters

valuenumberrequired

Trigger price value.

typestringrequired

Price source: bid, ask, or last.

trailingobjectrequired

Optional trailing stop configuration.

Hide child parametersShow child parameters

enabledbooleanrequired

Whether trailing stop is enabled.

valuenumber

Absolute deviation.

percentnumber

Percentage deviation.

timeoutobjectrequired

Optional timeout for conditional trades.

Hide child parametersShow child parameters

enabledbooleanrequired

Whether timeout is enabled.

valueinteger

Timeout in seconds.

leverageobject

Optional leverage configuration (OKX Futures only).

Hide child parametersShow child parameters

typestring

Leverage mode: isolated or cross.

---

Example Trade Types

Market Buy

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "market",
    "side": "buy"
  },
  "units": {
    "value": "1.0"
  },
  "conditional": {
    "enabled": false
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": false
  }
}

Market Sell

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "market",
    "side": "sell"
  },
  "units": {
    "value": "1.0"
  },
  "conditional": {
    "enabled": false
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": false
  }
}

Limit Buy

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "limit",
    "side": "buy"
  },
  "units": {
    "value": "1.0"
  },
  "price": {
    "value": "10000.0"
  },
  "conditional": {
    "enabled": false
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": false
  }
}

Limit Sell

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "limit",
    "side": "sell"
  },
  "units": {
    "value": "1.0"
  },
  "price": {
    "value": "100000.0"
  },
  "conditional": {
    "enabled": false
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": false
  }
}

Conditional Market Buy

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "market",
    "side": "buy"
  },
  "units": {
    "value": "1.0"
  },
  "conditional": {
    "enabled": true,
    "value": "less_or_equal",
    "price": {
      "value": "10000.0",
      "type": "last"
    }
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": false
  }
}

Conditional Limit Sell

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "limit",
    "side": "sell"
  },
  "units": {
    "value": "1.0"
  },
  "price": {
    "value": "100000.0"
  },
  "conditional": {
    "enabled": true,
    "value": "greater_or_equal",
    "price": {
      "value": "90000.0",
      "type": "last"
    }
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": false
  }
}

Conditional Trailing Sell

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "market",
    "side": "sell"
  },
  "units": {
    "value": "1.0"
  },
  "conditional": {
    "enabled": true,
    "value": "greater_or_equal",
    "price": {
      "value": "90000.0",
      "type": "last"
    }
  },
  "trailing": {
    "enabled": true,
    "percent": "1.0"
  },
  "timeout": {
    "enabled": false
  }
}

Conditional + Timeout

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "market",
    "side": "sell"
  },
  "units": {
    "value": "1.0"
  },
  "conditional": {
    "enabled": true,
    "value": "greater_or_equal",
    "price": {
      "value": "90000.0",
      "type": "last"
    }
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": true,
    "value": 300
  }
}

Example Request

POST

/ver1/trades

{
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "market",
    "side": "buy"
  },
  "units": {
    "value": "1.0"
  },
  "conditional": {
    "enabled": false
  },
  "trailing": {
    "enabled": false
  },
  "timeout": {
    "enabled": false
  }
}

Response Parameters

If successful, the response includes trade ID, current status, and other metadata (not fully documented).

Example Responses

201 Created

{
  "uuid": "a6f1c3d2-9d1a-4db7-9ad4-f7a8e2f98765",
  "account_id": 1,
  "pair": "USDT_BTC",
  "order": {
    "type": "market",
    "side": "buy"
  },
  "units": {
    "value": "1.0"
  },
    "status": {
    "value": "to_process",
    "error": null
  },
  "filled": {
    "units": "0.0",
    "total": "0.0",
    "price": null
  },
  "created_at": 1727871936,
  "closed_at": null,
  "price": {
    "value": null
  },
  "conditional": {
    "enabled": false,
    "value": null,
    "price": {
      "value": null,
      "type": null
    }
  },
  "trailing": {
    "enabled": false,
    "value": null,
    "percent": null
  },
  "timeout": {
    "enabled": false,
    "value": null
  }
}

422 Unprocessable Entity

{
  "error": "invalid_request",
  "error_description": "Missing or invalid parameters"
}

403 Forbidden

{
  "error": "Forbidden",
  "error_description": "Api key not authorized for this action"
}