Order lifecycle

This guide uses OMS for trading and account state. Market data comes from MDS; see Market data client.

Flow

Authenticate: GET /nonce/{user_id}, sign the nonce value, POST /auth.
Discover the market on OMS: GET /markets or GET /market/{asset_id} for book decimals and fees.
Sign the action-specific object: order create signs order, replace signs request, cancel signs cancel.
Submit over REST or the /control WebSocket.
Treat the REST response as admission, not finality. Confirm over the orders and trades streams or by refetching orders.

Numeric examples use raw book units. With book_price_decimals = 2, 250000 means 2500.00. With book_quantity_decimals = 8, 125000000 means 1.25000000.

Raw REST

curl -X POST https://oms.tplus.cx/orders/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Id: $USER_ID" \
  -H "Content-Type: application/json" \
  --data @create-order.json

create-order.json contains the signed body from Signing. Replace:

curl -X PATCH https://oms.tplus.cx/orders/replace \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Id: $USER_ID" \
  -H "Content-Type: application/json" \
  --data @replace-order.json

Cancel:

curl -X DELETE https://oms.tplus.cx/orders/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Id: $USER_ID" \
  -H "Content-Type: application/json" \
  --data @cancel-order.json

Batch create wraps signed create requests:

{
  "orders": [
    { "...": "signed create request 1" },
    { "...": "signed create request 2" }
  ]
}

Batch create is not all-or-nothing: accepted orders remain live even if a later item rejects. Cancel-all is unsigned at the action layer and authenticated by the session. OMS collects open orders with timestamp_ns < max_ts; if max_ts is omitted, it uses server time:

curl -X DELETE "https://oms.tplus.cx/orders/cancel-all?max_ts=1760000000000000000" \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Id: $USER_ID"

Use DELETE /orders/cancel-all/{asset_id} to scope to one market. Use DELETE /orders/cancel-batch with order IDs for a selected subset; IDs not owned by the caller are ignored.

tpluspy

from tplus.client import OrderBookClient
from tplus.model.asset_identifier import AssetIdentifier
from tplus.model.limit_order import GTC
from tplus.model.order import TradeTarget
from tplus.utils.user import User

OMS = "https://oms.tplus.cx"
asset = AssetIdentifier(200)
user = User(private_key="<ed25519-private-key-hex>")

async with OrderBookClient(user=user, base_url=OMS) as client:
    market = await client.get_market(asset)
    created = await client.create_limit_order(
        asset_id=asset,
        side="Buy",
        price=250000,
        quantity=125000000,
        time_in_force=GTC(post_only=False),
        target=TradeTarget(account=1, is_spot=False),
    )
    replaced = await client.replace_order(
        original_order_id=created.order_id,
        asset_id=asset,
        new_price=251000,
        new_quantity=100000000,
    )
    canceled = await client.cancel_order(created.order_id, asset)

Pass use_ws_control=True to OrderBookClient to send create, replace, and cancel over /control instead of REST. The control channel accepts v0 raw action wrappers or v1 envelopes with request_id.

Replace semantics

Replace preserves the order ID. The mutable fields are price, quantity, and trigger; the request also carries book decimals when price or quantity changes. Fill state of a partially filled enabled order is preserved. A replace with an older timestamp_ns than a newer applied replace is rejected by the orderbook. REST replace and REST cancel first look up the current OMS order and return not found if absent. The control channel forwards directly to the orderbook; a cancel that reaches the fast queue before its create can reject the later create.

Sub-accounts, transfers, and close-all

There is no standalone “create sub-account” call. Transfer spot balance into an unused target_index and include target_account_type. Raw transfer: Populate signature with the Ed25519 signature bytes over compact inner before sending.

{
  "inner": {
    "user": "<user public key>",
    "source_index": 0,
    "target_index": 1,
    "transfer_asset": "0",
    "transfer_amount": "1000000000000000000",
    "target_account_type": {"CrossMargin": null},
    "nonce": 1760000000000
  },
  "signature": [],
  "additional_signers": []
}

tpluspy-assisted transfer, using the SDK user signer and the raw request path:

import json
import time

inner = {
    "user": user.public_key,
    "source_index": 0,
    "target_index": 1,
    "transfer_asset": "0",
    "transfer_amount": str(10**18),
    "target_account_type": {"CrossMargin": None},
    "nonce": time.time_ns(),
}
signing_payload = json.dumps(inner, separators=(",", ":"))
signing_payload = signing_payload.replace(" ", "").replace("\r", "").replace("\n", "")
payload = {
    "inner": inner,
    "signature": list(user.sign(signing_payload)),
    "additional_signers": [],
}
await client._request("POST", "/account/transfer/sub-account", json_data=payload)

Use a client-generated, strictly increasing nonce per action domain and treat that nonce as the retry key: after a timeout, check /account/events/{user_id} and /inventory/user/{user_id} before sending a new nonce. The current request_transfer_to_subaccount SDK helper does not include the required signed nonce field; use the explicit signing path above until the helper exposes it. Close-position is available only after the base leg is zero. It folds the remaining quote credits into spot USD, or repays quote liabilities from spot USD, and emits PositionCleared; if a quote liability remains, the spot USD balance must cover it.

inner = {
    "user": user.public_key,
    "account": 1,
    "asset_identifier": "200",
    "nonce": time.time_ns(),
}
signing_payload = json.dumps(inner, separators=(",", ":"))
signing_payload = signing_payload.replace(" ", "").replace("\r", "").replace("\n", "")
payload = {
    "inner": inner,
    "signature": list(user.sign(signing_payload)),
    "additional_signers": [],
}
await client._request("POST", "/account/transfer/close-position", json_data=payload)

The current request_close_position SDK helper also omits the required signed nonce; use the explicit signing path above until the helper exposes it. Close-all is a preview loop:

GET /positions/close-all/{user_id}/{sub_account} returns unsigned reduce-only close orders.
Sign each suggested order.
Submit with POST /orders/batch-create.
Watch fills, then call close-position for each flattened asset.
Re-run the preview after partial fills or price movement.

Getting Started

Integration guides

Flow

Raw REST

tpluspy

Replace semantics

Sub-accounts, transfers, and close-all

​Flow

​Raw REST

​tpluspy

​Replace semantics

​Sub-accounts, transfers, and close-all

Flow

Raw REST

tpluspy

Replace semantics

Sub-accounts, transfers, and close-all