Skip to content
API status
API reference

Open a trade

POST
/api/v1/management/servers/{serverId}/accounts/{accountNumber}/trades
curl --request POST \
  --url https://api.koneth.com/api/v1/management/servers/6be9a699-2f28-402e-b64e-93ba6bdafe1b/accounts/7001042/trades \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: account-create-client-1042' \
  --header 'X-Request-Id: onboarding-client-1042' \
  --data '{ "symbol": "XAUUSD", "side": "BUY", "volume": 0.5, "orderType": "MARKET", "stopLoss": 4480.5, "requestId": "open-trade-client-1042" }'

Queues an order for one trading account. Market orders execute against the server’s authoritative quote; LIMIT and STOP orders are placed as pending orders and require requestedPrice.

The order passes the same risk, margin, and protection checks the terminal applies, and the resulting position, deals, ledger entries, and webhook events are identical to a trade the trader placed themselves. Requires trades:write.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
serverId
required
string format: uuid

UUID of a trading server owned by your organization.

Example
6be9a699-2f28-402e-b64e-93ba6bdafe1b
accountNumber
required
string
>= 4 characters <= 32 characters /^[A-Za-z0-9_-]+$/

Trading account number.

Example
7001042

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
>= 1 characters <= 100 characters

Unique key for this logical mutation. Reuse it only when retrying the same operation. Maximum 100 characters.

Example
account-create-client-1042
X-Request-Id
string

Optional correlation ID used for API request billing and logs.

Example
onboarding-client-1042

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
symbol
required

Instrument symbol enabled on the server, for example XAUUSD.

string
>= 1 characters <= 30 characters
side
required
string
Allowed values: BUY SELL
volume
required

Order volume in lots.

number
> 0
orderType
string
default: MARKET
Allowed values: MARKET LIMIT STOP
requestedPrice

Required for LIMIT and STOP orders.

number
> 0
stopLoss

Optional protection level, validated against the current quote.

number
> 0
takeProfit

Optional protection level, validated against the current quote.

number
> 0
requestId
required

Correlation ID for this trade action.

string
>= 1 characters <= 100 characters
Example
{
  "symbol": "XAUUSD",
  "side": "BUY",
  "volume": 0.5,
  "orderType": "MARKET",
  "stopLoss": 4480.5,
  "requestId": "open-trade-client-1042"
}

Responses

Section titled “Responses”

200

Section titled “200”

An earlier command was returned for the idempotency key.

Media typeapplication/json
object
command
required
object
id
required
string format: uuid
operation
required
string
Allowed values: account.create account.update account.enable account.disable account.archive account.password_reset account.investor_password_reset account.history_export finance.deposit finance.withdraw trade.open trade.cancel trade.modify position.close position.modify position.close_all
status
required
string
Allowed values: queued leased succeeded failed expired
managedAccountId
One of:
string format: uuid
attempts
required
integer
payload
object
key
additional properties
any
result
One of:
object
key
additional properties
any
errorCode
One of:
string
errorMessage
One of:
string
idempotencyKey
required
string
createdAt
required
string format: date-time
completedAt
One of:
string format: date-time
key
additional properties
any
duplicate
required
boolean
Example
{
  "command": {
    "operation": "account.create",
    "status": "queued"
  }
}

202

Section titled “202”

Operation queued.

Media typeapplication/json
object
command
required
object
id
required
string format: uuid
operation
required
string
Allowed values: account.create account.update account.enable account.disable account.archive account.password_reset account.investor_password_reset account.history_export finance.deposit finance.withdraw trade.open trade.cancel trade.modify position.close position.modify position.close_all
status
required
string
Allowed values: queued leased succeeded failed expired
managedAccountId
One of:
string format: uuid
attempts
required
integer
payload
object
key
additional properties
any
result
One of:
object
key
additional properties
any
errorCode
One of:
string
errorMessage
One of:
string
idempotencyKey
required
string
createdAt
required
string format: date-time
completedAt
One of:
string format: date-time
key
additional properties
any
duplicate
required
boolean
Example
{
  "command": {
    "operation": "account.create",
    "status": "queued"
  }
}

400

Section titled “400”

Invalid request.

Media typeapplication/json
object
error
required
string
issues

Validation issue details when the request fails schema validation.

Array<object>
object
key
additional properties
any
Examplegenerated
{
  "error": "example",
  "issues": [
    {}
  ]
}

401

Section titled “401”

Management API authentication is missing or invalid.

Media typeapplication/json
object
error
required
string
issues

Validation issue details when the request fails schema validation.

Array<object>
object
key
additional properties
any
Example
{
  "error": "Management API authentication required"
}

402

Section titled “402”

The organization cannot cover the active API request price.

Media typeapplication/json
object
error
required
string
issues

Validation issue details when the request fails schema validation.

Array<object>
object
key
additional properties
any
Example
{
  "error": "Insufficient API credits"
}

403

Section titled “403”

The key lacks the required scope or server access.

Media typeapplication/json
object
error
required
string
issues

Validation issue details when the request fails schema validation.

Array<object>
object
key
additional properties
any
Example
{
  "error": "Missing API scope: accounts:read"
}

404

Section titled “404”

The requested resource was not found.

Media typeapplication/json
object
error
required
string
issues

Validation issue details when the request fails schema validation.

Array<object>
object
key
additional properties
any
Examplegenerated
{
  "error": "example",
  "issues": [
    {}
  ]
}

409

Section titled “409”

The request conflicts with the current resource state.

Media typeapplication/json
object
error
required
string
issues

Validation issue details when the request fails schema validation.

Array<object>
object
key
additional properties
any
Examplegenerated
{
  "error": "example",
  "issues": [
    {}
  ]
}

500

Section titled “500”

Unexpected server error.

Media typeapplication/json
object
error
required
string
issues

Validation issue details when the request fails schema validation.

Array<object>
object
key
additional properties
any
Example
{
  "error": "Internal server error"
}