Sending an order from code

This is the chapter the whole course has been circling. Everything so far has been safe: reading data, taking in a feed, none of it moves a rupee. Placing an order does. So learn it here, in the one place it is harmless, against the simulated broker, and carry a healthy caution for when the same code later meets a real one. The mechanics are simple. The consequences, live, are not.

The three actions

Managing orders from code comes down to three actions, and you already have them on the simulated broker. You place an order to open or close a position. You modify an order that is still working, to change its price or size. And you cancel an order you no longer want. Here are all three, plus a market order that fills at once, each tagged with a client id you choose.

# Placing and managing an order from code, against the simulated broker. Every
# order carries our own client id so we can always find it again. The identical
# logic against a REAL broker spends real money, and is shown but never run.
from paper_broker import PaperBroker

broker = PaperBroker(cash=1_000_000, prices={"RELIANCE": 1400})

# A limit buy below the market, tagged with a client id we choose.
order = broker.place_order("RELIANCE", "BUY", 100, "LIMIT", price=1390,
                           client_order_id="entry-001")
print(f"Placed    {order.client_order_id}: {order.status}  {order.quantity} @ {order.price}")

# Change our mind on the price (modify), then read it back.
broker.modify_order(order.order_id, price=1385)
print(f"Modified  {order.client_order_id}: {order.status}  {order.quantity} @ {order.price}")

# Decide not to trade after all (cancel).
broker.cancel_order(order.order_id)
print(f"Cancelled {order.client_order_id}: {order.status}")

# A separate market order that fills right away.
mkt = broker.place_order("RELIANCE", "BUY", 10, "MARKET", client_order_id="mkt-002")
print(f"Market    {mkt.client_order_id}: {mkt.status}  {mkt.filled_quantity} @ {mkt.average_price}")

print("Funds:    ", broker.get_funds())
print("Positions:", broker.get_positions())

Placed    entry-001: OPEN  100 @ 1390
Modified  entry-001: OPEN  100 @ 1385
Cancelled entry-001: CANCELLED
Market    mkt-002: FILLED  10 @ 1400.0
Funds:     {'available_cash': 986000.0}
Positions: [{'symbol': 'RELIANCE', 'quantity': 10, 'avg_price': 1400.0}]

Walk the output. The limit order to buy 100 at 1,390 is placed and rests, OPEN, because the market is at 1,400 and has not reached the limit. You modify its price down to 1,385, and it is still OPEN, now at the new price. You cancel it, and it becomes CANCELLED, having never traded. Then a market order to buy 10 fills immediately at 1,400, and your cash and position move. Placing, changing, and cancelling: that is the whole vocabulary of managing orders, and it is the same against a real broker.

# Placing a REAL order via a broker's SDK, shown generically and NOT run.
# A live order spends real money the instant it fills. Do not run anything like
# this until very late in the course, and even then only at the smallest size.
order_id = client.place_order(symbol="NSE:RELIANCE", side="BUY", quantity=1,
                              order_type="LIMIT", price=1390,
                              tag="my-strategy-001")     # your client-side id

Give every order a name

Notice that every order in the example carried a client_order_id, a label you set, such as "entry-001". This is not decoration; it is how a program keeps its sanity. Once your code has sent an order, it needs to recognise that order again later, in the stream of confirmations coming back, to know it was accepted, filled, or rejected. A client id you assign lets you match "the order I sent" to "the order the broker is telling me about," even across a restart or a lost connection. An order manager, which you build in the next part, leans on these ids completely. Get into the habit now: every order your program sends gets its own id.

A recap of order types, now automated

The order types you met in Stock Market Basics matter more when a program places them. A market order trades immediately at the best available price, and its danger is that you do not choose the price, which for a fast or thin stock can be far from what you saw. A limit order trades only at your price or better, giving you control of price but no guarantee of a fill. Stop orders, which trigger once a level is crossed, exist too, and a real broker offers them; the simulated broker here keeps to market and limit, which are enough to learn on. In an automated system the choice is consequential. A program firing market orders at speed can pay far more in slippage than a human would, a cost the reality chapters will measure. Choose the order type deliberately, not by habit.

The weight of this one action

It is worth sitting with the difference between this chapter and the ones before it. Reading data, you could run against a real account safely all day. Placing orders, you cannot. Every safeguard the rest of this course builds, the order manager that tracks state, the reconciliation that trusts the broker, the risk gate that can say no, exists because this one action has consequences that the earlier ones do not. That is why you learn it against the simulator, and why going live remains many chapters away.

What to carry forward

Managing orders from code is three actions: place, modify, and cancel, and you ran all three safely against the simulated broker, watching a limit order rest, change price, and cancel, and a market order fill. Every order should carry a client id you assign, because that is how a program recognises its own orders in the replies that come back, which the next part depends on. The order types from Stock Market Basics carry real weight here: market for certainty of a fill, limit for certainty of price, chosen deliberately because a program pays for a careless choice. Above all, this is the one action that moves money, which is why you learn it in the sandbox. You can now read, stream, and order. The next part makes those orders reliable, starting with the life of a single order from the moment you send it.