Orders & positions

How to open, change and close trades, what each answer means, and how to read the account back.

#The calls

Every write needs an Idempotency-Key header (see Idempotency), and a key with the trade or trade:propose scope.

#Placing an order

A limit order buys below or sells above the current price; a stop order buys above or sells below it. Pending orders come back typed as buy_limit, sell_limit, buy_stop or sell_stop.

curl -X POST https://terminal.jafx.com/trading-api/v1/accounts/$ACCOUNT/orders \
  -H "Authorization: Bearer $JAFX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"EURUSD","side":"buy","type":"market","volume":"0.02","stop_loss":1.1100,"client_tag":"breakout-v2"}'

order = {"symbol": "EURUSD", "side": "buy", "type": "market", "volume": "0.02",
         "stop_loss": 1.1100, "client_tag": "breakout-v2"}
key = str(uuid.uuid4())          # keep it: retries of THIS order reuse it
r = api.post(f"/accounts/{account}/orders", json=order, headers={"Idempotency-Key": key})

const order = { symbol: 'EURUSD', side: 'buy', type: 'market', volume: '0.02', stop_loss: 1.11, client_tag: 'breakout-v2' }
const key = randomUUID()          // keep it: retries of THIS order reuse it
const r = await fetch(`${BASE}/accounts/${account}/orders`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json', 'Idempotency-Key': key },
  body: JSON.stringify(order),
})

A buy limit order with a stop, a target and an expiry:

{"symbol":"EURUSD","side":"buy","type":"limit","volume":"0.10","price":1.1080,
 "stop_loss":1.1040,"take_profit":1.1180,"expires_at":"2026-10-20T00:00:00Z","client_tag":"breakout-v2"}

#What each answer means

The result object:

{
  "request_id": "01JQ8Z6M3S4X7T2N9CKV5W0HRB",
  "kind": "market",
  "status": "filled",
  "ticket": 5001,
  "broker_status": "dc-answered",
  "failure": null,
  "client_tag": "breakout-v2",
  "position": {
    "ticket": 5001, "symbol": "EURUSD", "side": "buy", "volume": "0.02",
    "open_price": 1.11555, "open_time": "2026-10-13T09:29:47.512Z",
    "stop_loss": 1.11, "take_profit": null, "profit": "-0.02",
    "origin": "api", "client_tag": "breakout-v2", "from_ticket": null
  }
}

• request_id identifies this order request; use it with GET /accounts/{account}/requests/{request_id}.
• kind: market, pending, modify_position, modify_order, close or cancel.
• broker_status is the broker's own decision code, useful when you contact support. Branch on status, not on it.
• failure explains a refusal in the broker's words.

#Following a request

GET /accounts/{account}/requests/{request_id} shows where any order request stands. When the request is still open it checks with the broker before answering.

#Stops and targets

Send only what changes. A field you omit is kept; null removes it.

# Move the stop loss; the take profit stays as it is
curl -X PATCH https://terminal.jafx.com/trading-api/v1/accounts/$ACCOUNT/positions/5001 \
  -H "Authorization: Bearer $JAFX_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"stop_loss":1.1105}'

# Remove the take profit
curl -X PATCH https://terminal.jafx.com/trading-api/v1/accounts/$ACCOUNT/positions/5001 \
  -H "Authorization: Bearer $JAFX_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"take_profit":null}'

Stop and target changes count against the key's modifications_per_minute, not its order budget. A trailing stop should move the stop only when it has moved meaningfully, rather than on every quote.

#Pending orders

PATCH /accounts/{account}/orders/{ticket} changes price, stop_loss, take_profit or expires_at; omitted fields are kept and null removes a stop or the expiry. DELETE /accounts/{account}/orders/{ticket} cancels the order. When a pending order fills, the orders stream sends order.triggered followed by position.opened.

#Closing

An empty body closes the whole position at market. {"volume": "0.01"} closes part of it.

After a partial close, the part that stays open is a new position with a new ticket: the answer's ticket is that new ticket, and its position.from_ticket names the original. The remainder keeps the original's client_tag. In the history, the closed part appears with "state": "closed_partial".

{
  "request_id": "01JQ8ZD9R2K6W4T8NB1XQ5VH3M",
  "kind": "close",
  "status": "filled",
  "ticket": 5002,
  "position": { "ticket": 5002, "volume": "0.01", "client_tag": "breakout-v2", "from_ticket": 5001 }
}

#Tags (client_tag)

• Optional, up to 32 characters from A–Z a–z 0–9 . _ : -, set when you place the order.
• Returned on positions, pending orders, closed trades and stream events, and filterable: GET …/positions?client_tag=breakout-v2.
• Kept by the remainder of a partial close.
• Use it to tell strategies apart, like the magic number some platforms give each strategy: "magic:20231105".

Trades placed outside the API have no tag. Their origin says where they came from: api, web, mobile, dealer, expert, signal, client or other.

#Reading the account

• Summary (GET /accounts/{account}): balance, credit, equity, margin, free_margin, floating_profit in the account currency, and margin_level in percent (null with no margin in use).
• Positions include the floating profit, swap, commission and taxes.
• Closed trades (GET …/trades) are ordered by close time, newest first, in windows of up to 90 days, with next_cursor for more. state is closed, closed_partial, closed_by, cancelled or expired; cancelled and expired pending orders appear here too.
• Balance operations (GET …/transactions): deposits, withdrawals and credit, as balance or credit rows.

For live updates, subscribe to the account and orders channels on the stream instead of polling.

#What can refuse an order

JAFX checks these before anything reaches the broker, in this order. A refusal never costs you a trade, and the idempotency key is released so you can retry once the cause is fixed.

Then the order goes to the broker through your account's own session, and the broker validates it against your account: the instrument (404 symbol_not_available), volume steps, stop distances, margin and market hours.

#Not available yet

Maximum slippage on market orders, stop-limit orders, OCO pairs and server-side trailing stops. Tell us which you need most.

#Porting a bot from another platform

Most orders are acknowledged well within a second. When the broker covers a trade with a liquidity provider it can take a few seconds: that is the 202 pending case.