Spark Client SDK Overview

    The high level description of our order entry interface is as follows:

    service OrderService {
       // RPCs
       rpc create_order(Create) returns (Response)
       rpc cancel_order(Cancel) returns (Response)
       rpc update_order(Update) returns (Response)
       // Streams
       rpc orders (OrdersSub) returns (stream OrderRecord);
       rpc fills (FillsSub) returns (stream Fill);
    }
    

    This description uses the Google Protocol Buffers syntax to define the server interface (we use our own little compiler to generate bindings to this interface in C#, C++ and Excel). Using this server interface we can create, cancel or update orders, using the Remote Procedure Calls (RPCs) defined these orders can be exchange native orders or our own high level algo orders, or new order types created by users via the Spark Server SDK). We can monitor order state by subscribing to the orders stream above, which produces a a stream of OrderRecord objects, each capturing the latest state of a particular order, as it goes through it life cycle.

    An OrderRecord looks like this:

    message OrderRecord {
       uint32 key;
       uint32 parent_key;
       OrderDefinition def;
       OrderState state;
    }
    

    We have an order key, a possibly null parent order key, an OrderDefinition record, which defines the basic elements of the order, namely its type, side, security, account, etc, and an OrderState record, which captures the latest state of the order:

    message OrderState {
       // Standard order state, shared by all order types
       OrderStatus status ;
       double price ;
       uint32 quantity ;
       uint32 filled_quantity;
       double last_price;
       double avg_price;
       string last_msg;
       google.protobuf.Timestamp created;
       google.protobuf.Timestamp last_change;
       // Custom order state, specific to the order type in question
       oneof custom {
          // native order types
          MarketOrderState market;
          LimitOrderState limit;
          StopOrderState stop;
          StopLimitOrderState stop_limit;
          // algo order types
          IcebergOrderState iceberg;
          SpreaderOrderState spreader;
          TimeBoxOrderState time_box;
          TickOrderState tick;
          LeanOrderState lean;
          JoinOrderState join;
          TopOrderState top;evident
          TriggerOrderState trigger;
          CoverOrderState cover;
          OffsetOrderState offset;
          DynamicOrderState dynamic;
       }
    }
    

    This OrderState record consists of a common part, applicable to all order types, and a custom part that is specific to the particular order type the record is associated with. Most of the standard fields should be self-explanatory, the latest price, the latest quantity, the filled quantity, etc. The status enumerate field tells you which state the order is in. We currently define the following states:

    enum OrderStatus {
       // The order has been constructed but not acted on. Inactive orders
       // can be abandoned without consequences. This state should only be
       // used internally by the order manager, i.e. it should never appear
       // in externally visible orders.
       ORDER_STATUS_INACTIVE = 0;
       // The order is currently working, i.e. its algorithm is operating.
       ORDER_STATUS_WORKING = 1;
       // The order has completed successfully and accomplished its
       // goal. This is a terminal state.
       ORDER_STATUS_COMPLETED = 2;
       // The order was terminated orderly before it had a chance to
       // complete. This is a terminal state.
       ORDER_STATUS_CANCELED = 3;
       // The order has encountered an unexpected condition from which it
       // cannot recover. This a terminal state.
       ORDER_STATUS_ERROR = 4;
       // The last known state for this order was ORDER_STATUS_WORKING, but
       // since then the execution gateway has signaled a disconnect. This
       // is not a terminal state.
       ORDER_STATUS_DISCONNECTED = 5;
       // The order is initializiYou can ng. It cannot be modified at this
       point.
       ORDER_STATUS_PENDING_WORKING = 6;
       // The order is invalid and was rejected by Spark (not the
       // exchange), on creation. This is a terminal state.
       ORDER_STATUS_REJECTED_BY_SPARK= 7;
    }
    

    Threading

    Check out our API Threading Doc here.