NAV

Introduction

Institutions can use the FIX Drop Copy feed to receive confirmations of trades on the Gemini exchange. This will only report the trades themselves, not cancels or order placements.

There are no client-originated messages supported on this channel except for the session-management ones.

Survey

Please complete our API Use Survey to help us improve your experience using the Gemini APIs.

FIX Dictionary

Gemini uses FIX 4.4 with the 20030618 errata.

Of particular note if you may be using an older dictionary:

Tag Field Value Notes
234 StipulationValue FIX enum but should allow other values. Compatible with Errata 20030618 Vol 6 - see p. 86.

Custom tags

Tag Field Type Notes
9000 RiskLiquidityFlag Boolean Used in NewOrderSingle <D> Indicates whether or not the order should match against Liquidation Orders sent from the Liquidation Engine. Only allowed from permissioned Market Makers.
9001 CancelOnDisconnect Boolean Used in Logon <A> to enable or disable session-level cancel on disconnect.
9002 MDEntryMakerSide Char Used in Market Data - Incremental Refresh <X> MDEntry groups when MDEntryType had the value 2 = Trade to indicate the maker side of a trade. See Examples: Request to enable maker side on trades.
9003 EnableMDEntryMakerSide Boolean Used in Market Data Request <V> to optionally enable showing custom field 9002 MDEntryMakerSide in Market Data - Incremental Refresh <X> messages when MDEntryType had the value 2 = Trade. See Examples: Showing Maker Side For Trades.
9009 MDEntryFundingIsRealized Boolean Used in Market Data - Incremental Refresh <X> MDEntry groups when MDEntryType had the value S = Funding Amount to indicate the IsRealized field of Funding Amount.
9008 EventId Int Used in Market Data - Incremental Refresh <X> to specify the event associated with the update. This is for information only and may not be used to form a business logic. See Examples: market data responses send to clients.

Download

For your convenience, Gemini maintains our custom dictionary in QuickFIX XML form:

Environment File
Production https://docs.gemini.com/files/gemini-fix-dictionary.xml.zip
Sandbox https://docs.sandbox.gemini.com/files/gemini-fix-dictionary.xml.zip

Connecting

Gemini's primary trading platform and network point of presence (PoP) is housed in the Equinix NY5 data center in Secaucus, New Jersey. Customers can cross connect from their NY2/NY4/NY5 infrastructure or leverage an approved extranet provider to access Gemini production Market Data feeds, Drop Copy, and Order Entry sessions.

We are also nearing completion of a PoP in Equinix CH3 which will be available via cross connects from the Equinix family of data centers in Chicago and approved extranet providers.

Steps to get connected to our FIX infrastructure:

Complete Account Verification

If your firm has not done so already, please complete the Institutional Account Verification Process

Get connected

Once on-boarded as a Gemini customer, email connectivity@gemini.com with a brief description of your business and your preferred connectivity method. There are 3 options for production FIX connectivity to Gemini:

Cross-connect

For customers with applications in the same data center as Gemini. If you would like to cross-connect, please include the legal entity name that we should include in our LOA (letter of authorization).

Extranet connectivity

Customers who are not in the Equinix family of data centers can leverage an extranet provider to connect to Gemini. If your firm wishes to leverage an extranet provider or third party to connect, please specify that in your email including the providers name.

Third Party Order Management System Provider

There are a number of Service providers that allow Gemini customers to leverage their trading platforms to connect to Gemini for trading. If you would like to cross-connect, please include the legal entity name that we should include in our LOA (letter of authorization). If your firm wishes to leverage an extranet provider or third party to connect, please specify that in your email including the providers name.

Sandbox and Testing

Gemini operates a Sandbox environment which acts as a replica of our production environment. Gemini strongly recommends that all FIX customers create a Sandbox account to test their workflows. Please follow these steps to get a FIX Sandbox environment setup:

Setup a Sandbox Account

Create a Sandbox account by going to: https://sandbox.gemini.com

Permission Your Test IP

E-mail connectivity@gemini.com and specify the email address used to setup your Sandbox account and the Source IP that you will be using to connect to the FIX Sandbox. We will respond back once the IP addresses have been enabled. We will also provide you with the Sender and Target CompId that should be used to connect to the test environment.

Test Your Workflow Thoroughly

Test all messaging workflows specified in our FIX API documentation. (Gemini currently only supports FIX 4.4)

Workflow

Gemini will report all trades on the exchange using Trade Capture Report <AE>.

Trades can occur via orders placed using:

Drop Copy reports on trades from all of these sources, distinguished by the value supplied in the PartyID <448> field.

Precision on the exchange

Quantity and price on incoming orders are strictly held to the minimums and increments on the table shown above.

However, once on the exchange, quantities and notional values may exhibit additional precision down to two decimal places past the "minimum order increment" listed above. For instance, it is possible that a btcusd trade could execute for a quantity of 0.0000000001 (1e-10) BTC. This is due to:

This additional precision is marketable once on the exchange.

Your account balances are maintained to full fractional precision in each currency.

Understanding price and quantity

In a Trade Capture Report <AE>, the LastQty <32> field is denominated in BTC and the LastPx <31> field is denominated in USD.

RAW
8=FIX.4.4|9=236|35=AE|34=17|49=GEMINI|52=20160301-21:38:35.688|56=CLIENT-DC|31=301.42|32=0.02|55=BTCUSD|60=20160301-21:38:35.591|75=20160301|570=N|571=40987|552=1|54=1|37=40979|11=ORD1|453=1|448=CLIENT-OE|447=D|452=11|12=0.120568|13=3|479=USD|58=TAKER|10=085|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 236
       34                     MsgSeqNum: 17
       35                       MsgType: TradeCaptureReport (AE)
       49                  SenderCompID: GEMINI
       52                   SendingTime: 20160301-21:38:35.688
       56                  TargetCompID: CLIENT-DC
BODY
       31                        LastPx: 301.42
       32                       LastQty: 0.02
       55                        Symbol: BTCUSD
       60                  TransactTime: 20160301-21:38:35.591
       75                     TradeDate: 20160301
      570            PreviouslyReported: N
      571                 TradeReportID: 40987
    NoSides: count = 1
           11                       ClOrdID: ORD1
           12                    Commission: 0.120568
           13                      CommType: ABSOLUTE (3)
           37                       OrderID: 40979
           54                          Side: BUY (1)
           58                          Text: TAKER
          479                  CommCurrency: USD
        NoPartyIDs: count = 1
              447                 PartyIDSource: PROPRIETARY_CUSTOM_CODE (D)
              448                       PartyID: CLIENT-OE
              452                     PartyRole: ORDER_ORIGINATION_TRADER (11)
TRAILER
       10                      CheckSum: 085

Currency-based messages and fields

Fees

The amount in Commission <12> is denominated in the currency specified by the currency code value in CommCurrency <479>.

Identifiers

Client supplied FIX identifier field values must contain between at least one and up to one hundred allowed characters.

Any exchange-bound message containing an invalid identifier will be rejected.

Allowed characters

Client supplied identifier values should match against this PCRE regular expression: [:\-_\.#a-zA-Z0-9]{1,100}.

Characters Description ASCII Codes (Dec)
A-Z Uppercase A-Z 65 - 90
a-z Lowercase a-z 97 - 122
0-9 Digits 48 - 57
# Hash, octothorpe, number sign 35
- Hyphen 45
. Period 46
: Colon 58
_ Underscore 95

Client supplied identifiers

Identifiers assigned by Gemini

Standard header

The Standard Header is required on every message.

PossResend <97> is not supported. Gemini will report the last sequence number that the exchange received in the header of the Logon <A> message. The client should assume that any events that the server requests to be replayed have not been acted upon: see Beginning a session for details.

Standard Trailer

The Standard Trailer is required on every message.

Session-Level Messages

Establishing a connection

  1. Client sends server → Logon <A> message
  2. Is client ResetSeqNumFlag <141> to Y?
    • Yes, reset sequence numbers and proceed
      • server resets next expected client sequence number
      • server resets its own sequence number
      • server responds with ← Logon <A> message with reset sequence number
      • client sends server → Heartbeat <0>
    • No, negotiate sequence numbers on both sides
      1. Is client MsgSeqNum <34> value what the server is expecting?
      2. Is server MsgSeqNum <34> value what the client is expecting?
        • No, value is greater than expected
        • No, value is less than expected
          • client disconnects or sends server → Logout <5>
          • Gemini coordinates with the client to triage so the FIX connection can be re-established
        • Otherwise
  3. Success! Your FIX connection is established.

When can sequence numbers be reset?

Gemini runs the server side of the FIX connection ("acceptor"). Gemini never resets sequence numbers on the server side during the logon workflow unless the client explicitly requests it.

The client ("initiator") can reset sequence numbers during Logon <A> by setting ResetSeqNumFlag <141> to Y.

Gemini recommends that client consider configuring the FIX initiator to automatically reset sequence numbers under the following conditions:

While synchronizing sequence numbers after a replay, the client may send a Sequence Reset <4> with GapFillFlag <123> = Y in lieu of a replay.

Ending a connection

The client may send the server an optional Logout <5> message but the exchange will not interpret its absence as being an abnormal condition.

Under certain conditions, the server may send the client a Logout <5> message where the Text <58> field contains the reason, such as scheduled maintenance.

Logon <A>

The Logon <A> message must be the first message sent by the application requesting to initiate a FIX session. The Logon <A> message authenticates an institution establishing a connection to Gemini.

Upon receipt of a Logon <A> message, Gemini will authenticate the institution requesting connection by validating the source IP Address, SenderCompID <49>, and TargetCompID <56> identifying the institution. The server will then issue a Logon <A> message as acknowledgment that the connection request has been accepted. The acknowledgment Logon <A> can also be used by the institution to validate that the connection was established with the correct party. If validation fails, the connection will be dropped without a Reject <3>.

Heartbeat <0>

The Heartbeat <0> monitors the status of the communication link and identifies when the last of a string of messages was not received. The only supported heartbeat interval, as specified by the Logon <A> message, is 30 seconds.

When either end of a FIX connection has not sent any data for HeartBtInt <108> seconds, it will transmit a Heartbeat <0> message. When either end of the connection has not received any data for (HeartBtInt <108> + "some reasonable transmission time") seconds, it will transmit a Test Request <1> message. If there is still no Heartbeat <0> message received after (HeartBtInt <108> + "some reasonable transmission time") seconds then the connection should be considered lost and corrective action be initiated.

Note that a Test Request <1> message can still be sent independent of the value of the HeartBtInt <108>, which will force a Heartbeat <0> message.

Heartbeats issued as the result of Test Request <1> must contain the TestReqID <112> transmitted in the Test Request <1> message. This is useful to verify that the Heartbeat <0> is the result of the Test Request <1> and not as the result of a regular timeout.

Test Request <1>

The Test Request <1> message forces a heartbeat from the opposing application. The Test Request <1> message checks sequence numbers or verifies communication line status. The opposite application responds to the Test Request <1> with a Heartbeat <0> containing the TestReqID <112>.

The TestReqID <112> verifies that the opposite application is generating the heartbeat as the result of Test Request <1> and not a normal timeout. The opposite application includes the TestReqID <112> in the resulting Heartbeat <0>. Any string can be used as the TestReqID <112> (one suggestion is to use a timestamp string).

Resend Request <2>

The resend request is sent by the receiving application to initiate the retransmission of messages. This function is utilized if a sequence number gap is detected, if the receiving application lost a message, or as a function of the initialization process.

The resend request can be used to request a single message, a range of messages or all messages subsequent to a particular message.

Note: the sending application may wish to consider the message type when resending messages; e.g. if a new order is in the resend series and a significant time period has elapsed since its original inception, the sender may not wish to retransmit the order given the potential for changed market conditions. (The Sequence Reset <4> - Gap Fill message is used to skip messages that a sender does not wish to resend.)

Note: it is imperative that the receiving application process messages in sequence order, e.g. if message number 7 is missed and 8-9 received, the application should ignore 8 and 9 and ask for a resend of 7-9, or, preferably, 7-0 (0 represents infinity). This latter approach is strongly recommended to recover from out of sequence conditions as it allows for faster recovery in the presence of certain race conditions when both sides are simultaneously attempting to recover a gap.

Reject <3>

Gemini sends a Reject <3> message when a message is received but cannot be properly processed due to a session-level rule violation. A reject is typically a serious error in the trading application's session logic. A session reject would also be generated if client message rate has exceeded the allocated throttle.

Sequence Reset <4>

The Sequence Reset <4> message is used in response to a Resend Request <2> message when one or more messages must be skipped over for the following reasons:

Gemini does not support Reset mode (GapFillFlag <123> not present or equal to N).

Logout <5>

The Logout <5> message initiates or confirms the termination of a FIX session.

Business Message Reject <j>

Gemini sends Business Message Reject <j> when the exchange receives a valid FIX message which cannot be processed.

Examples include:

Gemini does not use Business Message Reject <j> to handle invalid New Order Single <D> messages. Rejected orders are handled with an Execution Report <8> message with an OrdStatus <39> field with a value of 8 - Rejected.

Party IDs and Roles

Trade capture reports for trades placed by your own account use one party ID with the following PartyRole <452> value:

Field Tag Value
NoPartyIDs 453 1
First Group
PartyID 448 The API session key of the REST or FIX session that placed the order; "UI" when placed using the website.
PartyRole 452 11 = Order Origination Trader
PartyIDSource 447 D = Proprietary/Custom Code

Third Party Support

When an OMS/OEMS account is set up to place orders on behalf of one or more other accounts, this account will receive trade capture reports for:

When an order is placed, the trade capture report will contain two party IDs with the following PartyRole <452> values:

Field Tag Value
NoPartyIDs 453 2
First Group
PartyID 448 The API session key of the REST or FIX session that placed the order; "UI" when placed using the website.
PartyRole 452 11 = Order Origination Trader
PartyIDSource 447 D = Proprietary/Custom Code
Second Group
PartyID 448 The OnBehalfOfCompID <115> assigned to the account the order was placed on behalf of
PartyRole 452 1 = Executing Firm
PartyIDSource 447 D = Proprietary/Custom Code

Client-Bound Messages

Trade Capture Report <AE>

Gemini will send a Trade Capture Report <AE> for all fills against orders placed by the client.

This includes orders from all FIX sessions, REST sessions, and orders entered through the UI. See Party IDs and Roles and Third Party Support for a detailed explanation of how party IDs and roles are used.

Examples

These are examples of drop copy messages sent to the client.

Buy Limit Order

In this example, TRADEBOTDC002 receives a trade capture report showing that a limit order identified by ClOrdID <11> KsL0nZY2gLLJSvuY6Z was filled for 0.001 BTC at 8490.50 USD.

RAW
8=FIX.4.4|9=270|35=AE|34=2|49=GEMINI|52=20180425-18:08:42.445|56=TRADEBOTDC002|31=8490.50|32=0.001|55=BTCUSD|60=20180425-18:08:42.444|75=20180425|570=N|571=335278183|552=1|54=1|37=335278181|11=KsL0nZY2gLLJSvuY6Z|453=1|448=TRADEBOTOE002|447=D|452=11|12=0.008490500|13=3|479=USD|58=TAKER|10=217|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 270
       34                     MsgSeqNum: 2
       35                       MsgType: TradeCaptureReport (AE)
       49                  SenderCompID: GEMINI
       52                   SendingTime: 20180425-18:08:42.445
       56                  TargetCompID: TRADEBOTDC002
BODY
       31                        LastPx: 8490.50
       32                       LastQty: 0.001
       55                        Symbol: BTCUSD
       60                  TransactTime: 20180425-18:08:42.444
       75                     TradeDate: 20180425
      570            PreviouslyReported: N
      571                 TradeReportID: 335278183
    NoSides: count = 1
           11                       ClOrdID: KsL0nZY2gLLJSvuY6Z
           12                    Commission: 0.008490500
           13                      CommType: ABSOLUTE (3)
           37                       OrderID: 335278181
           54                          Side: BUY (1)
           58                          Text: TAKER
          479                  CommCurrency: USD
        NoPartyIDs: count = 1
              447                 PartyIDSource: PROPRIETARY_CUSTOM_CODE (D)
              448                       PartyID: TRADEBOTOE002
              452                     PartyRole: ORDER_ORIGINATION_TRADER (11)
TRAILER
       10                      CheckSum: 217

Buy Limit Order on Behalf of Third Party

In this example, TRADEBOTDC001, an OMS, has placed a third-party order on behalf of an account identified by AA1AA1AAA1.

RAW
8=FIX.4.4|9=297|35=AE|34=2|49=GEMINI|52=20180425-17:50:34.508|56=TRADEBOTDC001|31=8490.68|32=0.001|55=BTCUSD|60=20180425-17:50:34.506|75=20180425|570=N|571=335278079|552=1|54=1|37=335278077|11=opFrFzIMQksPhSVfvx|453=2|448=TRADEBOTOE001|447=D|452=11|448=AA1AA1AAA1|447=D|452=1|12=0.021226700|13=3|479=USD|58=TAKER|10=028|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 297
       34                     MsgSeqNum: 2
       35                       MsgType: TradeCaptureReport (AE)
       49                  SenderCompID: GEMINI
       52                   SendingTime: 20180425-17:50:34.508
       56                  TargetCompID: TRADEBOTDC001
BODY
       31                        LastPx: 8490.68
       32                       LastQty: 0.001
       55                        Symbol: BTCUSD
       60                  TransactTime: 20180425-17:50:34.506
       75                     TradeDate: 20180425
      570            PreviouslyReported: N
      571                 TradeReportID: 335278079
    NoSides: count = 1
           11                       ClOrdID: opFrFzIMQksPhSVfvx
           12                    Commission: 0.021226700
           13                      CommType: ABSOLUTE (3)
           37                       OrderID: 335278077
           54                          Side: BUY (1)
           58                          Text: TAKER
          479                  CommCurrency: USD
        NoPartyIDs: count = 2
              447                 PartyIDSource: PROPRIETARY_CUSTOM_CODE (D)
              448                       PartyID: TRADEBOTOE001
              452                     PartyRole: ORDER_ORIGINATION_TRADER (11)
            ----
              447                 PartyIDSource: PROPRIETARY_CUSTOM_CODE (D)
              448                       PartyID: AA1AA1AAA1
              452                     PartyRole: EXECUTING_FIRM (1)
TRAILER
       10                      CheckSum: 028

Revision History

Date Notes
2016/03/23 Initial FIX Drop Copy API documentation
2018/02/22 New Feature: Document Third Party Support. Clarify usage of Party IDs and Roles.
2018/04/06 New Feature: Document block trading support.
2018/05/18 Add additional examples of Drop Copy messages.
2018/09/21 Updated OMS third party trade capture report example.
2022/06/23 Deprecating documentation for Auction and Block trading support