Day 33 — UUID Generator: Creating Unique Tracking IDs for Orders
What you will build today: A production-grade, thread-safe order ID system that prevents double-fills, survives API failures, and gives you forensic traceability during live incidents — all in under 300 lines of Python.
Before You Start
What you need to know already:
Basic Python classes and
dataclassesWhat a thread is and roughly why two threads sharing data can cause bugs
What an API is — you have called one before, even if it was just a weather API
What you will understand by the end:
Why generating an order ID wrong can cause you to accidentally buy twice the stock you intended
How Python’s
itertools.countgives you atomic incrementing without a lockWhat idempotency means and why it is one of the most important words in distributed systems
How to structure an ID that tells a story — so when something goes wrong at 9:31 AM on an earnings day, you can find the offending order in seconds
The str(time.time()) Trap
Picture this. You are three weeks into live paper trading. Your system has been running clean. Then one morning, the Alpaca API returns a 503 Service Unavailable. Your retry logic fires. It builds a new order request. And because you wrote this line in week one —
order_id = f"ORD-{int(time.time() * 1000)}-{random.randint(1000, 9999)}"
— it generates a brand new ID on the retry.
The broker never saw the first request fail. It was a network hiccup, not a server reject. The original order was already queued. Now you have just submitted a second, fresh order for the same stock.
You are long 2x your intended size in a name moving 8% in the wrong direction.
This is the double-submit problem, and it is the most common cause of unexpected position sizing in beginner algo systems. The fix is not complicated, but you have to understand why it happens before you can understand why the fix works.
The Three Failure Modes
1. Non-idempotent retry
The word idempotent means: do it once, do it ten times, the result is the same.
Alpaca’s API is designed to support idempotent order submission. If you submit an order with a client_order_id it has already seen, it returns the existing order and does nothing new. But this guarantee only holds if you send the same client_order_id on every retry. The moment you generate a new one, the broker has no way to know you already tried — and it creates a second live order.
2. Timestamp collision at scale
At 1ms resolution, two orders submitted in the same millisecond on the same thread share a prefix. Add four digits of random.randint and you have 10,000 possible values per millisecond. That sounds like a lot until your strategy fires a burst of 50 orders during a volatility spike and two of them land in the same millisecond with the same four-digit suffix.
Collision probability: not zero.
3. Structureless IDs destroy incident response
When your risk system pages you at 3 AM because your P&L is –$4,000, you need to answer one question in under 30 seconds: which strategy, which session, and which order in that session caused this?
A raw UUID4 like f47ac10b-58cc-4372-a567-0e02b2c3d479 answers none of those questions. You are grepping 50,000 log lines blind, under pressure, while the position is still open.
The AutoQuant-Alpha Architecture: StructuredOrderID
The solution is a three-layer ID scheme that is collision-resistant, human-readable under pressure, and stable across retries.
{STRATEGY}-{SESSION}-{SEQUENCE:06d}-{UUID4_PREFIX}
MOM 1RV4K2 000001 a3f8b2c1
Full example: MOM-1RV4K2-000001-a3f8b2c1 (25 chars)
Alpaca limit: 48 chars ✓
The full UUID4 is stored internally for exchange-level reconciliation. The client_order_id field sent to the broker is the short structured form — readable, sortable, and stable.
