Core concepts

Asynchronous operations

Track queued Koneth account and finance commands to completion.

Most account and finance mutations are asynchronous. A successful request returns 202 Accepted and a command instead of waiting for the target trading server to finish.

Command lifecycle

queued → leased → succeeded
               ↘ failed
queued ─────────→ expired

Status	Meaning
`queued`	Koneth accepted the operation and is waiting for the target server.
`leased`	The target server is processing the operation.
`succeeded`	The operation completed. Read `result` for its output.
`failed`	The operation stopped with an error. Read `errorCode` and `errorMessage`.
`expired`	The command could not complete within its delivery lifecycle.

Poll a command

Use the command ID from the mutation response:

curl --request GET \
  --url "https://api.koneth.com/api/v1/management/commands/$COMMAND_ID" \
  --header "Authorization: Management $KONETH_API_KEY"

Poll with exponential backoff and stop when the status is succeeded, failed, or expired.

const terminalStates = new Set(["succeeded", "failed", "expired"]);

for (let attempt = 0; attempt < 8; attempt += 1) {
  const response = await fetch(
    `https://api.koneth.com/api/v1/management/commands/${commandId}`,
    { headers: { Authorization: `Management ${process.env.KONETH_API_KEY}` } },
  );
  const { command } = await response.json();

  if (terminalStates.has(command.status)) {
    return command;
  }

  await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 500));
}

throw new Error("Command did not reach a terminal state in time");

Handle completion

Do not mark your local operation complete when you receive 202. Persist the command ID and wait for a terminal status.

On succeeded, apply the returned result to your local record.
On failed, surface errorCode and errorMessage to an operator.
On expired, reconcile the account state before deciding whether to submit a new operation.