NAV

Gemini Clearing

Gemini Clearing allows two parties to settle a trade off the order book. The initiator enters the trade details for any supported symbol and generates a clearing_id (OrderID <37>). If a counterparty_id is supplied, only the specified counterparty can confirm the order. If a counterparty_id is not supplied, then Gemini will generate a clearing_id (OrderID <37>) that can filled by any counterparty.

Workflow

Bilateral Trade

  1. Initiator places a clearing order with the order details
  2. Did the initiator use a counterparty_id?
    • Yes, only the Gemini account associated with the counterparty_id will be able to complete the order.
    • No, anybody with the clearing_id will be able to confirm the order.
  3. The counterparty will be able to confirm the order on the web interface, via FIX, or via REST
    • The order initiator can cancel the order if the counterparty has not yet confirmed. Cancellation can be performed on the web interface, via FIX, and REST.
  4. Once confirmed, Gemini will attempt settlement. Settlement can only occur when both parties have the funds required in their account to fill the trade.
    • If any party does not post the funds required to settle the trade before the expiration time, then the order will expire.

Broker Trade

  1. The broker submits a clearing order with the order details and both counterparty_ids of the buyer and seller.
  2. The buy and seller can both review the trade details and confirm the order on the web interface, via FIX, or via REST
    • Either side can cancel the trade if both the buyer and seller have yet to confirm the order. Cancellation can be done via the web interface, FIX, and REST
    • The broker will be able to see the the status of the order on the web interface and over the /v1/clearing/status endpoint on the REST API
  3. Once confirmed, Gemini will attempt settlement. Settlement can only occur when both parties have the funds required in their account to fill the trade.
    • If any party does not post the funds required to settle the trade before the expiration time, then the order will expire.

Initiator enters order

The initiator of the order places an order with the following details:

The clearing order will remain awaiting confirmation until the order is confirmed by a counterparty or the expiration time passes. The initiator does not have to have to requisite funds in their account to initiate an order but will need to post the funds before expiration for the trade to settle.

Broker enters order

The broker of the trade places an order with the following details

Order Confirmation

A counterparty can confirm the order on the web interface, sending a POST to https://api.gemini.com/v1/clearing/confirm, or sending a New Order Cross <s> via a FIX order entry session. The counterparty can confirm the order without having the funds needed to fill the order, but will need to post the funds for the trade to settle.

Confirmation via REST and FIX requires the following details to match the initiator's order:

Settlement

After the counterparty confirms the order, the system will attempt to settle the funds. Each party has until the exipiration time to post the required funds to settle the order. If either party does not post the funds to settle the order before the expiration, then the order will expire.

After settlement occurs, the order will show in transaction history.

Cancellation

In a bilateral trade the initiator can cancel the order before it is confirmed. In a broker trade, either counterparty may cancel the trade before it is confirmed by both sides. Cancellation can be done using the web interface, sending a POST to https://api.gemini.com/v1/clearing/cancel, or sending a Cross Order Cancel Request <u>.

Cancellation via REST only requires the clearing_id and FIX requires the following details:

Testing

Gemini Clearing is available in our sandbox environment. Start by creating a sandbox account.

Email trading@gemini.com to coordinate a testing session to go over the Gemini Clearing workflow.

Symbols and minimums

Symbols are formatted as CCY1CCY2 where prices are in CCY2 and quantities are in CCY1, as this table makes explicit:

Symbol Price currency Quantity currency Minimum order size Minimum order increment Minimum price increment
btcusd USD BTC 0.00001 BTC (1e-5) 0.00000001 BTC (1e-8) 0.01 USD
ethusd USD ETH 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.01 USD
ethbtc BTC ETH 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.00001 BTC (1e-5)
zecusd USD ZEC 0.001 ZEC (1e-3) 0.000001 ZEC (1e-6) 0.01 USD
zecbtc BTC ZEC 0.001 ZEC (1e-3) 0.000001 ZEC (1e-6) 0.00001 BTC (1e-5)
zeceth ETH ZEC 0.001 ZEC (1e-3) 0.000001 ZEC (1e-6) 0.0001 ETH (1e-4)
zecbch BCH ZEC 0.001 ZEC (1e-3) 0.000001 ZEC (1e-6) 0.0001 BCH (1e-4)
zecltc LTC ZEC 0.001 ZEC (1e-3) 0.000001 ZEC (1e-6) 0.001 LTC (1e-3)
bchusd USD BCH 0.001 BCH (1e-3) 0.000001 BCH (1e-6) 0.01 USD
bchbtc BTC BCH 0.001 BCH (1e-3) 0.000001 BCH (1e-6) 0.00001 BTC (1e-5)
bcheth ETH BCH 0.001 BCH (1e-3) 0.000001 BCH (1e-6) 0.0001 ETH (1e-4)
ltcusd USD LTC 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.01 USD
ltcbtc BTC LTC 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.00001 BTC (1e-5)
ltceth ETH LTC 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.0001 ETH (1e-4)
ltcbch BCH LTC 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.0001 BCH (1e-4)

FIX

Initiate a Clearing Order

New Order Cross

To submit a new Gemini Clearing order, send a New Order Cross <s> message with OrdType <40> as type Limit.

Gemini will respond to a New Order Cross <s> with an Execution Report <8>. The Execution Report <8> will have OrderID <37> populated with the clearing_id which the counterparty will need to confirm the order.

RAW
8=FIX.4.4|9=204|35=s|34=2|49=TESTOE001|52=20190807-19:28:38.078|56=GEMINI|40=2|44=12000|55=BTCUSD|60=20190807-19:28:38.078|126=20190807-21:28:38.078|548=26990504|549=1|550=0|552=1|54=1|11=87749738|38=2.22222|10=023|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 204
        35                      MsgType: NewOrderCross (s)
        34                    MsgSeqNum: 2
        49                 SenderCompID: TESTOE001
        52                  SendingTime: 20190807-19:28:38.078
        56                 TargetCompID: GEMINI
BODY
        40                      OrdType: LIMIT (2)
        44                        Price: 12000
        55                       Symbol: BTCUSD
        60                 TransactTime: 20190807-19:28:38.078
        126                  ExpireTime: 20190807-21:28:38.078
        548                     CrossID: 26990504
        549                   CrossType: Cross trade which is either completely executed or not executed at all (1)
        550         CrossPrioritization: No priority (0)
        552                     NoSides: One Side (1)
        54                         Side: BUY (1)
        11                      ClOrdID: 87749738
        38                       OrderQty: 2.22222
TRAILER
        10                     CheckSum: 023

New Order Cross Execution Report <8>

RAW
8=FIX.4.4|9=197|35=8|34=2|49=GEMINI|52=20190807-19:28:38.251|56=TESTOE001|6=12000|11=87749738|14=2.22222|17=1565206118250|37=2DZ4MPQM|39=0|44=12000|54=1|55=BTCUSD|60=20190807-19:28:38.250|150=0|151=2.22222|10=009|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 197
        35                      MsgType: ExecutionReport (8)
        34                    MsgSeqNum: 2
        49                 SenderCompID: GEMINI
        52                  SendingTime: 20190807-19:28:38.251
        56                 TargetCompID: TESTOE001
BODY
        6                         AvgPx: 12000
        11                      ClOrdID: 87749738
        14                       CumQty: 2.22222
        17                       ExecID: 1565206118250
        37                      OrderID: 2DZ4MPQM
        39                    OrdStatus: NEW (0)
        44                        Price: 12000
        54                         Side: BUY (1)
        55                       Symbol: BTCUSD
        60                 TransactTime: 20190807-19:28:38.250
        150                    ExecType: NEW (0)
        151                   LeavesQty: 2.22222
TRAILER
        10                     CheckSum: 009

Clearing Order Confirmation

New Order Cross Confirmation

To confirm a Gemini Clearing order, the counterparty must login and confirm the order. The order must be confirmed with the same details provided in the initial order.

Gemini will respond to a New Order Cross <s> with an Execution Report <8>.

RAW
8=FIX.4.4|9=191|35=s|34=2|49=TESTOE002|52=20190806-18:49:03.689|56=GEMINI|40=2|44=12000|55=btcusd|60=20190806-18:49:03.689|117=4KZ306ZG|548=86478800|549=1|550=0|552=1|54=2|11=46081666|38=2.22222|10=103|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 191
        35                      MsgType: NewOrderCross (s)
        34                    MsgSeqNum: 2
        49                 SenderCompID: TESTOE002
        52                  SendingTime: 20190806-18:49:03.689
        56                 TargetCompID: GEMINI
BODY
        40                      OrdType: LIMIT (2)
        44                        Price: 12000
        55                       Symbol: BTCUSD
        60                 TransactTime: 20190806-18:49:03.689
        117                     QuoteID: 2DZ4MPQM
        548                     CrossID: 86478800
        549                   CrossType: 1
        550         CrossPrioritization: 0
        552             Number of sides: 1
        54                         Side: SELL (2)
        11                      ClOrdID: 46081666
        38                       OrderQty: 2.22222
TRAILER
        10                     CheckSum: 103

New Order Cross Confirmation Execution Report <8>

See Execution Report <8> for more details on execution report tags.

RAW
8=FIX.4.4|9=205|35=8|34=2|49=GEMINI|52=20190806-18:49:03.839|56=TESTOE002|6=12000|11=46081666|14=2.22222|17=1565117343839|37=4KZ306ZG|39=0|44=12000|54=2|55=BTCUSD|58=ORDER_CONFIRMED|60=20190806-18:49:03.839|150=0|151=2.22222|10=057|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 205
        35                      MsgType: ExecutionReport (8)
        34                    MsgSeqNum: 2
        49                 SenderCompID: GEMINI
        52                  SendingTime: 20190806-18:49:03.839
        56                 TargetCompID: TESTOE002
BODY
        6                         AvgPx: 12000
        11                      ClOrdID: 46081666
        14                       CumQty: 2.22222
        17                       ExecID: 1565117343839
        37                      OrderID: 4KZ306ZG
        39                    OrdStatus: New (0)
        44                        Price: 12000
        54                         Side: SELL (2)
        55                       Symbol: BTCUSD
        58                         Text: ORDER_CONFIRMED
        60                 TransactTime: 20190806-18:49:03.839
        150                    ExecType: NEW (0)
        151                 LeavesQty: 2.22222
TRAILER
        10 CheckSum: 057

Clearing Order Cancellation

Cross Order Cancel Request

Once an initiator places a New Order Cross, a Cross Order Cancellation Request<35=u> can be placed to cancel the order before it is confirmed by the counterparty. If the order has already been confirmed by the counterparty, it can no longer be cancelled.

RAW
8=FIX.4.4|9=201|34=3|35=u|49=TESTOE001|52=20190806-20:30:28.898|56=GEMINI|37=2DZ4MPQM|55=BTCUSD|60=20190806-20:30:28.898|548=73180000|549=1|550=0|551=26990504|552=1|54=2|41=87749738|11=76494933|38=2.22222|10=128|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 201
        34                    MsgSeqNum: 3
        35                      MsgType: Cross Order Cancel Request
        49                 SenderCompID: TESTOE001
        52                  SendingTime: 20190806-20:30:28.898
        56                 TargetCompID: GEMINI
BODY
        37                      OrderID: 2DZ4MPQM
        55                       Symbol: BTCUSD
        60                 TransactTime: 20190806-20:30:28.898
        548                     CrossID: 73180000
        549                   CrossType: 1
        550         CrossPrioritization: 0
        551                 OrigCrossID: 26990504
        552                     NoSides: 1
        54                         Side: SELL (2)
        41                  OrigClOrdID: 87749738
        11                      ClOrdID: 76494933
        38                       OrderQty: 2.22222
TRAILER
        10                     CheckSum: 066

Cross Order Cancel Request Execution Report

RAW
8=FIX.4.4|9=202|35=8|34=3|49=GEMINI|52=20190806-20:30:28.947|56=TESTOE001|6=0|11=76494933|14=2.22222|17=1565123428947|37=2DZ4MPQM|39=4|54=2|55=BTCUSD|58=ORDER_CANCELED|60=20190806-20:30:28.947|150=4|151=2.22222|10=127|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 202
        35                      MsgType: ExecutionReport (8)
        34                    MsgSeqNum: 3
        49                 SenderCompId: GEMINI
        52                  SendingTime: 20190806-20:30:28.947
        56                 TargetCompID: TESTOE001
BODY
        6                         AvgPx: 0
        11                      ClOrdID: 76494933
        14                       CumQty: 2.22222
        17                       ExecID: 1565123428947
        37                      OrderID: 2DZ4MPQM
        39                    OrdStatus: CANCELED (4)
        54                         Side: SELL (2)
        55                       Symbol: BTCUSD
        58                         Text: ORDER_CANCELLED
        60                 TransactTime: 20190806-20:30:28.947
        150                    ExecType: CANCELED (4)
        151                   LeavesQty: 2.22222
TRAILER
        10                     CheckSum: 127

FIX Broker Support

Gemini Clearing also allows for brokers to facilitate trades between two Gemini customers. A broker can submit a new Gemini Clearing order that must then be confirmed by each counterparty before settlement.

Broker New Order Cross

RAW
8=FIX.4.4|9=247|35=s|34=2|49=TESTOE001|52=20190905-13:29:45.762|56=GEMINI|40=2|44=10000|55=btcusd|60=20190905-13:29:45.762|548=49382061|549=1|550=0|552=2|54=1|11=63216195|583=R485E04Q|38=25.01|54=2|11=44996792|583=7467JVXP|38=25.01|126=20190905-15:29:45.762|10=236|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 247
        35                      MsgType: NewOrderCross (s)
        34                    MsgSeqNum: 2
        49                 SenderCompID: TESTOE001
        52                  SendingTime: 20190905-13:29:45.762
        56                 TargetCompID: GEMINI
BODY
        40                      OrdType: LIMIT (2)
        44                        Price: 10000
        55                       Symbol: BTCUSD
        60                 TransactTime: 20190905-13:29:45.762
        548                     CrossID: 49382061
        549                   CrossType: Cross trade which is either completely executed or not executed at all (1)
        550         CrossPrioritization: No priority (0)
        552                     NoSides: Two Sides (2)
        126                  ExpireTime: 20190905-15:29:45.762
REPEATING GROUPS
        54                         Side: BUY (1)
        11                      ClOrdID: 63216195
        583                 ClOrdLinkID: R485E04Q
        38                     OrderQty: 25.01
        54                         Side: SELL (2)
        11                      ClOrdID: 44996792
        583                 ClOrdLinkID: 7467JVXP
        38                     OrderQty: 25.01
TRAILER
        10                     CheckSum: 236

Broker New Order Cross Execution Report

After submitting a new order cross as a broker, 2 execution reports will be sent (one for each side of the trade).

RAW
8=FIX.4.4|9=211|35=8|34=2|49=GEMINI|52=20190905-13:29:45.928|56=TESTOE001|6=10000|11=63216195|14=25.01|17=1567690185928|37=G9LVQOX5|39=0|44=10000|54=1|55=btcusd|60=20190905-13:29:45.928|150=0|151=25.01|583=R485E04Q|10=239|
8=FIX.4.4|9=211|35=8|34=3|49=GEMINI|52=20190905-13:29:45.929|56=TESTOE001|6=10000|11=44996792|14=25.01|17=1567690185928|37=G9LVQOX5|39=0|44=10000|54=2|55=btcusd|60=20190905-13:29:45.928|150=0|151=25.01|583=7467JVXP|10=054|

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 211
        35                      MsgType: ExecutionReport (8)
        34                    MsgSeqNum: 2
        49                 SenderCompID: GEMINI
        52                  SendingTime: 20190905-13:29:45.928
        56                 TargetCompID: TESTOE001
BODY
        6                         AvgPx: 10000
        11                      ClOrdID: 63216195
        14                       CumQty: 25.01
        17                       ExecID: 1567690185928
        37                      OrderID: G9LVQOX5
        39                    OrdStatus: NEW (0)
        44                        Price: 10000
        54                         Side: BUY (1)
        55                       Symbol: BTCUSD
        60                 TransactTime: 20190905-13:29:45.928
        150                    ExecType: NEW (0)
        151                   LeavesQty: 25.01
        583                 ClOrdLinkID: Clearing ID for corresponding Gemini account (R485E04Q)
Trailer
        10                     CheckSum: 239

HEADER
        8                   BeginString: FIX.4.4
        9                    BodyLength: 211
        35                      MsgType: ExecutionReport (8)
        34                    MsgSeqNum: 3
        49                 SenderCompID: GEMINI
        52                  SendingTime: 20190905-13:29:45.929
        56                 TargetCompID: TESTOE001
BODY
        6                         AvgPx: 10000
        11                      ClOrdID: 44996792
        14                       CumQty: 25.01
        17                       ExecID: 1567690185928
        37                      OrderID: G9LVQOX5
        39                    OrdStatus: NEW (0)
        44                        Price: 10000
        54                         Side: SELL (2)
        55                       Symbol: BTCUSD
        60                 TransactTime: 20190905-13:29:45.928
        150                    ExecType: NEW (0)
        151                   LeavesQty: 25.01
        583                 ClOrdLinkID: Clearing ID for corresponding Gemini account (7467JVXP)
Trailer
        10                     CheckSum: 054

REST API

Gemini Clearing allows two parties to settle a trade off the order book. The initiator enters the trade details for any supported symbol and generates a trade_id. If a counterparty_id is supplied, only the specified counterparty can confirm the order. If a counterparty_id is not supplied, the ticket will generate a trade_id that can filled by any counterparty.

New Clearing Order

Roles

The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information. You can also retrieve the clearing counterparty ID associated with the API key by posting a request to either the roles or account/list endpoints.

HTTP Request

POST https://api.gemini.com/v1/clearing/new

Sandbox

Base url can be changed to https://api.sandbox.gemini.com for test purposes. Please reach out to trading@gemini.com to enable Gemini Clearing on your sandbox account and test workflows.

Parameters

Parameter Type Description
request string The literal string "/v1/clearing/new"
nonce integer The nonce, as described in Private API Invocation
counterparty_id string An optional symbol that corresponds with a counterparty to which you are directing the trade. Can be retrieved from roles or account/list endpoints.
expires_in_hrs integer The number of hours before the trade expires. Your counterparty will need to confirm the order before this time expires.
symbol string The symbol of the order
amount string Quoted decimal amount to purchase
price string Quoted decimal amount to spend per unit
side string "buy" or "sell"

New Clearing Order example

import requests
import json
import base64
import hmac
import hashlib
import datetime, time

base_url = "https://api.gemini.com"
endpoint = "/v1/clearing/new"
url = base_url + endpoint

gemini_api_key = "mykey"
gemini_api_secret = "1234abcd".encode()
counterparty_id = "OM9VNL1G"
t = datetime.datetime.now()
payload_nonce =  str(int(time.mktime(t.timetuple())))

payload = {
    "request": endpoint,
    "nonce": payload_nonce,
    "counterparty_id": counterparty_id,
    "expires_in_hrs": 24,
    "symbol": "btcusd",
    "amount": "100",
    "price": "9500.00",
    "side": "buy"
}

encoded_payload = json.dumps(payload).encode()
b64 = base64.b64encode(encoded_payload)
signature = hmac.new(gemini_api_secret, b64, hashlib.sha384).hexdigest()

request_headers = { 'Content-Type': "text/plain",
                    'Content-Length': "0",
                    'X-GEMINI-APIKEY': gemini_api_key,
                    'X-GEMINI-PAYLOAD': b64,
                    'X-GEMINI-SIGNATURE': signature,
                    'Cache-Control': "no-cache" }

response = requests.post(url,
                        data=None,
                        headers=request_headers)

new_clearing_order = response.json()
print(new_clearing_order)

Sample payload

{
    "request": "v1/clearing/new",
    "nonce": <nonce>,
    "counterparty_id": "OM9VNL1G",
    "expires_in_hrs": 24,
    "symbol": "btcusd",
    "amount": "100",
    "price": "9500.00",
    "side": "buy"
}

JSON response

{
    "result": "AwaitConfirm",
    "clearing_id": "0OQGOZXW"
}

Response

The response will be an object

Field Type Description
result string A description of the status of the clearing order. Because this is the reponse to an order initiation the response will be AwaitConfirm upon order placement success. Failures will show a brief description of the error in this field or the reason and message fields.
clearing_id string A unique identifier for the clearing order. The clearing_id can be used to check the status of your order or by the counterparty to confirm the order.

New Broker Order

Gemini Clearing also allows for brokers to facilitate trades between two Gemini customers. A broker can submit a new Gemini Clearing order that must then be confirmed by each counterparty before settlement.

Sample payload for broker order initiation

{
    "request": "v1/clearing/broker/new",
    "nonce": <nonce>,
    "source_counterparty_id": "R485E04Q",
    "target_counterparty_id": "Z4929ZDY",
    "symbol": "ethusd",
    "amount": "175.00",
    "expires_in_hrs": 1.0,
    "price": "200",
    "side": "sell"
}

Parameters

Parameter Type Description
request string The literal string "v1/clearing/broker/new"
nonce integer The nonce, as described in Private API Invocation
source_counterparty_id string A symbol that corresponds with the counterparty sourcing the clearing trade
target_counterparty_id string A symbol that corresponds with the counterparty where the clearing trade is targeted
symbol string The symbol of the order
amount string Quoted decimal amount to purchase
expires_in_hrs integer The number of hours before the trade expires. Your counterparty will need to confirm the order before this time expires.
price string Quoted decimal amount to spend per unit
side string "buy" or "sell". This side will be assigned to the source_counterparty_id. The opposite side will be sent to the target_counterparty_id.

JSON response to broker clearing order

{
    "result": "AwaitSourceTargetConfirm",
    "clearing_id": "8EM7NVXD"
}

Response

The reponse will be an object

Field Type Description
result string Will return AwaitSourceTargetConfirm, meaning the order is waiting for both the source and the target parties to confirm the order
clearing_id string A unique identifier for the clearing order.

Clearing Order Status

HTTP Request

POST https://api.gemini.com/v1/clearing/status

Sample order cancel payload

{
    "request": "v1/clearing/status",
    "nonce": <nonce>,
    "clearing_id": "OM9VNL1G"
}

Parameters

Parameter Type Description
request string The literal string "v1/clearing/status"
nonce integer The nonce, as described in Private API Invocation
clearing_id string A unique identifier for the clearing order. The clearing_id can be used to check the status of, cancel or confirm the order.

JSON response for confirmed clearing order

{
    "result": "ok",
    "status": "Confirmed"
}

Response

The response will be an object

Field Type Description
result string Will return "ok"
status string A description of the status of the order give in the clearing_id field. See order status descriptions for more information

Order status description

Status Description
AwaitConfirm Indicates that a bilateral trade order has been successfully initiated but has not yet been confirmed by the counterparty
AwaitSourceTargetConfirm Indicates that a broker trade has been successfully initiated but has not yet been confirmed by the target nor source counterparty
AwaitTargetConfirm The source counterparty has confirmed the clearing order but the target counterparty has not yet confirmed
AwaitSourceConfirm The target counterparty has confirmed the clearing order but the source counterparty has not yet confirmed
Confirmed The counterparty has confirmed the clearing order but the trade has not attempted settlement yet.
AttemptSettlement The counterparty has not yet funded their account to the required amount to settle the trade.
Settled The order has been settled and the funds have successfully moved between accounts.
Expired The order expiration time has come before the counterparty confirmed the order or. If the counterparty did confirm the order, then they did not have enough funds to settle the order before the expiration time.
Canceled The order was canceled by the order initiator.
Not Found The clearing_id given in the payload was not successfully matched to a pending clearing order.

Cancel Clearing Order

HTTP Request

POST https://api.gemini.com/v1/clearing/cancel

Sample order cancel payload

{
    "request": "v1/clearing/cancel",
    "nonce": <nonce>,
    "clearing_id": "P0521QDV"
}

Parameters

Parameter Type Description
request string The literal string "v1/clearing/cancel"
nonce integer The nonce, as described in Private API Invocation
clearing_id string A unique identifier for the clearing order. The clearing_id can be used to check the status of, cancel or confirm the order.

JSON response - successful cancel

{
    "result": "ok",
    "details": "P0521QDV order canceled"
}

JSON response - failed cancel

{
    "result": "failed",
    "details": "Unable to cancel order P0521QDV"
}

Response

The response will be an object

Field Type Description
result string A description of the status of the clearing order. This reponse will return the string "ok" upon success, or "failed" upon failure.
details string Provides more detailed description on the result. Will either return "P0521QDV order canceled" or "Unable to cancel order P0521QDV".

Confirm Clearing Order

POST https://api.gemini.com/v1/clearing/confirm

Sample order confirmation payload

{
    "request": "v1/clearing/confirm",
    "nonce": <nonce>,
    "clearing_id": "OM9VNL1G",
    "symbol": "btcusd",
    "amount": "100",
    "price": "9500.00",
    "side": "sell"
}

Parameters

Parameter Type Description
request string The literal string "v1/clearing/confirm"
nonce integer The nonce, as described in Private API Invocation
clearing_id string A unique identifier for the clearing order. The clearing_id can be used to check the status of your order or by the counterparty to confirm the order.
symbol string The symbol of the order
amount string Quoted decimal amount to purchase
price string Quoted decimal amount to spend per unit
side string "buy" or "sell". Must be the opposite side of the initiator's side

JSON response - clearing order confirmation success

{
    "result": "confirmed"
}

JSON response - clearing order confirmation failure

{
    "result": "error",
    "reason": "InvalidSide",
    "message": "Invalid side for symbol BTCUSD: 'buy'"
}

Response

The reponse will be an object

Field Type Description
result sring A brief description of the result. Will return "confirmed" upon success and "error" upon failure
reason string Will only populate upon failure. Gives the reason for the confirmation error
message string Will only populate upon failure. A more detailed description of the reason for failure

Websockets

Gemini Clearing orders will be available on the order events API because clearing orders are not published to the exchange. All Gemini Clearing orders are cleared just between the initiating party and counterparty.

The orders will only show up in order events stream when the order is settled.

The following python code sample will open a private websocket stream.

import ssl
import websocket
import json
import base64
import hmac
import hashlib
import time

def on_message(ws, message):
    print(message)

def on_error(ws, error):
    print(error)

def on_close(ws):
    print("### closed ###")

gemini_api_key = "apikey"
gemini_api_secret = "apisecret".encode()

payload = {"request": "/v1/order/events","nonce": int(time.time())}
encoded_payload = json.dumps(payload).encode()
b64 = base64.b64encode(encoded_payload)
signature = hmac.new(gemini_api_secret, b64, hashlib.sha384).hexdigest()


ws = websocket.WebSocketApp("wss://api.gemini.com/v1/order/events",
                            on_message=on_message,
                            header={
                                'X-GEMINI-PAYLOAD': b64.decode(),
                                'X-GEMINI-APIKEY': gemini_api_key,
                                'X-GEMINI-SIGNATURE': signature
                            })
ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})

Sample JSON response for settled Clearing Order

This clearing order was settled on the Web UI. Please see common fields for more information on the expected fields.

[
  {
    "type": "fill",
    "order_id": "263424597",
    "api_session": "UI",
    "symbol": "ltcusd",
    "side": "buy",
    "order_type": "exchange limit",
    "timestamp": "1565273156",
    "timestampms": 1565273156891,
    "is_live": false,
    "is_cancelled": false,
    "is_hidden": true,
    "avg_execution_price": "90.00",
    "executed_amount": "15000",
    "remaining_amount": "0",
    "original_amount": "15000",
    "price": "90.00",
    "fill": {
      "trade_id": "263424597",
      "liquidity": "GTS",
      "price": "90.00",
      "amount": "15000",
      "fee": "0.00",
      "fee_currency": "USD"
    },
    "socket_sequence": 87
  }
]
Field Type Description
type string
order event type
fill
order_type string will always be exchange limit for clearing orders
fill.trade_id string the event id the order was filled at
fill.liquidity string will return GTS for clearing orders
fill.price decimal the price the trade filled at
fill.amount decimal the amount of the trade fill
fill.fee decimal the fee associated with this side of the trade
fill.fee_currency string the three-letter code of the currency associated with the fee

Revision History

Date Notes
2019/08/08 Initial Gemini Clearing API Documentation

© Copyright 2019 Gemini Trust Company, LLC.