Idempotency is a property borrowed from mathematics and distributed systems. An operation is idempotent if performing it multiple times has the same result as performing it once. In order execution, what is idempotency in order execution comes down to one question: if the job fires twice, do you end up with one filled order or two?
The answer determines whether a cron retry, a network timeout, or a process restart silently doubles your position.
What makes automated order submission vulnerable to duplicates
Automated trading runs on scheduled jobs. A job fires at market open, calls the broker API, and submits orders based on fresh signals. Sometimes the API call times out — the broker was slow, a connection dropped, or the job got killed mid-run. The job restarts, or the next scheduled run fires, and it submits the same orders again.
Without a deduplication mechanism, you now hold twice the intended position. The second order had no way to know the first already filled.
This is not a theoretical edge case. Network timeouts in broker APIs are common, cron double-fires happen whenever servers reboot during a scheduled window, and process supervisors restart crashed workers automatically. Any automated trading pipeline that does not handle this will eventually double-buy.
How client_order_id makes order execution idempotent
Alpaca exposes an optional `client_order_id` field — a string you supply when you create an order. If you submit an order with a `client_order_id` that already exists on the account, Alpaca rejects the second request with a clear duplicate error. The first order stands untouched.
The mechanism only works if the ID is deterministic. A random UUID per request breaks idempotency even if you use the field: a job crash followed by a restart generates a new UUID, and Alpaca treats it as a fresh order. You are back to the double-buy problem.
A deterministic ID fixes this. You generate `client_order_id` from a hash or stable concatenation of the inputs that define the order: the signal identifier, the user, and the strategy. The same signal + user + strategy always produces the same string — whether the executor runs once or five times.
What VelaDeck does when Alpaca rejects a duplicate
Each signal in VelaDeck gets a stable ID at creation time. When the executor runs, it derives `client_order_id` deterministically from that signal ID and the user’s identifier. The same signal can only produce one valid order per user.
If Alpaca returns a duplicate rejection, VelaDeck marks that planned-order row as `sent_dedupe` instead of `pending` or `failed`. You can see this status on the dashboard — it means the order was already submitted in a prior run, the position is not doubled, and no action is needed on your end.
This is especially relevant for live trading. Paper trading mistakes reset at your discretion, but a live double-buy costs real money and may need a sell to unwind. VelaDeck does not custody your funds — they remain in your own Alpaca account — and the `client_order_id` mechanism is the primary guard against accidental duplication.
For the full execution flow, see [how VelaDeck automates monthly rebalancing on Alpaca](/blog/how-veladeck-automates-alpaca-rebalancing).
Idempotency is not protection against bad signals
It is worth being precise about the guarantee. Idempotency ensures that a given signal fires at most once per user. It does not ensure the signal was correct. If the ingester pulls a bad composition — a transient data error on the source side — the resulting BUY or SELL order will still execute idempotently once, just on a wrong input.
This is one reason VelaDeck runs in paper mode by default. You can observe signal quality across one or two rebalance cycles before enabling live trading. The opt-in step is intentional — see [how to move from paper to live trading safely](/blog/paper-to-live-trading-safely) for the full checklist.
VelaDeck does not give investment advice. The strategies are third-party AI models, and historical performance is not a forecast of future returns.
SELL orders carry their own dedup logic
Duplicate SELLs carry a different risk than duplicate BUYs. A duplicate BUY inflates your position. A duplicate SELL can over-sell it, creating an unintended short if the position was already flat.
VelaDeck sizes SELL orders from your live Alpaca position at execution time, not from the strategy’s target weight. Before submitting, the executor reads your current quantity and sells exactly that amount. The `client_order_id` then prevents the same signal from triggering a second SELL even after the position is already closed.
If you hold no shares of a ticker and a SELL signal fires, Alpaca rejects the order for insufficient quantity. VelaDeck marks that row with the appropriate status so you can see it clearly on the dashboard without guessing.
You can review all six strategies and assign notional before enabling live trading at [/strategies](/strategies). If you have not yet connected an Alpaca account, [start here](/signup).
What is idempotency in order execution, in one sentence?
It means submitting the same order multiple times results in exactly one fill, because the broker recognizes the duplicate `client_order_id` and rejects every attempt after the first.
What happens if VelaDeck’s cron fires twice in the same day?
The executor derives `client_order_id` from the signal ID and your user identifier. Alpaca rejects the second submission as a duplicate. VelaDeck marks that planned order `sent_dedupe`. Your position is not doubled.
Does idempotency work for both paper and live Alpaca accounts?
Yes. Alpaca enforces `client_order_id` uniqueness in both environments. The same dedup mechanism applies whether you are running on paper or live.
Can I see which orders were deduplicated on the dashboard?
Yes. Each planned order shows a status field. `sent_dedupe` means the order was recognized as a duplicate and skipped — the earlier submission already filled.
Is idempotency enough, or do I also need a monthly cap?
They solve different problems. Idempotency prevents the same signal from executing twice. A monthly cap prevents a legitimate surge of new signals from exceeding your intended spending within a calendar month. VelaDeck supports both. Paper mode lets you observe both mechanisms in action before you switch to live trading.