---
title: "Place orders for a user"
url: https://docs.truemarkets.co/gateway/place-orders
description: "Place market and limit orders for a user, list and read them, cancel them, and follow each one to a final state."
---

Docs index: https://docs.truemarkets.co/llms.txt

# Place orders for a user

Every order is a `POST /v1/gateway/orders` with an asset, a size and a type. This page covers the calls you make most: place an order, list and read orders, and cancel one. Every call here carries your organization token and `TM-On-Behalf-Of`, so it acts on that user’s wallet. [Getting started](https://docs.truemarkets.co/gateway/quickstart) walks through signing and executing a market buy.

## Identify the asset

Send the asset's `id` from [the catalog](https://docs.truemarkets.co/gateway/what-you-can-trade) as `asset_id`. Older integrations name the asset with `base_asset` instead. Use `asset_id` for new code.

## Place a market order

A market order executes now at the best available price, so it takes no `price`. Size a buy by what you spend, with `qty_unit: "quote"`. Size a sell by what you sell, with `qty_unit: "base"`.

The response carries the quote and the `payloads` to sign. Nothing moves until you sign them and execute.

**TypeScript**

```typescript title="Buy 2 USDC worth of an asset"
const order = await post(
  "/v1/gateway/orders",
  {
    asset_id: assetId,
    qty: "2",
    qty_unit: "quote",
    side: "buy",
    type: "market",
  },
  forUser,
);
```

**Python**

```python title="Buy 2 USDC worth of an asset"
order = post(
    "/v1/gateway/orders",
    {
        "asset_id": asset_id,
        "qty": "2",
        "qty_unit": "quote",
        "side": "buy",
        "type": "market",
    },
    for_user,
)
```

**curl**

```bash title="Buy 2 USDC worth of an asset"
curl -s -X POST https://api.truemarkets.co/v1/gateway/orders \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "TM-On-Behalf-Of: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "'"$ASSET_ID"'",
    "qty": "2",
    "qty_unit": "quote",
    "side": "buy",
    "type": "market"
  }'
```

## Limit orders

A limit order rests at your `price` until it fills or you cancel it, sized with `qty_unit: "base"`. Limit orders aren't available for every asset yet; the [create order reference](https://docs.truemarkets.co/api/gateway/create-order) has the current rules. On the exchange, the `price` must be a whole number of ticks; see [Sizing](#sizing).

## List and read orders

`GET /v1/gateway/orders` lists the user's orders, newest first. Filter with `status` (comma-separated), and page with `limit` (up to 100) and the `cursor` from `pagination.next_cursor`. An order you created but never executed doesn't appear in the list. Read it by its id.

**TypeScript**

```typescript title="Resting orders, then one order by its id"
const orders = await get(
  "/v1/gateway/orders?status=active",
  forUser,
);

const order = await get(`/v1/gateway/orders/${orderId}`, forUser);
```

**Python**

```python title="Resting orders, then one order by its id"
orders = get("/v1/gateway/orders?status=active", for_user)

order = get(f"/v1/gateway/orders/{order_id}", for_user)
```

**curl**

```bash title="Resting orders, then one order by its id"
curl -s -G https://api.truemarkets.co/v1/gateway/orders \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "TM-On-Behalf-Of: $USER_ID" \
  -d status=active

curl -s https://api.truemarkets.co/v1/gateway/orders/$ORDER_ID \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "TM-On-Behalf-Of: $USER_ID"
```

## Cancel an order

Canceling a resting order is a wallet transaction too, so it works like placing one: the cancel call returns `payloads`, you sign them, and you execute the cancel.

**TypeScript**

```typescript title="Cancel a resting order, sign, execute"
const cancel = await post(
  `/v1/gateway/orders/${orderId}/cancel`,
  {},
  forUser,
);

const signatures = await Promise.all(
  cancel.payloads.map((p) => stamp(p.payload)),
);

await post(
  `/v1/gateway/orders/${orderId}/cancel/execute`,
  {
    signatures,
    auth_type: "api_key",
  },
  forUser,
);
```

**Python**

```python title="Cancel a resting order, sign, execute"
cancel = post(
    f"/v1/gateway/orders/{order_id}/cancel",
    {},
    for_user,
)

signatures = [stamp(p["payload"]) for p in cancel["payloads"]]

post(
    f"/v1/gateway/orders/{order_id}/cancel/execute",
    {
        "signatures": signatures,
        "auth_type": "api_key",
    },
    for_user,
)
```

## Sizing

In a pair such as SOL/USDC, the base asset is the one you buy or sell (SOL), and the quote asset is the one you price it in (USDC). `qty_unit` says which one `qty` counts. Every quantity is a positive decimal string.

| `qty_unit` | Meaning                                              | Allowed on                |
| ---------- | ---------------------------------------------------- | ------------------------- |
| `quote`    | amount of the quote asset to spend, "10 USDC of SOL" | market buy                |
| `base`     | amount of the base asset, "0.01 SOL"                 | market sell, limit orders |

An order that trades on the exchange (`venue: "cefi"`) must also fit the exchange's [increment sizes](https://docs.truemarkets.co/documentation/increment-sizes). The order's price bucket sets a tick size for `price` and a lot size for `qty`, and every order must be worth at least 1.00 in the quote asset. The exchange rejects an order that doesn't fit. A limit `price` must also sit inside the [price bands](https://docs.truemarkets.co/documentation/price-bands).

## Follow an order to a final state

- create → `initialized` → sign + execute → `complete` (filled), final; `active` (a limit order, resting); `pending` (still settling); `failed`, final
- cancel → `cancel_pending` → `canceled`, final

A final status won't change; for any other, read the order again.

An order that isn't in a final state can still change, so read it again until it is.

If `order_id` comes back empty, no order was created, and `quote.issues` says why. Nothing moves until you execute, so you can retry a create that timed out.

## When an order fails

| Status                                    | Meaning                                                                                                                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `201` with an empty `order_id`            | The wallet can't fund the buy. `quote.issues` says why, and no order was created.                                                                            |
| `422` with `insufficient_balance`         | The wallet can't fund a sell or a perpetual order.                                                                                                           |
| `422` with `quote_stale`                  | The quote expired or the price moved before execute landed. Place the order again.                                                                           |
| `403`                                     | The user isn't in your organization, or the asset isn't available in the country your request comes from. `GET /assets/availability` shows what's available. |
| `409` with `already_submitted` on execute | The transaction already landed. Read the order instead of executing again.                                                                                   |

[Errors](https://docs.truemarkets.co/developer-resources/errors) has the error body and the rest of the codes.

## Perpetuals

A perpetual, or perp, is a contract that tracks an asset's price and never expires. Perpetuals aren't available for every asset; the ones that are appear in the catalog with `type: "perp"`.

To open a position, send `leverage`, up to the asset's `perp.max_leverage` in the catalog. Margin is isolated. With `qty_unit: "quote"`, `qty` is the margin you commit and the position's size is `qty` times `leverage`; with `"base"`, `qty` is the position's size. To close a position, send `reduce_only: true` instead.

A `trigger` object turns the order into a take-profit or stop-loss that fires when the mark price crosses `trigger.price`. The [create order reference](https://docs.truemarkets.co/api/gateway/create-order) has every rule.

Next: [What you can trade](https://docs.truemarkets.co/gateway/what-you-can-trade)