// GLOSSARY

Idempotency key

A unique client-generated ID sent with an order so that retries don't create duplicates. If the first request succeeded but the response was lost, resending with the same key returns the original order instead of placing a second one.

The nastiest failure in trading APIs is the ambiguous timeout: you sent an order, the connection dropped, and you don't know whether it was placed. Retry blindly and you might double your position; don't retry and you might have no position at all.

How the key fixes it

You attach a unique ID (a UUID, or a client order ID) to the request. The server remembers it: a retry with the same key is recognized as the same order and returns the original result rather than creating a new one. Kalshi supports a client-supplied order ID for this purpose, and Polymarket orders are identified by their signed payload — check each venue's docs for the exact deduplication semantics rather than assuming them.

Worked example

Your bot sends a 500-contract buy, hits a 30-second timeout, and retries twice with the same key. Whatever happened on the wire, at most one order exists. Without the key, the worst case is three.

Idempotent order placement is table stakes for unattended bots — it's part of the reliability checklist in rate limits and order types.