Gemini Cryptocurrency Exchange Api

Gemini cryptocurrency exchange api

Introduction

Gemini offers both public and private REST APIs.

Public REST APIs provide market data such as:

  • current order book
  • recent trading activity
  • trade history

Private REST APIs allow you to manage both orders and funds:

  • place and cancel orders
  • see your active orders
  • see your trading history and trade volume
  • get your available balances

Survey

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

Sandbox

Gemini's sandbox site is an instance of the Gemini Exchange that offers full exchange functionality using test funds.

Sandbox URLs

  • Gemini has an automated system that makes trades on the exchange to simulate normal exchange activity
  • all funds are for testing purposes only, no deposits or withdrawals
  • hourly auctions

Sandbox URLs

Website
https://exchange.sandbox.gemini.com

REST API
https://api.sandbox.gemini.com

WebSocket Feed
wss://api.sandbox.gemini.com

Documentation
https://docs.sandbox.gemini.com

Create your account

Go to the sandbox site to register for a test account to begin trading.

  • use the website to get comfortable trading on Gemini
  • use the API to validate your trading systems before deploying them against the real Gemini exchange

Your account will automatically be credited with USD, BTC, ETH, ZEC, BCH, and LTC. You may use these funds to trade, both through the web site and through the API.

Gemini's sandbox site does not support either depositing or withdrawing your test funds, which can only be used to trade on the sandbox exchange.

Sandbox does not support email notifications.

If you need this as part of your testing plan, please contact [email protected]

If you have any issues, or if you need to adjust your balances (to test insufficient funds handling, for example), contact [email protected]

Rate Limits

To prevent abuse, Gemini imposes rate limits on incoming requests as described in the Gemini API Agreement.

For public API entry points, we limit requests to 120 requests per minute, and recommend that you do not exceed 1 request per second.

For private API entry points, we limit requests to 600 requests per minute, and recommend that you not exceed 5 requests per second.

How are rate limits applied?

When requests are received at a rate exceeding X requests per minute, we offer a "burst" rate of five additional requests that are queued but their processing is delayed until the request rate falls below the defined rate.

When you exceed the rate limit for a group of endpoints, you will receive a Too Many Requests HTTP status response until your request rate drops back under the required limit.

Example: 600 requests per minute is ten requests per second, meaning one request every 0.1 second.

If you send 20 requests in close succession over two seconds, then you could expect:

  • the first ten requests are processed
  • the next five requests are queued
  • the next five requests receive a 429 response, meaning the rate limit for this group of endpoints has been exceeded
  • any further incoming request immediately receive a 429 response
  • after a short period of inactivity, the five queued requests are processed
  • following that, incoming requests begin to be processed at the normal rate again

Use WebSocket APIs

Polling Order Status API endpoints may be subject to rate limiting: Gemini recommends using WebSocket API to get market data and realtime information about your orders and trades.

Batch cancels

If you want to cancel a group of orders, instead of making multiple Cancel Order requests, use one of Gemini's batch cancel endpoints:

Then use your Order Events WebSocket subscription to watch for notifications of:

Requests

There are two types of APIs below, the public ones and the private ones, which are subdivided into order placement, order status, and account status.

Public API invocation

Public APIs are accessible via GET, and the parameters for the request are included in the query string.

Private API invocation

Payload creation

Whitespace is valid JSON, so it is ignored by the server, and may be included if desired.

The hashes are always taken on the base64 string directly, with no normalization, so whatever is sent in the payload is what should be hashed, and what the server will verify.

In this example, the is

The final request will look like this:

Which produces these HTTP headers

Authentication

Gemini uses API keys to allow access to private APIs.

You can obtain these by logging on and creating a key in Settings/API. This will give you both an "API Key" that will serve as your user name, and an "API Secret" that you will use to sign messages.

All requests must contain a nonce, a number that will never be repeated and must increase between requests.

This is to prevent an attacker who has captured a previous request from simply replaying that request. We recommend using a timestamp at millisecond or higher precision. The nonce need only be increasing with respect to the session that the message is on.

Sessions

A single account may have multiple API keys provisioned.

Utility meets stability

In this document, we'll refer to these as "sessions". All orders will be recorded with the session that created them. The nonce associated with a request needs to be increasing with respect to the session that the nonce is used on.

This allows multithreaded or distributed trading systems to place orders independently of each other, without needing to synchronize clocks to avoid race conditions.

In addition, some operations (such as ) act on the orders associated with a specific session.

Require Heartbeat

When provisioning a session key you have the option of marking the session as "Requires Heartbeat".

The intention here is to specify that if connectivity to the exchange is lost for any reason, then all outstanding orders on this session should be canceled.

If this option is selected for a session, then if the exchange does not receive a message for 30 seconds, then it will assume there has been an interruption in service, and cancel all outstanding orders.

Options trading with $100

To maintain the session, the trading system should send a heartbeat message at a more frequent interval. We suggest at most 15 seconds between heartbeats.

The heartbeat message is provided for convenience when there is no trading activity. Any authenticated API call will reset the 30 second clock, even if explicit heartbeats are not sent.

This feature is often referred to as "Cancel on Disconnect" on connection-oriented exchange protocols.

Payload

The payload of the requests will be a JSON object, which will be described in the documentation below.

Rather than being sent as the body of the POST request, it will be base-64 encoded and stored as a header in the request.

Authenticated APIs do not submit their payload as POSTed data, but instead put it in the X-GEMINI-PAYLOAD header

All of them will include the request name and the nonce associated with the request. The nonce must be increasing with each request to prevent replay attacks.

HeaderValue
Content-Length
Content-Type
X-GEMINI-APIKEYYour Gemini API key
X-GEMINI-PAYLOADThe base64-encoded JSON payload
X-GEMINI-SIGNATURE
Cache-Controlno-cache

Master API

A group that contains multiple accounts can provision a Master API key.

Master API keys offer the convenience of invoking any account API on behalf of an account within that group.

Gemini cryptocurrency exchange api

To invoke an API on behalf of an account add that accounts nickname as an parameter to your request payload.

Master API keys are formatted with a prepending , while account level API keys are formatted with a prepending .

The parameter may be used on any API that performs an action for or against a single account.

Example of adding the account parameter to an API call, in this case New Order

Roles

Example of error response due to API key missing a role

Gemini uses a role-based system for private API endpoints so that you can separate privileges for your API keys.

By assigning different roles to different API keys, you can create

  1. one API key that can trade, and
  2. another API key that can withdraw digital assets to a whitelisted address, or
  3. an API key to have access to read-only endpoints

You can configure which roles are assigned to your API keys by logging in to the Gemini Exchange website and going to API Settings to configure your API keys.

When you create an API key, the Trader role is assigned by default.

If you try to access an endpoint that requires a role you did not assign to your API key, you will get back a response with:

  • status
  • a JSON response body with
    • set to , and
    • explaining what role you need to add to your API key to use this endpoint

See Error Codes for more information about API error responses.

Administrator

The Administrator role is exclusive to Master API keys.

Assigning the Administrator role to an API key allows this API key to:

  • Create accounts within the Master Group
  • View accounts within the Master Group
  • Execute internal book transfers between two exchange accounts within the same master group

Trader

Assigning the Trader role to an API key allows this API key to:

  • check balances
  • place and cancel orders
  • check the status of orders
  • see all active orders
  • see your trade history and volume

Fund Manager

Assigning the Fund Manager role to an API key allows this API key to:

  • check balances
  • request new cryptocurrency deposit addresses
  • withdraw cryptocurrency funds to whitelisted

Auditor

The Auditor role is read-only and cannot be combined with other roles.

Assigning the Auditor role to an API key allows this API key to:

  • Check balances
  • Check the status of orders
  • See transfers such as deposits and withdrawals
  • See all active orders
  • See trade volume
  • See past trades

Endpoint summary

Here's a summary of which role you need to assign to your API key to use each endpoint in the API:

Account Scoped API

Master Scoped API

EndpointURIAdministrator can access?Trader can access?Fund Manager can access?Auditor can access?
Create Account
Get Accounts
Internal Transfer
Master level API keys can access Account level endpoints if the proper role is assigned.

Introduction

The `account` will need to be passed in the payload of the request as detailed Account Administration APIs.

Roles API

HTTP Request

The endpoint will return a string of the role of the current API key. This API is only available for account level API keys.

Sample payload

Upon a successful call, an example response will be as follows

Parameters

ParameterTypeDescription
requeststringthe literal string "/v1/roles"
nonceintegerThe nonce, as described in Private API Invocation

Response

The response will be a JSON object indicating the assigned roles to the set of API keys used to call .

The role cannot be combined with other roles. and can be combined.

FieldTypeDescription
counterparty_idstringThe Gemini clearing counterparty ID associated with the API key making the request.
isAuditorboolean if the Auditor role is assigned to the API keys.

Gemini Trust Company™

otherwise.

isFundManagerboolean if the Fund Manager role is assigned to the API keys. otherwise.
isTraderboolean if the Trader role is assigned to the API keys. otherwise.

Troubleshooting

Please use our Sandbox environment to develop and test your code.

If your private API request is failing, turn on debug logging so you can print out:

  • the full headers of the HTTP request that you are sending
  • the HTTP status code of the response
  • the full content of the HTTP response

Make sure that you are not sending the JSON as the body.

If you receive a error that you are missing required data, then copy the base64 encoded string in to a base64 decoder such as https://www.base64decode.org/ and decode it.

Weekly options strategies to make 10000 a month

Compare the decoded JSON to the documentation for the endpoint you are trying to access.

If you are receiving a response, then see Rate Limits.

Support

If you are an institutional trader, please contact your Gemini account manager for institutional support.

If you still have a problem then contact [email protected] with the following information:

  1. Which environment did you try to make the request in, production or sandbox?
  2. What is your API key?
  3. What URL were you trying to hit?
  4. What IP address did you make the request from?
  5. What date and time (including time zone) did you try to make the request?

Please make sure to include:

  • your HTTP request headers
  • the full JSON response from the server

If you leave any of this information out, the response to your support request may be delayed.

Client Order ID

Order Event subscription Accepted event showing client_order_id

Order Status endpoint for the same order, showing client_order_id

Client order ID is a client-supplied order identifier that Gemini will echo back to you in all subsequent messages about that order.

Although this identifier is optional, Gemini strongly recommends supplying when placing orders using the New Order endpoint.

Institutional Solutions

This makes it easy to track the Order Events: Accepted and Order Events: Booked responses in your Order Events WebSocket subscription.

Visibility

Your client order ids are only visible to the Gemini exchange and you. They are never visible on any public API endpoints.

Uniqueness

Gemini recommends that your client order IDs should be unique per trading session.

Allowed characters

Your client order ids should match against this PCRE regular expression: .

CharactersDescriptionASCII Codes (Dec)
Uppercase A-Z65 - 90
Lowercase a-z97 - 122
Digits48 - 57
Hash, octothorpe, number sign35
Hyphen45
Period46
Colon58
Underscore95

Data Types

The protocol description below will contain references to various types, which are collected here for reference

TypeDescription
stringA simple quoted string, following standard JSON rules; see the JSON spec for details.
decimalA decimal value, encoded in a JSON string.

The contents will be a series of digits, followed by an optional decimal point and additional digits.

timestampThe number of seconds since 1970-01-01 UTC.

Gemini cryptocurrency exchange api

This is usually provided for compatibility; implementors should use the more precise timestampms when available. When used as an input, either the millisecond or second precision is usable; this is unambiguous for dates past 1/29/1970

timestampmsThe number of milliseconds since 1970-01-01 UTC.

The begin date is the standard UNIX epoch, so this will be 1000 times the UNIX timestamp in seconds. This will be transmitted as a JSON number, not a string.

integerAn whole number, transmitted as a JSON number.
booleanA JSON boolean, the literal string or
arraya JSON array.

Each element contains a payload that will be described.

Timestamps

The timestamp data type describes a date and time as a whole number in Unix Time format, as the number of seconds or milliseconds since 1970-01-01 UTC.

Requests

Gemini strongly recommends using milliseconds instead of seconds for timestamps.

Gemini API Tutorial

When timestamp is supplied as a request parameter, the following two values are supported in order of preference:

  1. The number of milliseconds since 1970-01-01 UTC
  2. The number of seconds since 1970-01-01 UTC (unix epoch)

For your convenience, a request may supply the parameter in a JSON payload as a string instead of a number.

Timestamp formatexampleSupported request type
whole number (seconds),
string (seconds) only
whole number (milliseconds),
string (milliseconds) only

Behavior

If the parameter is not present, the default behavior is to return the most recent items in the list.

For example, the public Trade History endpoint will return the most recent trades without a parameter.

The first trade on Gemini occurred at milliseconds. Any request for a timestamp value before this is the same as requesting the very first item in the list.

You may choose to supply a timestamp of to get the first trade in the list when retrieving trades historically.

If unable to parse your value, the exchange will return an error.

Responses

In a JSON response, the key

  • denotes the number of seconds since 1970-01-01 UTC
  • denotes the number of milliseconds since 1970-01-01 UTC

For backwards compatibility, some but not all timestamp values will be supplied in seconds.

Basis Point

We calculate fees as a fraction of the notional value of each trade (i.e., price × amount).

We use units of basis points (“bps”), which represent 1/100th of a percent of notional value.

Gemini cryptocurrency exchange api

For example, a fee of 25 bps means that 0.25% of the denominated value of the trade will be kept by our exchange, either deducted from the gross proceeds of a trade or charged to the account at the time a trade is executed. Any fees will be applied at the time an order is placed. For partially filled orders, only the executed portion is subject to trading fees.

For more information see Fee Calculation.

Symbols and minimums

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

SymbolPrice currencyQuantity currencyMinimum order sizeMinimum order incrementMinimum price increment
USDBTC0.00001 BTC (1e-5)0.00000001 BTC (1e-8)0.01 USD
USDETH0.001 ETH (1e-3)0.000001 ETH (1e-6)0.01 USD
BTCETH0.001 ETH (1e-3)0.000001 ETH (1e-6)0.00001 BTC (1e-5)
USDZEC0.001 ZEC (1e-3)0.000001 ZEC (1e-6)0.01 USD
BTCZEC0.001 ZEC (1e-3)0.000001 ZEC (1e-6)0.00001 BTC (1e-5)
ETHZEC0.001 ZEC (1e-3)0.000001 ZEC (1e-6)0.0001 ETH (1e-4)
BCHZEC0.001 ZEC (1e-3)0.000001 ZEC (1e-6)0.0001 BCH (1e-4)
LTCZEC0.001 ZEC (1e-3)0.000001 ZEC (1e-6)0.001 LTC (1e-3)
USDBCH0.001 BCH (1e-3)0.000001 BCH (1e-6)0.01 USD
BTCBCH0.001 BCH (1e-3)0.000001 BCH (1e-6)0.00001 BTC (1e-5)
ETHBCH0.001 BCH (1e-3)0.000001 BCH (1e-6)0.0001 ETH (1e-4)
USDLTC0.01 LTC (1e-2)0.00001 LTC (1e-5)0.01 USD
BTCLTC0.01 LTC (1e-2)0.00001 LTC (1e-5)0.00001 BTC (1e-5)
ETHLTC0.01 LTC (1e-2)0.00001 LTC (1e-5)0.0001 ETH (1e-4)
BCHLTC0.01 LTC (1e-2)0.00001 LTC (1e-5)0.0001 BCH (1e-4)

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 trade could execute for a quantity of 0.0000000001 (1e-10) BTC. This is due to:

  • incoming market orders that may result in partial fills
  • fees
  • holds

This additional precision is marketable once on the exchange.

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

Public APIs

Symbols

This endpoint retrieves all available symbols for trading

HTTP Request

Sandbox

Base URL can be changed to for test purposes.

URL Parameters

None

Response

An array of supported symbols

JSON response

Ticker

JSON response

This endpoint retrieves information about recent trading activity for the symbol.

HTTP Request

URL Parameters

None

Sandbox

Base URL can be changed to for test purposes.

Response

The response will be an object

FieldTypeDescription
biddecimalThe highest bid currently available
askdecimalThe lowest ask currently available
lastdecimalThe price of the last executed trade
volumenode (nested)Information about the 24 hour volume on the exchange.

See below

The volume field will contain information about the 24 hour volume on the exchange.

Gemini cryptocurrency exchange api

The volume is updated every five minutes based on a trailing 24-hour window of volume. It will have three fields

FieldTypeDescription
timestamptimestampmsThe end of the 24-hour period over which volume was measured
(price symbol, e.g.

Gemini cryptocurrency exchange api

"USD")

decimalThe volume denominated in the price currency
(quantity symbol, e.g. "BTC")decimalThe volume denominated in the quantity currency

Ticker V2

JSON response

This endpoint retrieves information about recent trading activity for the provided symbol.

HTTP Request

URL Parameters

None

Sandbox

Base url can be changed to for test purposes.

Response

The response will be an object

FieldTypeDescription
string etc.
decimalOpen price from 24 hours ago
decimalHigh price from 24 hours ago
decimalLow price from 24 hours ago
decimalClose price (most recent trade)
array of decimalsHourly prices descending for past 24 hours
--decimalClose price for each hour
decimalCurrent best bid
decimalCurrent best offer

Candles

JSON response

This endpoint retrieves time-intervaled data for the provided symbol.

HTTP Request

URL Parameters

None

ParameterTypeDescriptionValues
:symbolStringTrading pair symbol, etc.

See symbols and minimums

:time_frameStringTime range for each candle: 1 minute
: 5 minutes
: 15 minutes
: 30 minutes
: 1 hour
: 6 hours
: 1 day

Sandbox

Base URL can be changed to for test purposes.

Response

The response will be an array of arrays

FieldTypeDescription
Array of ArraysDescending order by time
-- -- timelongTime in milliseconds
-- -- opendecimalOpen price
-- -- highdecimalHigh price
-- -- lowdecimalLow price
-- -- closedecimalClose price
-- -- volumedecimalVolume

Current Order Book

JSON response

This will return the current order book as two arrays (bids / asks).

The quantities and prices returned are returned as strings rather than numbers.

Navigation menu

The numbers returned are exact, not rounded, and it can be dangerous to treat them as floating point numbers.

HTTP Request

Sandbox

Base URL can be changed to for test purposes.

URL Parameters

If a limit is specified on a side, then the orders closest to the midpoint of the book will be the ones returned.

ParameterTypeDescription
limit_bidsintegerOptional.

Limit the number of bid (offers to buy) price levels returned. Default is 50. May be 0 to return the full order book on this side.

limit_asksintegerOptional. Limit the number of ask (offers to sell) price levels returned.

Default is 50. May be 0 to return the full order book on this side.

Response

The response will be two arrays

FieldTypeDescription
bidsarrayThe bid price levels currently on the book. These are offers to buy at a given price
asksarrayThe ask price levels currently on the book.

These are offers to sell at a given price

The bids and the asks are grouped by price, so each entry may represent multiple orders at that price. Each element of the array will be a JSON object

FieldTypeDescription
pricedecimalThe price
amountdecimalThe total quantity remaining at the price
timestamptimestampDO NOT USE - this field is included for compatibility reasons only and is just populated with a dummy value.

Trade History

JSON response

This public API endpoint is limited to retrieving seven calendar days of data.



Please contact us through this form for information about Gemini market data.

This will return the trades that have executed since the specified timestamp. Timestamps are either seconds or milliseconds since the epoch (1970-01-01). See the Data Types section about for information on this.

Each request will show at most 500 records.

If no or is specified, then it will show the most recent trades; otherwise, it will show the most recent trades that occurred after that timestamp.

HTTP Request

Sandbox

Base URL can be changed to for test purposes.

URL Parameters

ParameterTypeDescription
timestamptimestampOptional.

Only return trades after this timestamp. See Data Types: Timestamps for more information. If not present, will show the most recent trades. For backwards compatibility, you may also use the alias 'since'.

limit_tradesintegerOptional. The maximum number of trades to return. The default is 50.
include_breaksbooleanOptional. Whether to display broken trades.

Gemini (company)

False by default. Can be '1' or 'true' to activate

Response

The response will be an array of JSON objects, sorted by timestamp, with the newest trade shown first.

FieldTypeDescription
timestamptimestampThe time that the trade was executed
timestampmstimestampmsThe time that the trade was executed in milliseconds
tidintegerThe trade ID number
pricedecimalThe price the trade was executed at
amountdecimalThe amount that was traded
exchangestringWill always be "gemini"
typestring
  • means that an ask was removed from the book by an incoming buy order
  • means that a bid was removed from the book by an incoming sell order
  • indicates a bulk trade from an auction
  • indicates a block trade
brokenbooleanWhether the trade was broken or not.

Broken trades will not be displayed by default; use the to display them.

Current auction

Before an auction opens

After an auction opens

After an indicative price has been published

After the last indicative price has been published

After the auction runs

HTTP Request

Sanbox

Base URL can be changed to for test purposes.

URL Parameters

None

Response

Response in an object with the following fields:

FieldTypeDescription
closed_until_mstimestampmsIf the auction is not currently open, show the time at which the next auction opens.

Not present if the auction has already opened.

last_auction_eidintegerAfter an auction opens, the unique event ID for last specific auction event. Changes when an auction event occurs: the auction opens, an indicative price is published, and the auction itself runs. Not present before the auction opens.
last_auction_pricedecimalIf available, show the auction price from the last successful auction for this trading pair.

Not present after current auction begins publishing indicative prices.

last_auction_quantitydecimalIf available, show the auction quantity from the last successful auction for this trading pair.

Gemini cryptocurrency exchange api

Not present after current auction begins publishing indicative prices.

last_highest_bid_pricedecimalIf available, show the highest bid price from the continuous trading order book at the time of the last successful auction for this trading pair. Not present after current auction begins publishing indicative prices.
last_lowest_ask_pricedecimalIf available, show the lowest ask price from the continuous trading order book at the time of the last successful auction for this trading pair.

Gemini dollar

Not present after current auction begins publishing indicative prices.

last_collar_pricedecimalIf available, show the collar price at the time of the last successful auction for this trading pair.

Not present after current auction begins publishing indicative prices.

most_recent_indicative_pricedecimalThe most recently published indicative price for the auction.

Not present before the current auction begins publishing indicatives.

most_recent_indicative_quantitydecimalThe most recently published indicative quantity for the auction. Not present before the current auction begins publishing indicatives.
most_recent_highest_bid_pricedecimalThe most recent highest bid at the time of the indicative price for the auction. Not present before the current auction begins publishing indicatives.
most_recent_lowest_ask_pricedecimalThe most recent lowest ask at the time of the indicative price for the auction.

Not present before the current auction begins publishing indicatives.

most_recent_collar_pricedecimalThe most recent collar price at the time of the indicative price for the auction.

Not present before the current auction begins publishing indicatives.

next_update_mstimestampmsTimestamp of the next event in this auction, either the publication of an indicative price/quantity or the auction itself.
next_auction_mstimestampmsTimestamp of when the next auction will run.

Auction history

JSON response