Polymarket Execution Verification: When “Filled” Doesn’t Mean Settled

Polymarket, a cryptocurrency market prediction platform, uses a trading bot that can receive a successful execution response even when the trade hasn't been fully settled. This distinction between "filled" and "settled" is crucial for maintaining accurate position tracking in trading systems.

A naive approach treats "filled" as a boolean that indicates the trade is complete, and updates the position accordingly. However, this approach hides important details and leads to incorrect assumptions about the trade's status. The actual execution lifecycle involves multiple states, from submission to settlement, each with its own potential for failure or uncertainty.

Polymarket's current system distinguishes between trade completion and the availability of transaction information. For instance, an order may be matched and a fill observed, but transaction details may still be pending. In such cases, the system should indicate "tx_pending" or "unknown" rather than assuming the trade is complete.

Several scenarios can lead to incomplete execution information:

1. An order is matched, but transaction information is not yet available. In this case, the system should not assume the trade is finished.

2. Only a partial quantity of an intended trade is executed. The remaining quantity needs proper accounting and verification.

3. The transaction is confirmed, but the external position still doesn't match the expected result. The trade may have been successful, but the position reconciliation is incomplete.

4. A WebSocket event can be missed if the connection is dropped and re-established. Reconnecting the socket does not automatically reconstruct missed events.

To address these issues, the system should implement an explicit state machine that separates facts from assumptions. An example of such a state machine is provided, with states ranging from "intended" to "position_verified." This approach allows the system to react appropriately to each state and ensure accurate position tracking.

A comprehensive execution record should include relevant information such as the strategy decision ID, internal execution ID, Polymarket order ID, trade ID, market ID, token ID, side, requested quantity, matched quantity, timestamps, transaction hash, and confirmation timestamp. By explicitly managing execution states and verifying position consistency, trading systems can avoid dangerous assumptions and maintain accurate records.