Gemini API – A Step-by-Step Guide

What is Gemini API?

Gemini API is a method that allows us to automatically trade cryptocurrencies on Gemini via code.

What is Gemini?

Gemini is a US-based cryptocurrency exchange platform that allows its users to safely buy, sell, and create portfolios around crypto.

Gemini was created in 2014 in New York by the Winklevoss twins. This makes Gemini one of the few crypto exchanges that are regulated in the US.

Gemini brings a user-friendly platform that is great for beginners and advanced traders alike. For example, beginner traders will enjoy Gemini’s web and mobile apps while the advanced users may dive into advanced features that the Active Trader brings.

What is the Gemini Dollar?

The Gemini Dollar (GUSD) is a regulated stablecoin that is designed for spending, lending and trading. It is also supported by the US dollars held at State Street Bank and Trust Company.

This means that it can be transferred back to US dollars at any time with a 1:1 rate.

Is Gemini free?

Gemini offers various fee schedules that are dependent on the platform you use. Most traders tend to use their web and mobile platforms, so the fees for those look like the following:

Less than $10 / fee $0.99

More than $10 but less than $25 / fee $1.49

More than $25 but less than $50 / fee $1.99

$50.01 to $200 / fee $2.99

More than $200 / fee 1.49% of your total order value

You will also be charged a convenience fee of 0.50% of the current market price of the coin that you are buying, on top of the transaction fee.

The API usage fees are more complicated so I would advise the reader to visit the following link for a better look where all the calculations are shown with examples:

Why should I use Gemini?

• Easy to use and beginner-friendly
• Has high-security protocols and hot wallets
• Provides many platforms that can accommodate the trader’s skill
• Provides educational resources
• Has a mobile app
• Has a sandbox for API testing
• You can pay directly with your crypto

Why shouldn’t I use Gemini?

• Not available in all countries
• Limited account funding methods
• High fees
• Only offers cryptocurrency trading

Is Gemini available in my country?

As the Gemini API is not available in all countries I created a map of all Gemini supported countries so you don’t need to go over a boring list.

What are the alternatives to using Gemini API?

Gemini API can be replaced with some alternatives and they are the following:

What clients are available for the Gemini API?

Gemini API is available in the following clients:

• Python
• JavaScript
• Java
• Ruby
• TypeScript
• C#
• Go
• PHP

How to get started with Gemini API?

In order to get started with the Gemini API, you will first need to go over to their website that is found on the following link:

What are Gemini’s Public APIs?

The Gemini API offers us the following public APIs to use:

• Symbols
• Tickers
• Candles
• Current Order Books
• Trade History
• Current auction
• Auction history
• Price feed

Let us explore how to call each of them and see what the responses look like and how we can manipulate them for a better understanding and look.

Have in mind that the rate limit for the public API entry points is set to 120 requests per minute, while the private API entry points are set to 600 requests per minute.

As their python library is experiencing some issues with connecting to the WebSocket, we will do the calls manually.

Let us import the relevant libraries and obtain a list of all the symbols that the Gemini API offers:

import json, requests
import pandas as pd

Now we will create a base for our URL that will remain the same for some of our public API endpoints. After that, we will build our response by adding the symbols specification to the end of the main URL.

We will also specify the response format to be JSON and then pass it into a pandas data frame and look at the last five of them.

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/symbols")
symbols = pd.DataFrame(response.json())
symbols.tail()

Now, let us check the value for a specific symbol, in this case it will be the BTC-USD one. All we need is to change our response to accommodate the wished symbol.

response = requests.get(base_url + "/symbols/details/BTCUSD")
symbols = response.json()
symbols

{'symbol': 'BTCUSD',
 'base_currency': 'BTC',
 'quote_currency': 'USD',
 'tick_size': 2,
 'quote_increment': 8,
 'min_order_size': '0.00001',
 'status': 'open'} 

The next thing we want to check for is the information about the recent trading activity of our symbol. For this, we will use the ticker endpoint.

response = requests.get(base_url + "/pubticker/btcusd")
btc_data = response.json()
btc_data

{'bid': '35910.14',
 'ask': '35918.91',
 'volume': {'BTC': '4540.3648977187',
   'USD': '159213478.551186081629',
   'timestamp': 1609970400000},
 'last': '35918.91'}

In order to get the V2 ticker we can do the following:

base_url = "https://api.gemini.com/v2"
response = requests.get(base_url + "/ticker/btcusd")
btc_data = response.json()
btc_data

What if we want to obtain the 15min time-interval data for our symbol aka candles?

In order to do this, we will need to change several things. Firstly, we will change our parameters. After that, we will arrange the data into a pandas data frame and provide a name for each column of the response.

response = requests.get(base_url + "/candles/btcusd/15m")
btc_candle_data = pd.DataFrame(response.json(), columns =['time','open','high','low','close','volume'])

The next thing is to convert the unix timestamp to a normal date and pass it as an index value. As the historical data will be arranged in a descending order starting from our current timestamp, we will need to rearrange it.

btc_candle_data['time'] = pd.to_datetime(btc_candle_data['time'], unit='ms')
btc_candle_data.set_index('time', inplace=True)
btc_candle_data.sort_values(by =['time'], inplace = True)
btc_candle_data

Now, let us calculate the 20 day simple moving average (20SMA). This step can be done easily with pandas but for more advanced indicators such as the RSI, I’d advise using the btalib library.

With pandas the code for the 20SMA looks like this

btc_candle_data['20 SMA'] = btc_candle_data.close.rolling(20).mean()

With btalib:

btc_candle_data[’20 SMA’] = btalib.sma(btc_candle_data.close, period=20).df
btc_candle_data.tail()

If you want to save the dataset into a csv format do the following:

btc_candle_data.to_csv('BitcoinData.csv')

Now, let’s go for a juicy candlestick plot to get a better understanding of the data. For this, we will use Plotly that provides us with interactive charts for finance.

All we need to do is to specify the type of graph and its components that build the main graph figure.

fig = go.Figure(data=[go.Candlestick(x = btc_candle_data.index,
                                    open = btc_candle_data['open'],
                                    high = btc_candle_data['high'],
                                    low = btc_candle_data['low'],
                                    close = btc_candle_data['close'],
                                    ),
                     go.Scatter(x= btc_candle_data.index, y=btc_candle_data['20 SMA'], line=dict(color='purple', width=1))])


fig.show() 

If you want to obtain the current order book as two arrays (bids/asks) write the following code:

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/book/btcusd")
btc_book = response.json()
btc_book

It is somewhat messy, isn’t it? Let us clean it up a bit. We will create a data frame for each of the two and then merge them together for a better look.

df_bid = pd.DataFrame(btc_book['bids'])
df_ask = pd.DataFrame(btc_book['asks'])
df_bid['timestamp'] = pd.to_datetime(df_ask['timestamp'], unit='s')
df_bid.set_index('timestamp', inplace=True)

df_ask['timestamp'] = pd.to_datetime(df_ask['timestamp'], unit='s')
df_ask.set_index('timestamp', inplace=True)

df_bid.head()
df_ask.head()

Merge them like this:

df = pd.merge(df_bid, df_ask, on = "timestamp", how = "inner") 
df = df.rename({"price_x":"Bid Price","amount_x":"Bid Amount",
                "price_y":"Ask Price","amount_y":"Ask Amount"}, axis='columns')
df

If you want to obtain the trade history aka the trades that were executed after the specified timestamp you need to have the following in mind.

Firstly, the call without a specified timestamp will return the most recent trades. The timestamps are dates that go back to 1970-01-01 and each request can show up to 500 records.

The request will return a response with:

timestamp – the time that the trade was executed

timestamps – the time that the trade was executed in ms

tid – trade id number

price – the price the trade was executed at

amount –    The amount that was traded

exchange – always Gemini

type – the type of trade (buy, sell, auction, block)

broken – broken trades aren’t included in a default call

Let us make a request and tidy it up a bit:

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/trades/btcusd")
btcusd_trades = pd.DataFrame(response.json(), columns = ['timestamp','price','amount','type'])
btcusd_trades['timestamp'] = pd.to_datetime(btcusd_trades['timestamp'], unit='s')
btcusd_trades.set_index('timestamp', inplace = True)
btcusd_trades.head()

To get the current auction for a symbol we can write this:

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/auction/btcusd")
btc_auction = response.json()
btc_auction

{'next_update_ms': 1610052600000,
 'next_auction_ms': 1610053200000,
 'last_auction_eid': 189461049871}

And for the auction history (have in mind that the public API only returns 7 calendar days of data) do this:

response = requests.get(base_url + "/auction/btcusd/history")
btc_auction_history = pd.DataFrame(response.json())
btc_auction_history.T

Gemini’s public API also offers a price feed where we obtain all the prices and 24h percent changes for each coin pair.

response = requests.get(base_url + "/pricefeed")
prices = pd.DataFrame(response.json())
prices.set_index('pair', inplace = True)
print('There are',len(prices),'currency pairs\n')
print(prices.tail())

How to place orders with Gemini API?

For this part of the article, we will rely on our Gemini API sandbox and show two examples of trading scenarios so you can learn how to place orders with the Gemini API and specify the circumstances of the order execution.

In the first example, I will show you how to properly and securely launch an order with specified requirements. The thing that we want to do is to launch a trade on ETH when BTC hits a certain price.

Let us go ahead and import the relevant libraries and set up the API Key and Secret for this task:

import requests
import hmac
import json
import base64
import hashlib
import datetime, time
gemini_api_key = "YOUR-KEY-HERE"
gemini_api_secret = "YOUR-KEY-HERE".encode()

The Gemini API has a “nonce” feature which is a number that must not be repeated and must be increased between order requests. This feature prevents potential hackers who have captured our previous request to simply replay that request. So let us set up a nonce.

t = datetime.datetime.now()
payload_nonce =  str(int(time.mktime(t.timetuple())*1000))

We will buy 5 ETH for their current market price if the price of BTC reaches $37900.00. Now, we shall specify the order payload that will carry the main order requirements. As Gemini doesn’t support direct market orders, we will need to go around it in our task loop later on.

This means that the next 3 steps can be skipped for now. I’ve pulled them out of our main loop out of didactic reasons so you can better understand what is happening.

payload = {
   "request": "/v1/order/new",
    "nonce": payload_nonce,
    "symbol": "ethusd",
    "amount": "5",
    "price": eth_price,
    "side": "buy",
    "type": "exchange limit",
}

Moreover, the way that we will go around the direct market order is to launch an exchange limit order with the current limit of the specified symbol.

Gemini advises its users to go around this by using the “immediate-or-cancel” execution option, coupled with a really aggressive limit price (very high for buy orders and very low for sell orders).

In the next step we will encode our payload and set up the signature.

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

The next step is to set up the headers for our order:

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" }

Now, let us add it all together and look for the specified BTC price in dollars. If the price is reached, the order will launch. If the price is not reached the loop will continue.

import requests
import hmac
import json
import base64
import hashlib
import pandas as pd
import datetime, time
from time import sleep

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

gemini_api_key = "master-2rJeGEcrQbx6OKXvSvLR"
gemini_api_secret = "CZTk6cmFZgVPSnoHij22LZNFZ3S".encode()

def Auth(payload):
    
    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" }
    return(request_headers)

while True:
    try:
        response = requests.get("https://api.gemini.com/v1/pubticker/BTCUSD").json()
        btc_price = float(response['ask'])
        print(btc_price)
    except exception as e:
        print(f'Error obtaining data: {e}')
        
    if btc_price >= 50000:
        try:
            response = requests.get("https://api.gemini.com/v1/pubticker/ETHUSD").json()
            eth_price = float(response['ask'])
            print(eth_price)
        except Exception as e:
            print(f'Error obtaining data: {e}')
            
        t = datetime.datetime.now()
        payload_nonce =  str(int(time.mktime(t.timetuple())*1000))  
        
        payload = {
            "request": "/v1/order/new",
            "nonce": payload_nonce,
            "symbol": "ethusd",
            "amount": "1",
            "price": eth_price,
            "side": "buy",
            "type": "exchange limit",
            "account": "algotrading"
            }
        
        
        try:
            new_order = requests.post(url,
                            data=None,
                            headers=Auth(payload)).json()
            print(new_order)
            
        except Exception as e:
            print(f'Error placing order: {e}')
            
        print(new_order)

        check_status = new_order['order_id']

        sleep(2)

        t = datetime.datetime.now()
        payload_nonce =  str(int(time.mktime(t.timetuple())*1000))

        payload1 = {
            "request" : '/v1/order/status',
            "nonce" : payload_nonce,
            "order_id" : check_status,
            "account" : "algotrading", 
        }
        
        try:  
            check = requests.post(base_url + '/v1/order/status',
                            data=None,
                            headers=Auth(payload1)).json()
            
        except Exception as e:
            print(f'Error checking order: {e}')

        if str(check['is_live']) == 'True':
            print ('Order placed at {}'.format(pd.Timestamp.now()))
            break

        else:
            print('Order was canceled {}'.format(pd.Timestamp.now()))
            break

    else:
        print('BTC did not reach the specified price')
        sleep(10)
        continue

The next example will use a similar order logic, but it will look for the percentage change between two symbols. The main task will be to execute an ETH trade when BTC moves 5% in the last 5 minutes.

This means that we will want to create a loop that will obtain the prices of the two cryptos and calculate the percentage change between the two.

If the percentage change is less than 5%, the program will be sleeping for 5 minutes and calculating the percentage change again. If the percentage change is equal to or more than 5% the trade will execute.

The code will be coupled with error handlings for each major step. The code up to the main loop remains the same as in our previous example.

Here is the main loop:

while True:
    try:
        response = requests.get("https://api.gemini.com/v1/pubticker/BTCUSD").json()
        btc_old = float(response['ask'])
        print(btc_old)
    except exception as e:
        print(f'Error obtaining data: {e}')
    
    sleep(300)
    
    try:
        response = requests.get("https://api.gemini.com/v1/pubticker/BTCUSD").json()
        btc_new = float(response['ask'])
        print(btc_new)
    except exception as e:
        print(f'Error obtaining data: {e}')
    
    percent = ((btc_new - btc_old)*100) / btc_old
        
    if percent >= 5:
        try:
            response = requests.get("https://api.gemini.com/v1/pubticker/ETHUSD").json()
            eth_price = float(response['ask'])
            print(eth_price)
        except Exception as e:
            print(f'Error obtaining data: {e}')
            
        t = datetime.datetime.now()
        payload_nonce =  str(int(time.mktime(t.timetuple())*1000))  
        
        payload = {
            "request": "/v1/order/new",
            "nonce": payload_nonce,
            "symbol": "ethusd",
            "amount": "1",
            "price": eth_price,
            "side": "buy",
            "type": "exchange limit",
            "account": "algotrading"
            }
        
        
        try:
            new_order = requests.post(url,
                            data=None,
                            headers=Auth(payload)).json()
            print(new_order)
            
        except Exception as e:
            print(f'Error placing order: {e}')
            
        print(new_order)

        check_status = new_order['order_id']

        sleep(2)

        t = datetime.datetime.now()
        payload_nonce =  str(int(time.mktime(t.timetuple())*1000))

        payload1 = {
            "request" : '/v1/order/status',
            "nonce" : payload_nonce,
            "order_id" : check_status,
            "account" : "algotrading", 
        }
        
        try:  
            check = requests.post(base_url + '/v1/order/status',
                            data=None,
                            headers=Auth(payload1)).json()
            
        except Exception as e:
            print(f'Error checking order: {e}')

        if str(check['is_live']) == 'True':
            print ('Order placed at {}'.format(pd.Timestamp.now()))
            break

        else:
            print('Order was canceled {}'.format(pd.Timestamp.now()))
            break

    else:
        print(f'BTC did not reach the requirement. Percentage move is at {percent}')
        continue

How to cancel orders with Gemini API?

Orders can be canceled with Gemini by passing the order nonce and id into your response.

{
    "nonce": <nonce>,
    "order_id": <order-id-here>,
    "request": "/v1/order/cancel"
}

To cancel all session orders write the following:

{
    "request": "/v1/order/cancel/session",
    "nonce": <nonce>
}

To cancel all active orders write this:

{
    "nonce": <nonce>,
    "request": "/v1/order/cancel/all"
}

What order execution options does Gemini have?

Gemini features several order execution options that can be added to your main order payload as “type” : “option name”. Let us see what they do:

“maker-or-cancel” – This order only adds liquidity to the order book. If any part of the order wasn’t filled immediately, the whole order will be canceled before the execution.

“immediate-or-cancel” – This order only removes liquidity from the order book. This means that it will fill whatever part of the order it can immediately and cancel the remaining amount so that it doesn’t get added to another order book.

“fill-or-kill” – This order, like the previous one, removes liquidity from the order book. It will fill the entire order immediately or cancel.

“auction-only” – This order will be added to the auction-only book for the next auction for a specified symbol.

“indication-of-interest” – is a request for liquidity from block trading market-makers for a specified symbol.

How to get Notional and Trade Volumes with Gemini API?

In order to get these volumes we will need to do several things when calling the API that were shown in the previous trading examples. So let us code the notional volumes request:

import requests
import hmac
import json
import base64
import hashlib
import pandas as pd
import datetime, time
from time import sleep

gemini_api_key = "master-2rJeGEcrQbx6OKXvSvLR"
gemini_api_secret = "CZTk6cmFZgVPSnoHij22LZNFZ3S".encode()

t = datetime.datetime.now()
payload_nonce =  str(int(time.mktime(t.timetuple())*1000))

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

payload = {
            "request": "/v1/notionalvolume",
            "nonce": payload_nonce,
            }

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)
print(response)

In order to get the trade volumes change the payload and required endpoints like this:

{
    "nonce": <nonce>,
    "request": "/v1/tradevolume"
}

How to use Gemini Clearing orders?

The Gemini clearing endpoint allows two parties to conduct a trade-off in the order book. The initiator enters the trade details for a specified symbol and creates a trade_id.

If a counterparty_id is supplied, only the counterparty can confirm the order. It the id is not supplied, the ticket will generate a trade_id that can be filled by any counterparty.

Here is how a clearing order would look like:

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

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

gemini_api_key = "YOUR-API-KEY-HERE"
gemini_api_secret = "YOUR-SECRET-KEY-HERE".encode()
counterparty_id = "COUNTERPARTY-ID-HERE"
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": "ethusd",
    "amount": "20",
    "price": "9000.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)

How to use Fund Management APIs from Gemini?

There are several fund management endpoints and we will mention a few of them. For a full list check the Gemini API documentation that is found on the following link:

What is the Heartbeat function from Gemini API?

Heartbeat is a part of Gemini’s Session APIs that prevents a session from timing out and canceling orders if the required heartbeat flag has bet properly set.

This may only be required if there aren’t any other private API requests that have been made. Any message that arrives will reset the heartbeat timer.

To set up the heartbeat, change the payload to:

{
    "nonce": <nonce>,
    "request": "/v1/heartbeat"
}

More about Gemini

Moreover, the creators of Gemini were also the ones that created ConnectU, a predecessor to Facebook.

When it comes to cryptocurrency Gemini offers its users access to over 20 cryptos like Bitcoin, Ethereum, Litecoin, XRP, Stellar, Tezos, Cardano, Polkadot, and more.

Examples of some features that the Active Trader brings are the following: advanced charting, auctions, block trading, and multiple order types.

This is also integrated with their mobile app that comes with custom push notifications and a possibility of trading with it. Moreover, you can pay retailers directly with your crypto.

All you need to do is to push the “Pay” button that is located near the bottom of the app interface. Select the crypto you want to pay in and the retailer. After that, a custom QR code will appear that can be scanned for payment.

For algorithmic traders, Gemini features a good API that is easy to use and integrate and we will explore its features later down the article.

When it comes to funding your account on Gemini, you’ll need to do it through your bank account. This means that it can’t be funded by the use of a credit or debit card.

You also have the option to fund your Gemini wallet with another crypto wallet but the currencies must be along the lines of BTC, LTC, BCH, ETH or ZEC.

Your maximum funding price ranges from $500 to $15k on a monthly basis, while the withdrawal amount is set to $100k.

Your money is stored in the Gemini Wallet that is a hot wallet aka an “institutional-grade cold storage system”. This means that it should be safe from hacking.

If a hack happens the funds are FDIC insured which means that they should remain safe. Compared to other similar platforms, Gemini might be the safest one for storing money.

Gemini has a Gemini Clearing function that allows two parties to settle a trade off the order book. Here Gemini is a regulating third-party in the pre-arranged transactions.

Gemini offers its users educational resources so they can learn more about the world of cryptocurrency and trading before sailing the boat.

They have their Cryptopedia that feature more than 160 articles covering 4 main categories which are cryptocurrencies, security, trading and investing, and DeFi.

Gemini also features 3 distinct webinars that allow beginners to make a solid grasp of trading and finance:

• Intro to Crypto Webinar – here you are taught about the basics of the cryptocurrency ecosystem.
• Intro to Ethereum Webinar – this one is self-explanatory.
• Crypto 201 Webinar – here you will learn about the main differences between the ETH and BTC blockchains, ERC-20 tokens, and more.

Full code: