Start here

Instrument terms

Change an instrument's leverage ceiling, spread, and trading state from the Management API.

An instrument’s terms decide what a trader can do on it: how much margin a position costs, what spread they pay, and whether it trades at all. They can be changed from the Console by hand, or from the Management API when the change has to happen on a schedule.

The case that needs the API is news. Raising the cost of carrying a position before a release and lowering it afterwards is routine, and it should not depend on somebody being at a keyboard at the right moment.

The leverage ceiling

Each instrument may declare a ceiling. The leverage actually applied is the lower of the account’s and the instrument’s:

effective = min(account leverage, instrument ceiling)

It applies to every account, not only unlimited ones — an instrument capped at 1:400 holds a 1:500 account to 1:400 as well. null removes the ceiling, and an unlimited account on a capped instrument requires margin at that cap rather than none at all.

Lowering the ceiling raises margin on every account holding the instrument, which is exactly what makes it usable as a pre-news measure.

The spread

Market Service applies a server’s spread where the price leaves for a Terminal, and the trading server fetches its execution prices through the same endpoint — so the chart and the fill cannot disagree.

Mode	What it does
`floating`	Keeps the provider’s spread, never tighter than `minSpreadPoints`, then adds `spreadPoints` as a markup.
`fixed`	Replaces the spread with exactly `spreadPoints`. The minimum is ignored.

The provider’s midpoint is preserved and the spread is widened around it, so adjusting a spread moves the spread and never the level.

Set terms for one instrument

curl --request PATCH \
  --url "https://api.koneth.com/api/v1/management/servers/$KONETH_SERVER_ID/instruments/BTCUSD" \
  --header "Authorization: Management $KONETH_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: news-btc-20260916" \
  --data '{
    "maxLeverage": 100,
    "minSpreadPoints": 25,
    "requestId": "news-btc-20260916"
  }'

Only the fields you send are written. Everything else keeps whatever the attachment or a previous override already said, which is what makes a one-field change safe.

Set terms for a whole category

The same body, applied to every instrument in a category the server is entitled to. Categories are forex, metals, crypto, indices, commodities, stocks, and synthetic.

curl --request PATCH \
  --url "https://api.koneth.com/api/v1/management/servers/$KONETH_SERVER_ID/instrument-categories/crypto" \
  --header "Authorization: Management $KONETH_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: news-crypto-20260916" \
  --data '{ "maxLeverage": 50, "requestId": "news-crypto-20260916" }'

Then, after the release, the same call with the original value restores it.

Fields

Field	Meaning
`maxLeverage`	The ceiling, or `null` for none.
`spreadMode`	`fixed` or `floating`.
`spreadPoints`	The whole spread when fixed; a markup over the provider’s when floating.
`minSpreadPoints`	Floating only: a floor under the provider’s spread.
`tradingEnabled`	Whether the instrument trades at all. Disabling it does not close open positions.

Both routes require the markets:write scope and an Idempotency-Key. They answer synchronously and republish the market configuration, so a spread change is quoting immediately rather than at the next publish.

What you cannot do here

An instrument the organisation has not purchased is not attached to the server, and cannot be configured. A category with nothing attached answers 404.

The liquidation thresholds — the margin-call and stop-out levels — are set per server, not per instrument.