PhoenixPerpetualsDocs API v1
Get an API key

Working with the API

Idempotency⁠.

Why a lost answer never places a second order: the Idempotency-Key, what a retry gets back, and your own order ids.

View as Markdown

On this page
  1. Where it is required
  2. What a retry gets
  3. Your own order ids
  4. A recovery that always works

A connection can drop after your order reached us and before the answer reached you. Did the order go through? With an Idempotency-Key, you never have to guess: send the same call again with the same key, and you get the first call's result instead of a second order.

Where it is required#

Every call that creates something or acts on the market takes an Idempotency-Key header, and is refused with idempotency_key_required without one:

Call
POST /v1/accounts/{account_id}/ordersPlace an order
POST /v1/accounts/{account_id}/orders/cancel-allCancel every order
POST /v1/accounts/{account_id}/positions/{market}/closeClose a position
POST /v1/accounts/{account_id}/flattenClose everything
POST /v1/accounts/{account_id}/strategiesStart a strategy
POST /v1/accountsOpen a sandbox account

PUT and DELETE calls say what the end state should be, never what to add, so sending one twice changes nothing: they need no key. A change of an order (PATCH .../orders/{order_id}) takes a key when you give one: the same change sent again under it is done once. Without a key, a change is sent once and never again by the SDKs (a size changed again after a partial fill would not be the same change).

The key is any string of 1 to 128 printable characters that you never reuse for another call: a UUID is ideal. The SDKs make one for every such call and keep it across their own retries.

What a retry gets#

The key is remembered for 24 hours, for your API key and that call: the account and the market in its path are part of it. The same key on another account or market is another call, and it is done.

You sendYou get
The same key and the same bodyThe first call's result, with Idempotent-Replayed: true. For an order, the order as it is now (filled since, for example)
The same key while the first call is still running409 operation_in_progress with Retry-After: 1: ask again in a second
The same key with a different body400 idempotency_key_reused: nothing is done

A refusal for good counts as a result when the order reached the trading servers: the retry gets the same refusal, with the same order_id. A refusal that says retryable: true (the account not ready yet, no price, the engine busy) is no result: send the call again with the same key and the same client_order_id and it is done again (the refused attempt stays readable under its own order_id). A call refused before the trading servers (a field missing, a size off the step) keeps nothing, so you can fix it and send it again with the same key.

Your own order ids#

Give an order your own client_order_id (1 to 64 characters: letters, digits, ., _, : and -) and you can find it again from anywhere, even from another process or with another key: GET /v1/accounts/{account_id}/orders?client_order_id=momentum-0142. It is unique across your accounts in its environment: a second order with the same client_order_id is refused with client_order_id_conflict, the first one named in order_id. Strategies take a client_strategy_id the same way (the programs: oco, twap, vwap, scaled, chase). A program whose orders are refused when it starts made nothing: the error answers, and its client_strategy_id is free to use again.

A recovery that always works#

When a call that places an order fails without an answer:

  1. Send it again, same key, same body. You get the order, placed once.
  2. If you cannot (your process restarted and lost the key), look it up by its client_order_id.
  3. If the order shows unconfirmed, the trading servers' answer was lost on the way: read it again a second later and it settles.

Guides, endpoints, fields and error codes.