NAV
python shell

Introduction

Gemini offers both public and private REST APIs.

Public REST APIs provide market data such as:

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

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

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.

Your account will automatically be credited with USD, BTC, ETH, BCH, LTC, OXT, LINK, BAT and DAI. 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 trading@gemini.com.

If you have any issues, or if you need to adjust your balances (to test insufficient funds handling, for example), contact trading@gemini.com.

Two Factor Authentication

Two factor authentication ("2FA") is enabled by default for all sandbox accounts. To disable 2FA for automated testing, please do the following:

  1. At the Authy 2FA entry screen, set a cookie or an HTTP header with the name GEMINI-SANDBOX-2FA. The value doesn’t matter.
  2. Enter 9999999 as your 2FA code

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 429 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:

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.

Information you want How to get it through the WebSocket API
Your trade notifictions Order Events: Filled
All trade notifcations Market Data: Trade event
Your active orders
  1. Populate local state using Order Events: Active Orders
  2. then update local state by processing individual order event types as received:
The status of an active order A subscription to Order Events will provide you will all your active orders followed by realtime updates to order status. Maintain local state and look up the status of your order there.
All active orders Market Data: Change Event

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

{
    "request": "/v1/order/status",
    "nonce": <nonce>,
    "order_id": 18834
}

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.

~$ base64 << EOF
> {
>     "request": "/v1/order/status",
>     "nonce": 123456,
>
>     "order_id": 18834
> }
> EOF
ewogICAgInJlcXVlc3QiOiAiL3YxL29yZGVyL3N0YXR1cyIsCiAgICAibm9uY2UiOiAxMjM0NTYs
CgogICAgIm9yZGVyX2lkIjogMTg4MzQKfQo=

encoded_payload = json.dumps(payload)
b64 = base64.b64encode(encoded_payload)

In this example, the api_secret is 1234abcd

echo -n 'ewogICAgInJlcXVlc3QiOiAiL3YxL29yZGVyL3N0YXR1cyIsCiAgICAibm9uY2UiOiAxMjM0NTYsCgogICAgIm9yZGVyX2lkIjogMTg4MzQKfQo=' | openssl sha384 -hmac "1234abcd"
(stdin)= 337cc8b4ea692cfe65b4a85fcc9f042b2e3f702ac956fd098d600ab15705775017beae402be773ceee10719ff70d710f

gemini_api_secret = "1234abcd"
signature = hmac.new(gemini_api_secret, b64, hashlib.sha384).hexdigest()

The final request will look like this:

curl --request POST \
  --url https://api.gemini.com/v1/order/status \
  --header 'Cache-Control: no-cache' \
  --header 'Content-Length: 0' \
  --header 'Content-Type: text/plain' \
  --header 'X-GEMINI-APIKEY: mykey' \
  --header 'X-GEMINI-PAYLOAD: ewogICAgInJlcXVlc3QiOiAiL3YxL29yZGVyL3N0YXR1cyIsCiAgICAibm9uY2UiOiAxMjM0NTYsCgogICAgIm9yZGVyX2lkIjogMTg4MzQKfQo=' \
  --header 'X-GEMINI-SIGNATURE: 337cc8b4ea692cfe65b4a85fcc9f042b2e3f702ac956fd098d600ab15705775017beae402be773ceee10719ff70d710f'

import requests
import json
import base64
import hmac
import hashlib
import time

url = "https://api.gemini.com/v1/mytrades"
gemini_api_key = "mykey"
gemini_api_secret = "1234abcd".encode()

payload_nonce = time.time()

payload =  {"request": "/v1/mytrades", "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, headers=request_headers)

my_trades = response.json()
print(my_trades)

Which produces these HTTP headers

POST /v1/mytrades
Content-Type: text/plain
Content-Length: 0
X-GEMINI-APIKEY: mykey
X-GEMINI-PAYLOAD:ewogICAgInJlcXVlc3QiOiAiL3YxL29yZGVyL3N
    0YXR1cyIsCiAgICAibm9uY2UiOiAxMjM0NTYsCgogICAgIm9yZGV
    yX2lkIjogMTg4MzQKfQo=
X-GEMINI-SIGNATURE: 337cc8b4ea692cfe65b4a85fcc9f042b2e3f
    702ac956fd098d600ab15705775017beae402be773ceee10719f
    f70d710f

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. When provisioning a session key, you have the option of selecting "Uses a time based nonce". If this option is selected, the nonce, which must be in seconds, has to be within +/- 30 seconds of Unix Epoch timestamp to be deemed valid.

If you do not choose the option of a time based nonce, then the nonce has to be 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. 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 Cancel All Session Orders) 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. 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.

All of them will include the request name and the nonce associated with the request.

Header Value
Content-Length 0
Content-Type text/plain
X-GEMINI-APIKEY Your Gemini API key
X-GEMINI-PAYLOAD The base64-encoded JSON payload
X-GEMINI-SIGNATURE hex(HMAC_SHA384(base64(payload), key=api_secret))
Cache-Control no-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. To invoke an API on behalf of an account, add that account's nickname as an account parameter to your request payload.

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

The account 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

{
    "request": "/v1/order/new",
    "account": "my-trading-account",
    "nonce": <nonce>,
    "client_order_id": <client_order_id>,
    "symbol": "btcusd",
    "amount": "5",
    "price": "3633.00",
    "side": "buy",
    "type": "exchange limit"
}

Roles

Example of error response due to API key missing a role

{
   "result":"error",
   "reason":"MissingRole",
   "message":"To access this endpoint, you need to log in to the website and go to the settings page to assign one of these roles [FundManager] to API key wujB3szN54gtJ4QDhqRJ which currently has roles [Trader]"
}

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, 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.

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:

See Error Codes for more information about API error responses.

Administrator

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

Trader

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

Fund Manager

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

Auditor

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

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

Endpoint URI Trader can access? Fund Manager can access? Auditor can access?
New Order /v1/order/new ✓ ✗ ✗
Cancel Order /v1/order/cancel ✓ ✗ ✗
Cancel All Session Orders /v1/order/cancel/session ✓ ✗ ✗
Cancel All Active Orders /v1/order/cancel/all ✓ ✗ ✗
Wrap Order /v1/wrap/:symbol ✓ ✗ ✗
Order Status /v1/order/status ✓ ✗ ✓
Get Active Orders /v1/orders ✓ ✗ ✓
Get Past Trades /v1/mytrades ✓ ✗ ✓
Get Orders History /v1/orders/history ✓ ✗ ✓
Get Trade Volume /v1/tradevolume ✓ ✗ ✓
Get Notional Volume /v1/notionalvolume ✓ ✗ ✓
Heartbeat /v1/heartbeat ✓ ✗ ✗
Get Available Balances /v1/balances ✓ ✓ ✓
Get Notional Balances v1/notionalbalances/:currency ✓ ✓ ✓
Get Deposit Addresses /v1/addresses/:network ✓ ✓ ✓
New Deposit Address /v1/deposit/:network/newAddress ✗ ✓ ✗
Transfers /v1/transfers ✓ ✓ ✓
Custody Account Fees /v1/custodyaccountfees ✓ ✓ ✓
Withdraw Crypto Funds /v1/withdraw/:currency ✗ ✓ ✗
New Clearing Order /v1/clearing/new ✓ ✗ ✗
Clearing Order Status /v1/clearing/status ✓ ✗ ✓
Cancel Clearing Order /v1/clearing/cancel ✓ ✗ ✗
Confirm Clearing Order /v1/clearing/confirm ✓ ✗ ✗
Clearing Order List /v1/clearing/list ✓ ✗ ✗
Clearing Broker List /v1/clearing/broker/list ✓ ✗ ✗
Clearing Trades /v1/clearing/trades ✓ ✗ ✗
Get Instant Quote /v1/instant/quote/:side/:symbol ✓ ✗ ✗
Execute Instant Order /v1/instant/execute ✓ ✗ ✗
Add A Bank /v1/payments/addbank ✗ ✓ ✗
Add A Bank CAD /v1/payments/addbank/cad ✗ ✓ ✗
View Payment Methods /v1/payments/methods ✓ ✓ ✓
Account Detail /v1/account ✓ ✓ ✓
Create Approved Address /v1/approvedAddresses/:network/request ✗ ✓ ✗
View Approved Address List /v1/approvedAddresses/account/:network ✓ ✓ ✓
Remove Address from Approved Address List /v1/approvedAddresses/:network/remove ✗ ✓ ✗
FX Rate /v2/fxrate/:symbol/:timestamp ✗ ✗ ✓

Master Scoped API

Endpoint URI Administrator can access? Trader can access? Fund Manager can access? Auditor can access?
Create Account /v1/account/create ✓ ✗ ✗ ✗
Rename Account /v1/account/rename ✓ ✗ ✗ ✗
Get Accounts /v1/account/list ✓ ✓ ✓ ✓
Internal Transfer /v1/account/transfer/:currency ✗ ✗ ✓ ✗
Transactions /v1/transactions ✓ ✓ ✓ ✓

Roles API

HTTP Request

POST https://api.gemini.com/v1/roles

The v1/roles endpoint will return a string of the role of the current API key. The response fields will be different for account-level and master-level API keys.

Sample payload

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

Successful response for account-scoped key

{
    "counterparty_id": EMONNYXJ,
    "isAuditor": False,
    "isFundManager": True,
    "isTrader": True
}

Successful response for master-scoped key

{
    "isAuditor": False,
    "isFundManager": True,
    "isTrader": True,
    "isAccountAdmin": True
}

Parameters

Parameter Type Description
request string the literal string "/v1/roles"
nonce integer or timestamp The 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 /v1/roles. The Auditor role cannot be combined with other roles. Fund Manager and Trader can be combined.

Field Type Description
counterparty_id string Only returned for master-level API keys. The Gemini clearing counterparty ID associated with the API key making the request.
isAuditor boolean True if the Auditor role is assigned to the API keys. False otherwise.
isFundManager boolean True if the Fund Manager role is assigned to the API keys. False otherwise.
isTrader boolean True if the Trader role is assigned to the API keys. False otherwise.
isAccountAdmin boolean Only returned for master-level API keys. True if the Administrator role is assigned to the API keys. False 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:

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

If you receive a 400 error that you are missing required data, then copy the base64 encoded string in X-GEMINI-PAYLOAD to a base64 decoder such as https://www.base64decode.org/ and decode it. Compare the decoded JSON to the documentation for the endpoint you are trying to access.

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

Support

If you still have a problem then contact trading@gemini.com 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:

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

[ {
  "type" : "accepted",
  "order_id" : "372456298",
  "event_id" : "372456299",
  "client_order_id": "20170208_example", 
  "api_session" : "AeRLptFXoYEqLaNiRwv8",
  "symbol" : "btcusd",
  "side" : "buy",
  "order_type" : "exchange limit",
  "timestamp" : "1478203017",
  "timestampms" : 1478203017455,
  "is_live" : true,
  "is_cancelled" : false,
  "is_hidden" : false,
  "avg_execution_price" : "0", 
  "original_amount" : "14.0296",
  "price" : "1059.54"
} ]

Order Status endpoint for the same order, showing client_order_id

{
    "avg_execution_price": "0.00",
    "client_order_id": "20170208_example",
    "exchange": "gemini",
    "executed_amount": "0",
    "id": "372456298",
    "is_cancelled": false,
    "is_hidden": false,
    "is_live": true,
    "order_id": "372456298",
    "original_amount": "14.0296",
    "price": "1059.54",
    "remaining_amount": "14.0296",
    "side": "buy",
    "symbol": "btcusd",
    "timestamp": "1478203017",
    "timestampms": 1478203017455,
    "type": "exchange limit",
    "was_forced": false
}

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 client_order_id when placing orders using the New Order endpoint.

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: [:\-_\.#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 Transfer ID

Client transfer ID is an optional client-supplied unique identifier for each withdrawal or internal transfer.

Although this identifier is optional, it is useful for preventing submission of duplicate withdrawal or internal transfers.

Data Types

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

Type Description
string A simple quoted string, following standard JSON rules; see the JSON spec for details.
decimal A decimal value, encoded in a JSON string. The contents will be a series of digits, followed by an optional decimal point and additional digits.
timestamp The number of seconds since 1970-01-01 UTC. 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
timestampms The 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.
integer An whole number, transmitted as a JSON number.
boolean A JSON boolean, the literal string true or false
array a 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

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 POST request may supply the timestamp parameter in a JSON payload as a string instead of a number.

Timestamp format example Supported request type
whole number (seconds) 1495127793 GET, POST
string (seconds) "1495127793" POST only
whole number (milliseconds) 1495127793000 GET, POST
string (milliseconds) "1495127793000" POST only

Behavior

If the timestamp 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 timestamp parameter.

The first trade on Gemini occurred at 1444311607801 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 0 to get the first trade in the list when retrieving trades historically.

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

Responses

In a JSON response, the key

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. 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 CCY1CCY2 where prices are in CCY2 and quantities are in CCY1. CCY1 is in the Currency column and CCY2 is in the respective CCY2 Price Increment column:

Symbol Minimum Order Size Tick Size Quote Currency Price Increment
btcusd 0.00001 BTC (1e-5) 0.00000001 BTC (1e-8) 0.01 USD
btceur 0.00001 BTC (1e-5) 0.00000001 BTC (1e-8) 0.01 EUR
btcgbp 0.00001 BTC (1e-5) 0.00000001 BTC (1e-8) 0.01 GBP
btcsgd 0.00001 BTC (1e-5) 0.00000001 BTC (1e-8) 0.01 SGD
ethbtc 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.00001 BTC (1e-5)
ethusd 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.01 USD
etheur 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.01 EUR
ethgbp 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.01 GBP
ethsgd 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.01 SGD
bchusd 0.001 BCH (1e-3) 0.000001 BCH (1e-6) 0.01 USD
bchbtc 0.001 BCH (1e-3) 0.000001 BCH (1e-6) 0.00001 BTC (1e-5)
bcheth 0.001 BCH (1e-3) 0.000001 BCH (1e-6) 0.0001 ETH (1e-4)
ltcusd 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.01 USD
ltcbtc 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.0000001 BTC (1e-7)
ltceth 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.00001 ETH (1e-5)
ltcbch 0.01 LTC (1e-2) 0.00001 LTC (1e-5) 0.0001 BCH (1e-4)
batusd 1.0 BAT (1e0) 0.000001 BAT (1e-6) 0.00001 USD (1e-5)
daiusd 0.1 DAI (1e-1) 0.000001 DAI (1e-6) 0.00001 USD (1e-5)
linkusd 0.1 LINK (1e-1) 0.000001 LINK (1e-6) 0.00001 USD (1e-5)
oxtusd 1.0 OXT (1e0) 0.000001 OXT (1e-6) 0.00001 USD (1e-5)
linkbtc 0.1 LINK (1e-1) 0.000001 LINK (1e-6) 0.00000001 BTC (1e-8)
linketh 0.1 LINK (1e-1) 0.000001 LINK (1e-6) 0.0000001 ETH (1e-7)
ampusd 10.0 AMP (1e1) 0.000001 AMP (1e-6) 0.00001 USD (1e-5)
compusd 0.001 COMP (1e-3) 0.000001 COMP (1e-6) 0.01 USD
paxgusd 0.0001 PAXG (1e-4) 0.00000001 PAXG (1e-8) 0.01 USD
mkrusd 0.001 MKR (1e-3) 0.000001 MKR (1e-6) 0.01 USD
zrxusd 0.1 ZRX (1e-1) 0.000001 ZRX (1e-6) 0.00001 USD (1e-5)
manausd 1.0 MANA (1e0) 0.000001 MANA (1e-6) 0.00001 USD (1e-5)
storjusd 0.1 STORJ (1e-1) 0.000001 STORJ (1e-6) 0.00001 USD (1e-5)
crvusd 0.1 CRV (1e-1) 0.000001 CRV (1e-6) 0.0001 USD (1e-4)
uniusd 0.01 UNI (1e-2) 0.000001 UNI (1e-6) 0.0001 USD (1e-4)
renusd 0.01 REN (1e-2) 0.000001 REN (1e-6) 0.00001 USD (1e-5)
umausd 0.01 UMA (1e-2) 0.000001 UMA (1e-6) 0.0001 USD (1e-4)
yfiusd 0.00001 YFI (1e-5) 0.000001 YFI (1e-6) 0.01 USD
aaveusd 0.001 AAVE (1e-3) 0.000001 AAVE (1e-6) 0.0001 USD (1e-4)
filusd 0.1 FIL (1e-1) 0.000001 FIL (1e-6) 0.0001 USD (1e-4)
sklusd 0.1 SKL (1e-1) 0.000001 SKL (1e-6) 0.00001 USD (1e-5)
grtusd 0.1 GRT (1e-1) 0.000001 GRT (1e-6) 0.0001 USD (1e-4)
lrcusd 0.1 LRC (1e-1) 0.000001 LRC (1e-6) 0.00001 USD (1e-5)
sandusd 0.1 SAND (1e-1) 0.000001 SAND (1e-6) 0.00001 USD (1e-5)
cubeusd 0.01 CUBE (1e-2) 0.000001 CUBE (1e-6) 0.0001 USD (1e-4)
lptusd 0.001 LPT (1e-3) 0.000001 LPT (1e-6) 0.0001 USD (1e-4)
maticusd 0.1 MATIC (1e-1) 0.000001 MATIC (1e-6) 0.00001 USD (1e-5)
injusd 0.01 INJ (1e-2) 0.000001 INJ (1e-6) 0.0001 USD (1e-4)
sushiusd 0.01 SUSHI (1e-2) 0.000001 SUSHI (1e-6) 0.0001 USD (1e-4)
dogeusd 0.1 DOGE (1e-1) 0.000001 DOGE (1e-6) 0.00001 USD (1e-5)
ftmusd 0.03 FTM (3e-2) 0.000001 FTM (1e-6) 0.0001 USD (1e-4)
ankrusd 0.1 ANKR (1e-1) 0.000001 ANKR (1e-6) 0.00001 USD (1e-5)
btcgusd 0.00001 BTC (1e-5) 0.00000001 BTC (1e-8) 0.01 GUSD
ethgusd 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.01 GUSD
ctxusd 0.002 CTX (2e-3) 0.000001 CTX (1e-6) 0.0001 USD (1e-4)
xtzusd 0.02 XTZ (2e-2) 0.000001 XTZ (1e-6) 0.0001 USD (1e-4)
axsusd 0.003 AXS (3e-3) 0.000001 AXS (1e-6) 0.01 USD (1e-2)
dogebtc 1.0 DOGE (1e0) 0.00000001 DOGE (1e-8) 0.000000001 BTC (1e-9)
dogeeth 1.0 DOGE (1e0) 0.00000001 DOGE (1e-8) 0.00000001 ETH (1e-8)
rareusd 0.1 RARE (1e-1) 0.000001 RARE (1e-6) 0.001 USD (1e-3)
qntusd 0.0004 QNT (4e-4) 0.000001 QNT (1e-6) 0.01 USD (1e-2)
maskusd 0.01 MASK (1e-2) 0.000001 MASK (1e-6) 0.001 USD (1e-3)
fetusd 0.1 FET (1e-1) 0.000001 FET (1e-6) 0.00001 USD (1e-5)
api3usd 0.03 API3 (3e-2) 0.000001 API3 (1e-6) 0.001 USD (1e-3)
usdcusd 0.1 USDC (1e-1) 0.000001 USDC (1e-6) 0.00001 USD (1e-5)
shibusd 1000.0 SHIB (1e3) 0.000001 SHIB (1e-6) 0.000000001 USD (1e-9)
rndrusd 0.02 RNDR (2e-2) 0.000001 RNDR (1e-6) 0.001 USD (1e-3)
galausd 0.4 GALA (4e-1) 0.000001 GALA (1e-6) 0.00001 USD (1e-5)
ensusd 0.002 ENS (2e-3) 0.000001 ENS (1e-6) 0.001 USD (1e-3)
tokeusd 0.002 TOKE (2e-3) 0.000001 TOKE (1e-6) 0.001 USD (1e-3)
ldousd 0.02 LDO (2e-2) 0.000001 LDO (1e-6) 0.001 USD (1e-3)
rlyusd 0.2 RLY (2e-1) 0.000001 RLY (1e-6) 0.00001 USD (1e-5)
solusd 0.001 SOL (1e-3) 0.000001 SOL (1e-6) 0.001 USD (1e-3)
apeusd 0.02 APE (2e-2) 0.000001 APE (1e-6) 0.001 USD (1e-3)
gusdsgd 0.1 GUSD 0.000001 GUSD (1e-6) 0.001 SGD (1e-3)
chzusd 0.5 CHZ (5e-1) 0.000001 CHZ (1e-6) 0.00001 USD (1e-5)
jamusd 10.0 JAM (1e1) 0.000001 JAM (1e-6) 0.0000001 USD (1e-7)
gmtusd 0.1 GMT (1e-1) 0.000001 GMT (1e-6) 0.00001 USD (1e-5)
aliusd 2.0 ALI (2e0) 0.000001 ALI (1e-6) 0.000001 USD (1e-6)
gusdgbp 0.1 GUSD 0.0001 GUSD (1e-4) 0.001 GBP (1e-3)
dotusd 0.01 DOT (1e-2) 0.000001 DOT (1e-6) 0.0001 USD (1e-4)
ernusd 0.05 ERN (5e-2) 0.000001 ERN (1e-6) 0.0001 USD (1e-4)
elonusd 60000.0 ELON (6e4) 0.000001 ELON (1e-6) 0.00000000001 USD (1e-11)
galusd 0.04 GAL (4e-2) 0.000001 GAL (1e-6) 0.0001 USD (1e-4)
samousd 10.0 SAMO (1e+1) 0.000001 SAMO (1e-6) 0.0000001 USD (1e-7)
imxusd 0.1 IMX (1e-1) 0.000001 IMX (1e-6) 0.00001 USD (1e-5)
iotxusd 3.0 IOTX (3e+0) 0.000001 IOTX (1e-6) 0.000001 USD (1e-6)
avaxusd 0.005 AVAX (5e-3) 0.000001 AVAX (1e-6) 0.001 USD (1e-3)
atomusd 0.01 ATOM (1e-2) 0.000001 ATOM (1e-6) 0.001 USD (1e-3)
usdtusd* 0.1 USDT (1e-1) 0.000001 USDT (1e-6) 0.0001 USD (1e-4)
btcusdt* 0.00001 BTC (1e-5) 0.00000001 BTC (1e-8) 0.01 USDT (1e-2)
ethusdt* 0.001 ETH (1e-3) 0.000001 ETH (1e-6) 0.01 USDT (1e-2)
pepeusd 1000 PEPE (1e3) 0.000001 PEPE (1e-6) 0.000000001 USD (1e-9)
xrpusd 0.1 XRP (1e-1) 0.000001 XRP (1e-6) 0.00001 USD (1e-5)
hntusd 0.04 HNT (4e-1) 0.000001 HNT (1e-6) 0.0001 USD (1e-4)
wifusd 0.07 WIF (7e-2) 0.000001 WIF (1e-6) 0.0001 USD (1e-4)
bonkusd 4000 BONK (4e3) 0.000001 BONK (1e-6) 0.000000001 USD (1e-9)
popcatusd 0.07 POPCAT (7e-2) 0.000001 POPCAT (1e-6) 0.0001 USD (1e-4)
opusd 0.07 OP (7e-2) 0.000001 OP (1e-6) 0.0001 USD (1e-4)
moodeng 1 MOODENG (1) 0.000001 MOODENG (1e-6) 0.000001 USD (1e-6)
pnutusd 0.2 PNUT (2e-1) 0.0001 PNUT (1e-4) 0.0001 USD (1e-4)
goatusd 0.1 GOAT (1e-1) 0.000001 GOAT (1e-6) 0.0001 USD (1e-4)
mewusd 10 MEW (1e1) 0.01 MEW (1e-2) 0.000001 USD (1e-6)
bomeusd 10 BOME (1e1) 0.01 BOME (1e-2) 0.000001 USD (1e-6)

*Note: Not available to trade for customers in New York

All Supported Symbols

btcusd ethbtc ethusd bchusd bchbtc bcheth ltcusd ltcbtc ltceth ltcbch batusd daiusd linkusd oxtusd linkbtc linketh ampusd compusd paxgusd mkrusd zrxusd manausd storjusd crvusd uniusd renusd umausd yfiusd aaveusd filusd btceur btcgbp etheur ethgbp btcsgd ethsgd sklusd grtusd lrcusd sandusd cubeusd lptusd maticusd injusd sushiusd dogeusd ftmusd ankrusd btcgusd ethgusd ctxusd xtzusd axsusd dogebtc dogeeth rareusd qntusd maskusd fetusd api3usd usdcusd shibusd rndrusd galausd ensusd elonusd tokeusd ldousd rlyusd solusd apeusd gusdsgd chzusd jamusd gmtusd aliusd gusdgbp dotusd ernusd galusd samousd imxusd iotxusd avaxusd atomusd usdtusd btcusdt ethusdt pepeusd xrpusd hntusd wifusd bonkusd popcatusd opusd moodeng pnutusd goatusd mewusd bomeusd

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.

Public APIs

Symbols

$ curl "https://api.gemini.com/v1/symbols"

import requests, json

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

print(symbols)

This endpoint retrieves all available symbols for trading

HTTP Request

GET https://api.gemini.com/v1/symbols

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

URL Parameters

None

Response

An array of supported symbols. The full list of supported symbols:

Symbols

btcusd ethbtc ethusd bchusd bchbtc bcheth ltcusd ltcbtc ltceth ltcbch batusd daiusd linkusd oxtusd linkbtc linketh ampusd compusd paxgusd mkrusd zrxusd manausd storjusd crvusd uniusd renusd umausd yfiusd aaveusd filusd btceur btcgbp etheur ethgbp btcsgd ethsgd sklusd grtusd lrcusd sandusd cubeusd lptusd maticusd injusd sushiusd dogeusd ftmusd ankrusd btcgusd ethgusd ctxusd xtzusd axsusd efilfil gusdusd dogebtc dogeeth rareusd qntusd maskusd fetusd api3usd usdcusd shibusd rndrusd galausd ensusd tokeusd ldousd rlyusd solusd apeusd gusdsgd zbcusd chzusd jamusd gmtusd aliusd gusdgbp dotusd ernusd galusd samousd imxusd iotxusd avaxusd atomusd usdtusd btcusdt ethusdt pepeusd xrpusd hntusd btcgusdperp ethgusdperp pepegusdperp xprgusdperp solgusdperp maticgusdperp dogegusdperp linkgusdperp avaxgusdperp ltcgusdperp dotgusdperp bnbgusdperp injgusdperp wifgusdperp wifusd bonkusd popcatusd opusd bonkgusdperp popcatgusdperp opgusdperp moodengusd pnutusd goatusd mewusd bomeusd

JSON response


["btcusd", "ethbtc", "ethusd", "bchusd", "bchbtc", "bcheth", "ltcusd", "ltcbtc", "ltceth", "ltcbch", "batusd", "daiusd", "linkusd", "oxtusd", "linkbtc", "linketh", "ampusd", "compusd", "paxgusd", "mkrusd", "zrxusd", "manausd", "storjusd", "crvusd", "uniusd", "renusd", "umausd", "yfiusd", "btcdai", "ethdai", "aaveusd", "filusd", "btceur", "btcgbp", "etheur", "ethgbp", "btcsgd", "ethsgd", "sklusd", "grtusd", "lrcusd", "sandusd", "cubeusd", "lptusd", "maticusd", "injusd", "sushiusd", "dogeusd", "ftmusd", "ankrusd", "btcgusd", "ethgusd", "ctxusd", "xtzusd", "axsusd", "efilfil", "gusdusd", "dogebtc", "dogeeth", "rareusd", "qntusd", "maskusd", "fetusd", "api3usd", "usdcusd", "shibusd", "rndrusd", "galausd", "ensusd", "elonusd", "tokeusd", "ldousd", "rlyusd", "solusd", "apeusd", "gusdsgd", "chzusd", "jamusd", "gmtusd", "aliusd", "gusdgbp", "dotusd", "ernusd", "galusd", "samousd", "imxusd", "iotxusd", "avaxusd", "atomusd", "usdtusd", "btcusdt","ethusdt","pepeusd","xrpusd", "hntusd", "btcgusdperp", "ethgusdperp", "pepegusdperp","xrpgusdperp", "solgusdperp", "maticgusdperp", "dogegusdperp", "linkgusdperp", "avaxgusdperp", "ltcgusdperp", "dotgusdperp", "bnbgusdperp", "injgusdperp", "wifgusdperp", "wifusd","bonkusd", "popcatusd", "opusd", "opgusdperp", "popcatgusdperp", "bonkgusdperp" "moodengusd", "pnutusd", "goatusd", "mewusd", "bomeusd"]

Symbol Details

$ curl "https://api.gemini.com/v1/symbols/details/:symbol"

import requests, json

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/symbols/details/:symbol")
symbols = response.json()

print(symbols)

This endpoint retrieves extra detail on supported symbols, such as minimum order size, tick size, quote increment and more.

HTTP Request

GET https://api.gemini.com/v1/symbols/details/:symbol

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

URL Parameters

Parameter Type Description Values
:symbol String Trading pair symbol BTCUSD, etc. See symbols and minimums

Response

The response will be an object

Field Type Description
symbol string The requested symbol. See symbols and minimums
base_currency string CCY1 or the top currency. (ieBTC in BTCUSD)
quote_currency string CCY2 or the quote currency. (ie USD in BTCUSD)
tick_size decimal The number of decimal places in the base_currency. (ie 1e-8)
quote_increment decimal The number of decimal places in the quote_currency (ie 0.01)
min_order_size string The minimum order size in base_currency units (ie 0.00001)
status string Status of the current order book. Can be open, closed, cancel_only, post_only, limit_only.
wrap_enabled boolean When True, symbol can be wrapped using this endpoint: POST https://api.gemini.com/v1/wrap/:symbol
product_type string instrument type spot / swap -- where swap signifies perpetual swap.
contract_type string vanilla / linear / inverse where vanilla is for spot
while linear is for perpetual swap
and inverse is a special case perpetual swap where the perpetual contract will be settled in base currency
contract_price_currency string CCY2 or the quote currency for spot instrument (i.e. USD in BTCUSD)
Or collateral currency of the contract in case of perpetual swap instrument

JSON response - Spot instrument response

{
  "symbol": "BTCUSD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "tick_size": 1E-8,
  "quote_increment": 0.01,
  "min_order_size": "0.00001",
  "status": "open",
  "wrap_enabled": false,
  "product_type":"spot",
  "contract_type":"vanilla",
  "contract_price_currency":"USD"

}

JSON response - Perpetual Swap instrument response

{
  "symbol":"BTCETHPERP",
  "base_currency":"BTC",
  "quote_currency":"ETH",
  "tick_size":0.0001,
  "quote_increment":0.5,
  "min_order_size":"0.0001",
  "status":"open",
  "wrap_enabled":false,
  "product_type":"swap",
  "contract_type":"linear",
  "contract_price_currency":"GUSD"
}

Network

$ curl "https://api.gemini.com/v1/network/rbn"

import requests, json

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/nework/rbn")
network = response.json()

print(network)

This endpoint retrieves the associated network for a requested token.

HTTP Request

GET https://api.gemini.com/v1/network/:token

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

URL Parameters

Parameter Type Description Values
:token String Token identifier BTC, ETH, SOL etc. See symbols and minimums

Response

The response will be a JSON object:

Field Type Description
token string The requested token.
network array Network of the requested token.

JSON response


{
  "token":"RBN",
  "network":["ethereum"]
}

Ticker

import requests, json

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

print(btc_data)

$ curl "https://api.gemini.com/v1/pubticker/btcusd"

JSON response

{
    "ask": "977.59",
    "bid": "977.35",
    "last": "977.65",
    "volume": {
        "BTC": "2210.505328803",
        "USD": "2135477.463379586263",
        "timestamp": 1483018200000
    }
}

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

HTTP Request

GET https://api.gemini.com/v1/pubticker/:symbol

URL Parameters

None

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

Response

The response will be an object

Field Type Description
bid decimal The highest bid currently available
ask decimal The lowest ask currently available
last decimal The price of the last executed trade
volume node (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. The volume is updated every five minutes based on a trailing 24-hour window of volume. It will have three fields

Field Type Description
timestamp timestampms The end of the 24-hour period over which volume was measured
(price symbol, e.g. "USD") decimal The volume denominated in the price currency
(quantity symbol, e.g. "BTC") decimal The volume denominated in the quantity currency

Ticker V2

import requests, json

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

print(btc_data)

$ curl "https://api.gemini.com/v2/ticker/btcusd"

JSON response

{
  "symbol": "BTCUSD",
  "open": "9121.76",
  "high": "9440.66",
  "low": "9106.51",
  "close": "9347.66",
  "changes": [
    "9365.1",
    "9386.16",
    "9373.41",
    "9322.56",
    "9268.89",
    "9265.38",
    "9245",
    "9231.43",
    "9235.88",
    "9265.8",
    "9295.18",
    "9295.47",
    "9310.82",
    "9335.38",
    "9344.03",
    "9261.09",
    "9265.18",
    "9282.65",
    "9260.01",
    "9225",
    "9159.5",
    "9150.81",
    "9118.6",
    "9148.01"
  ],
  "bid": "9345.70",
  "ask": "9347.67"
}

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

HTTP Request

GET https://api.gemini.com/v2/ticker/:symbol

URL Parameters

None

Sandbox

Base url can be changed to api.sandbox.gemini.com/v2 for test purposes.

Response

The response will be an object

Field Type Description
symbol string BTCUSD etc.
open decimal Open price from 24 hours ago
high decimal High price from 24 hours ago
low decimal Low price from 24 hours ago
close decimal Close price (most recent trade)
changes array of decimals Hourly prices descending for past 24 hours
-- decimal Close price for each hour
bid decimal Current best bid
ask decimal Current best offer

Candles

import requests, json

base_url = "https://api.gemini.com/v2"
response = requests.get(base_url + "/candles/btcusd/15m")
btc_candle_data = response.json()

print(btc_candle_data)

$ curl "https://api.gemini.com/v2/candles/btcusd/15m"

JSON response

[
    [
     1559755800000,
     7781.6,
     7820.23,
     7776.56,
     7819.39,
     34.7624802159
    ],
    [1559755800000,
    7781.6,
    7829.46,
    7776.56,
    7817.28,
    43.4228281059],
    ...
]

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

HTTP Request

GET https://api.gemini.com/v2/candles/:symbol/:time_frame

URL Parameters

None

Parameter Type Description Values
:symbol String Trading pair symbol BTCUSD, etc. See symbols and minimums
:time_frame String Time range for each candle 1m: 1 minute
5m: 5 minutes
15m: 15 minutes
30m: 30 minutes
1hr: 1 hour
6hr: 6 hours
1day: 1 day

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v2 for test purposes.

Response

The response will be an array of arrays

Field Type Description
Array of Arrays Descending order by time
-- -- time long Time in milliseconds
-- -- open decimal Open price
-- -- high decimal High price
-- -- low decimal Low price
-- -- close decimal Close price
-- -- volume decimal Volume

Derivatives Candles

import requests, json

base_url = "https://api.gemini.com/v2"
response = requests.get(base_url + "/derivatives/candles/BTCGUSDPERP/1m")
btc_perps_candle_data = response.json()

print(btc_perps_candle_data)

$ curl "https://api.gemini.com/v2/derivatives/candles/BTCGUSDPERP/1m"

JSON response

[
    [
      1714126740000,
      68038,
      68038,
      68038,
      68038,
      0
    ],
    [
      1714126680000,
      68038,
      68038,
      68038,
      68038,
      0
    ],
    ...
]

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

HTTP Request

GET https://api.gemini.com/v2/derivatives/candles/:symbol/:time_frame

URL Parameters

None

Parameter Type Description Values
:symbol String Trading pair symbol available only for perpetual pairs likeBTCGUSDPERP, See symbols and minimums
:time_frame String Time range for each candle 1m: 1 minute (only)

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v2 for test purposes.

Response

The response will be an array of arrays

Field Type Description
Array of Arrays Descending order by time
-- -- time long Time in milliseconds
-- -- open decimal Open price
-- -- high decimal High price
-- -- low decimal Low price
-- -- close decimal Close price
-- -- volume decimal Volume

Fee Promos

$ curl "https://api.gemini.com/v1/feepromos"

import requests, json

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

print(feepromos)

This endpoint retrieves symbols that currently have fee promos.

HTTP Request

GET https://api.gemini.com/v1/feepromos

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

URL Parameters

None

Response

The response will be a JSON object:

Field Type Description
symbols array Symbols that currently have fee promos

JSON response


{
  "symbols": [
    "GMTUSD",
    "GUSDGBP",
    "MIMUSD",
    "ORCAUSD",
    "RAYUSD",
    "FIDAUSD",
    "SOLUSD",
    "USDCUSD",
    "SRMUSD",
    "SBRUSD",
    "GUSDSGD",
    "DAIUSD"
  ]
}

Current Order Book

curl "https://api.gemini.com/v1/book/btcusd"

import requests, json

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

print(btc_book)

JSON response


{
  "bids": [{
            "price": "3607.85",
            "amount": "6.643373",
            "timestamp": "1547147541"
           }
           ...
           ],
  "asks": [{
            "price": "3607.86",
            "amount": "14.68205084",
            "timestamp": "1547147541"
           }
           ...
           ]
}

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

HTTP Request

GET https://api.gemini.com/v1/book/:symbol

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 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.

Parameter Type Description
limit_bids integer Optional. 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_asks integer Optional. 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

Field Type Description
bids array The bid price levels currently on the book. These are offers to buy at a given price
asks array The 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

Field Type Description
price decimal The price
amount decimal The total quantity remaining at the price
timestamp timestamp DO NOT USE - this field is included for compatibility reasons only and is just populated with a dummy value.

Trade History

curl "https://api.gemini.com/v1/trades/btcusd?since=$(date -d 2014-01-01 +%s)"

import requests, json

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

print(btcusd_trades)

JSON response

[
  {
    "timestamp": 1547146811,
    "timestampms": 1547146811357,
    "tid": 5335307668,
    "price": "3610.85",
    "amount": "0.27413495",
    "exchange": "gemini",
    "type": "buy"
  },
  ...
]

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 timestamp for information on this.

Each request will show at most 500 records.

If no since or timestamp 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

GET https://api.gemini.com/v1/trades/:symbol

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

URL Parameters

Parameter Type Description
timestamp timestamp Optional. 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'. With timestamp, there is a 90-day hard limit.
since_tid integer Optional. Only retuns trades that executed after this tid. since_tid trumps timestamp parameter which has no effect if provided too. You may set since_tid to zero to get the earliest available trade history data.
limit_trades integer Optional. The maximum number of trades to return. The default is 50.
include_breaks boolean Optional. Whether to display broken trades. 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.

Field Type Description
timestamp timestamp The time that the trade was executed
timestampms timestampms The time that the trade was executed in milliseconds
tid integer The trade ID number
price decimal The price the trade was executed at
amount decimal The amount that was traded
exchange string Will always be "gemini"
type string
  • buy means that an ask was removed from the book by an incoming buy order
  • sell means that a bid was removed from the book by an incoming sell order
broken boolean Whether the trade was broken or not. Broken trades will not be displayed by default; use the include_breaks to display them.

Price feed

import requests, json

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/pricefeed")
prices = response.json()

print(prices)

$ curl "https://api.gemini.com/v1/pricefeed"

JSON Response

[   
    {
        "pair":"BTCUSD",
        "price":"9500.00",
        "percentChange24h": "5.23"
    },
    {
        "pair":"ETHUSD",
        "price":"257.54",
        "percentChange24h": "4.85"
    },
    {
        "pair":"BCHUSD",
        "price":"450.10",
        "percentChange24h": "-2.91"
    },
    {
        "pair":"LTCUSD",
        "price":"79.50",
        "percentChange24h": "7.63"
    }
]

HTTP Request

GET https://api.gemini.com/v1/pricefeed

Sanbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

URL Parameters

None

Response

Response is a list of objects, one for each pair,with the following fields:

Field Type Description
pair String Trading pair symbol. See symbols and minimums
price String Current price of the pair on the Gemini order book
percentChange24h String 24 hour change in price of the pair on the Gemini order book

Funding Amount

$ curl "https://api.gemini.com/v1/fundingamount/:symbol"

import requests, json

base_url = "https://api.gemini.com/v1"
response = requests.get(base_url + "/fundingamount/:symbol")
symbols = response.json()

print(symbols)

This endpoint retrieves extra detail on supported symbols, such as minimum order size, tick size, quote increment and more.

HTTP Request

GET https://api.gemini.com/v1/fundingamount/:symbol

Sandbox

Base URL can be changed to api.sandbox.gemini.com/v1 for test purposes.

URL Parameters

Parameter Type Description Values
:symbol String Trading pair symbol BTCGUSDPERP, etc. See symbols and minimums

Response

The response will be an object

Field Type Description
symbol string The requested symbol. See symbols and minimums
fundingDateTime string UTC date time in format yyyy-MM-ddThh:mm:ss.SSSZ format
fundingTimestampMilliSecs long Current funding amount Epoc time.
nextFundingTimestamp long Next funding amount Epoc time.
amount decimal The dollar amount for a Long 1 position held in the symbol for funding period (1 hour)
estimatedFundingAmount decimal The estimated dollar amount for a Long 1 position held in the symbol for next funding period (1 hour)

JSON response


{
    "symbol": "btcgusdperp",
    "fundingDateTime": "2023-06-12T03:00:00.000Z",
    "fundingTimestampMilliSecs": 1686538800000,
    "nextFundingTimestamp": 1686542400000,
    "fundingAmount": 0.51692,
    "estimatedFundingAmount": 0.27694
}

Funding Amount Report File

HTTP Request

GET https://api.gemini.com/v1/fundingamountreport/records.xlsx?symbol=<symbol>&fromDate=<date>&toDate=<date>&numRows=<rows>

Parameters

Parameter Type Description
symbol string Mandatory
fromDate integer Mandatory if toDate is specified. Else, Optional. If empty, will only fetch records by numRows value
toDate string Mandatory if fromDate is specified. Else, Optional. If empty, will only fetch records by numRows value
numRows integer Optional. If empty, default value '8760'

Examples

Response

csv / excel file will be downloaded

Order Placement APIs

New Order

If you wish orders to be automatically cancelled when your session ends, see the require heartbeat section, or manually send the cancel all session orders message.

import requests
import json
import base64
import hmac
import hashlib
import time

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

gemini_api_key = "mykey"
gemini_api_secret = "1234abcd".encode()

payload_nonce = time.time()

payload = {
   "request": "/v1/order/new",
    "nonce": payload_nonce,
    "symbol": "btcusd",
    "amount": "5",
    "price": "3633.00",
    "side": "buy",
    "type": "exchange limit",
    "options": ["maker-or-cancel"] 
}

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_order = response.json()
print(new_order)

Sample limit order payload

{
    "request": "/v1/order/new",
    "nonce": <nonce>,
    "client_order_id": <client_order_id>,
    "symbol": "btcusd",
    "amount": "5",
    "price": "3633.00",
    "side": "buy",
    "type": "exchange limit"
}

JSON limit order response

{
    "order_id": "106817811", 
    "id": "106817811", 
    "symbol": "btcusd", 
    "exchange": "gemini", 
    "avg_execution_price": "3632.8508430064554",
    "side": "buy", 
    "type": "exchange limit", 
    "timestamp": "1547220404", 
    "timestampms": 1547220404836, 
    "is_live": True, 
    "is_cancelled": False, 
    "is_hidden": False, 
    "was_forced": False,
    "executed_amount": "3.7567928949",
    "remaining_amount": "1.2432071051",
    "client_order_id": "20190110-4738721",
    "options": [],
    "price": "3633.00", 
    "original_amount": "5"
}

Sample Stop-Limit order payload

{
    "amount": ".1",
    "client_order_id": "470135",
    "price": "10500",
    "nonce": <nonce>,
    "side": "Buy",
    "request": "/v1/order/new",
    "stop_price": "10000",
    "symbol": "btcusd",
    "type": "exchange stop limit"
}

JSON Stop-Limit order response

{
    "order_id": "7419662",
    "id": "7419662",
    "symbol": "btcusd",
    "exchange": "gemini",
    "avg_execution_price": "0.00",
    "side": "buy",
    "type": "stop-limit",
    "timestamp": "1572378649",
    "timestampms": 1572378649018,
    "is_live": True,
    "is_cancelled": False,
    "is_hidden": False,
    "was_forced": False,
    "executed_amount": "0",
    "options": [],
    "stop_price": "10400.00",
    "price": "10500.00",
    "original_amount": "0.01"
}

Roles

The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information.

The OAuth scope must have orders:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

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

Parameters

Parameter Type Description
request string The literal string "/v1/order/new"
nonce integer or timestamp The nonce, as described in Private API Invocation
client_order_id string Recommended. A client-specified order id
symbol string The symbol for the new order
amount string Quoted decimal amount to purchase
price string Quoted decimal amount to spend per unit
side string "buy" or "sell"
type string The order type. "exchange limit" for all order types except for stop-limit orders. "exchange stop limit" for stop-limit orders.
options array Optional. An optional array containing at most one supported order execution option. See Order execution options for details.
stop_price string Optional. The price to trigger a stop-limit order. Only available for stop-limit orders.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to place the order. Only available for exchange accounts.

Stop-Limit Orders

A Stop-Limit order is an order type that allows for order placement when a price reaches a specified level. Stop-Limit orders take in both a price and and a stop_price as parameters. The stop_price is the price that triggers the order to be placed on the continous live order book at the price. For buy orders, the stop_price must be below the price while sell orders require the stop_price to be greater than the price.

What about market orders?

The API doesn't directly support market orders because they provide you with no price protection.

Instead, use the “immediate-or-cancel” order execution option, coupled with an aggressive limit price (i.e. very high for a buy order or very low for a sell order), to achieve the same result.

Order execution options

Note that options is an array. If you omit options or provide an empty array, your order will be a standard limit order - it will immediately fill against any open orders at an equal or better price, then the remainder of the order will be posted to the order book.

If you specify more than one option (or an unsupported option) in the options array, the exchange will reject your order.

No options can be applied to stop-limit orders at this time.

The available limit order options are:

Option Description
"maker-or-cancel" This order will only add liquidity to the order book.

If any part of the order could be filled immediately, the whole order will instead be canceled before any execution occurs.

If that happens, the response back from the API will indicate that the order has already been canceled ("is_cancelled": true in JSON).

Note: some other exchanges call this option "post-only".
"immediate-or-cancel" This order will only remove liquidity from the order book.

It will fill whatever part of the order it can immediately, then cancel any remaining amount so that no part of the order is added to the order book.

If the order doesn't fully fill immediately, the response back from the API will indicate that the order has already been canceled ("is_cancelled": true in JSON).
"fill-or-kill" This order will only remove liquidity from the order book.

It will fill the entire order immediately or cancel.

If the order doesn't fully fill immediately, the response back from the API will indicate that the order has already been canceled ("is_cancelled": true in JSON).

Response

Response will be the fields included in Order Status

Cancel Order

This will cancel an order. If the order is already canceled, the message will succeed but have no effect.

Sample payload

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

Upon a successful call, the response will be as follows. Note the *is_cancelled** node will have a value of 'true'

{
    "order_id":"106817811",
    "id":"106817811",
    "symbol":"btcusd",
    "exchange":"gemini",
    "avg_execution_price":"3632.85101103",
    "side":"buy",
    "type":"exchange limit",
    "timestamp":"1547220404",
    "timestampms":1547220404836,
    "is_live":False,
    "is_cancelled":True,
    "is_hidden":False,
    "was_forced":False,
    "executed_amount":"3.7610296649",
    "remaining_amount":"1.2389703351",
    "reason":"Requested",
    "options":[],
    "price":"3633.00",
    "original_amount":"5"
}

Roles

The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information.

The OAuth scope must have orders:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

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

Parameters

Parameter Type Description
request string The literal string "/v1/order/cancel"
nonce integer or timestamp The nonce, as described in Private API Invocation
order_id integer The order ID given by /order/new.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to cancel the order. Only available for exchange accounts.

Response

Response will be the fields included in Order Status. If the order was already canceled, then the request will have no effect and the status will be returned.

All Cancellation Reasons

Under unique circumstances, orders may be automatically cancelled by the exchange. These scenarios are detailed in the table below:

Cancel Reason Description
MakerOrCancelWouldTake Occurs when the "maker-or-cancel" execution option is included in the order request and any part of the requested order could be filled immediately.
ExceedsPriceLimits Occurs when there is not sufficient liquidity on the order book to support the entered trade. Orders will be automatically cancelled when liquidity conditions are such that the order would move price +/- 5%.
SelfCrossPrevented Occurs when a user enters a bid that is higher than that user's lowest open ask or enters an ask that is lower than their highest open bid on the same pair.
ImmediateOrCancelWouldPost Occurs when the "immediate-or-cancel" execution option is included in the order request and the requested order cannot be fully filled immediately. This type of cancellation will only cancel the unfulfilled part of any impacted order.
FillOrKillWouldNotFill Occurs when the "fill-or-kill" execution option is included in the new order request and the entire order cannot be filled immediately.

Unlike "immediate-or-cancel" orders, this execution option will result in the entire order being cancelled rather than just the unfulfilled portion.
Requested Cancelled via user request to /v1/order/cancel endpoint.
MarketClosed Occurs when an order is placed for a trading pair that is currently closed.
TradingClosed Occurs when an order is placed while the exchange is closed for trading.

Wrap Order

This endpoint wraps and unwraps Gemini issued assets.

Sample payload

{
    "request": "/v1/wrap/GUSDUSD",
    "nonce": <nonce>,
    "account": "alice",
    "amount": "1",
    "side": "buy",
    "client_order_id":"4ac6f45f-baf1-40f8-83c5-001e3ea73c7f"

}

Sample response

{
    "orderId": 429135395, 
    "pair": "GUSDUSD", 
    "price": "1", 
    "priceCurrency": "USD", 
    "side": "buy", 
    "quantity": "1", 
    "quantityCurrency": "GUSD", 
    "totalSpend": "1", 
    "totalSpendCurrency": "USD", 
    "fee": "0", 
    "feeCurrency": "USD", 
    "depositFee": "0", 
    "depositFeeCurrency": "USD"
}

Roles

The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information.

The OAuth scope must have orders:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/wrap/:symbol

Parameters

Parameter Type Description
request string The literal string "/v1/wrap/:symbol"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to place the order. Only available for exchange accounts.
amount string Amount to be wrapped/unwrapped depending on direction
side string "buy" or "sell"
client_order_id string Recommended. A client-specified order id

Response

Field Type Description
orderId string The order id
pair string Trading pair symbol. See symbols and minimums
price string The current price of the pair on the order
priceCurrency string The currency in which the order is priced. Matches CCY2 in the symbol
side string Either "buy" or "sell"
quantity string The amount that was executed
quantityCurrency string The currency label for the quantity field. Matches CCY1 in the symbol
totalSpend string Total quantity to spend for the order. Will be the sum inclusive of all fees and amount to be traded.
totalSpendCurrency string Currency of the totalSpend to be spent on the order
fee string The amount charged
feeCurrency string Currency that the fee was paid in
depositFee string The deposit fee quantity. Will be applied if a debit card is used for the order. Will return 0 if there is no depositFee
depositFeeCurrency string Currency in which depositFee is taken

Cancel All Session Orders

This will cancel all orders opened by this session.

This will have the same effect as heartbeat expiration if "Require Heartbeat" is selected for the session.

Sample payload

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

Roles

The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information.

The OAuth scope must have orders:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/order/cancel/session

Parameters

Parameter Type Description
request string The literal string "/v1/order/cancel/session"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to cancel the orders. Only available for exchange accounts.

Response

JSON response

{
    "result":"ok",
    "details":
        {
            "cancelledOrders":[330429345],
            "cancelRejects":[]
        }
}
Field Type Description
result string ok
details node (nested) cancelledOrders/cancelRejects with IDs of both

Cancel All Active Orders

This will cancel all outstanding orders created by all sessions owned by this account, including interactive orders placed through the UI.

Typically Cancel All Session Orders is preferable, so that only orders related to the current connected session are cancelled.

Roles

The API key you use to access this endpoint must have the Trader role assigned. See Roles for more information.

The OAuth scope must have orders:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/order/cancel/all

Sample payload

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

Parameters

Parameter Type Description
request string The literal string "/v1/order/cancel/all"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to cancel the orders. Only available for exchange accounts.

Response

JSON response

{
    "result": "ok",
    "details": {
        "cancelRejects": [],
        "cancelledOrders": [
            330429106,
            330429079,
            330429082
        ]
    }
}
Field Type Description
result string ok
details node (nested) cancelledOrders/cancelRejects with IDs of both

Order Status APIs

Order Status

Sample payload

{
    "request": "/v1/order/status",
    "nonce": <nonce>,
    "order_id": 123456789012345,
    "include_trades": True
}

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

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

Parameters

Parameter Type Description
request string The literal string "/v1/order/status"
nonce integer or timestamp The nonce, as described in Private API Invocation
order_id integer The order id to get information on. The order_id represents a whole number and is transmitted as an unsigned 64-bit integer in JSON format. An unsigned 64-bit integer is a non-negative whole number with a maximum value of 18,446,744,073,709,551,615. order_id cannot be used in combination with client_order_id.
client_order_id string Optional. The client_order_id used when placing the order. client_order_id cannot be used in combination with order_id
include_trades boolean Optional. Either True or False. If True the endpoint will return individual trade details of all fills from the order.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the order was placed. Only available for exchange accounts.

Response

The response will be an object when using order_id in the payload of the request, and an array when using client_order_id.

JSON reponse for limit buy

{
  "order_id" : "123456789012345",
  "id" : "123456789012345",
  "symbol" : "btcusd",
  "exchange" : "gemini",
  "avg_execution_price" : "400.00",
  "side" : "buy",
  "type" : "exchange limit",
  "timestamp" : "1494870642",
  "timestampms" : 1494870642156,
  "is_live" : False,
  "is_cancelled" : False,
  "is_hidden" : False,
  "was_forced" : False,
  "executed_amount" : "3",
  "remaining_amount" : "0",
  "options" : [],
  "price" : "400.00",
  "original_amount" : "3"
}

JSON response for market buy with include_trades as True

{
  "avg_execution_price": "22728.94",
  "exchange": "gemini",
  "executed_amount": "0.0219983861",
  "id": "17379712927",
  "is_cancelled": false,
  "is_hidden": false,
  "is_live": false,
  "options": [],
  "order_id": "17379712927",
  "remaining_amount": "0",
  "side": "buy",
  "symbol": "btcusd",
  "timestamp": "1608229172",
  "timestampms": 1608229172627,
  "trades": [
    {
      "aggressor": true,
      "amount": "0.0219983861",
      "exchange": "gemini",
      "fee_amount": "0.00",
      "fee_currency": "USD",
      "order_id": "17379712927",
      "price": "22728.94",
      "tid": 17379712930,
      "timestamp": 1608229172,
      "timestampms": 1608229172627,
      "type": "Buy"
    }
  ],
  "type": "market buy",
  "was_forced": false
}
Field Type Description
order_id string The order id
client_order_id string An optional client-specified order id
symbol string The symbol of the order
exchange string Will always be "gemini"
price decimal The price the order was issued at
avg_execution_price decimal The average price at which this order as been executed so far. 0 if the order has not been executed at all.
side string Either "buy" or "sell".
type string Description of the order:
  • exchange limit
  • market buy
  • market sell
options string An array containing at most one supported order execution option. See Order execution options for details.
timestamp timestamp The timestamp the order was submitted. Note that for compatibility reasons, this is returned as a string. We recommend using the timestampms field instead.
timestampms timestampms The timestamp the order was submitted in milliseconds.
is_live boolean true if the order is active on the book (has remaining quantity and has not been canceled)
is_cancelled boolean true if the order has been canceled. Note the spelling, "cancelled" instead of "canceled". This is for compatibility reasons.
reason string Populated with the reason your order was canceled, if available.
was_forced boolean Will always be false.
executed_amount decimal The amount of the order that has been filled.
remaining_amount decimal The amount of the order that has not been filled.
original_amount decimal The originally submitted amount of the order.
is_hidden boolean Will always return false.
trades array Optional. Contains an array of JSON objects with trade details.
-- -- price decimal The price that the execution happened at
-- -- amount decimal The quantity that was executed
-- -- timestamp timestamp The time that the trade happened in epoch seconds
-- -- timestampms timestampms The time that the trade happened in milliseconds
-- -- type string Will be either "Buy" or "Sell", indicating the side of the original order
-- -- aggressor boolean If true, this order was the taker in the trade
-- -- fee_currency string Currency that the fee was paid in
-- -- fee_amount decimal The amount charged
-- -- tid integer Unique identifier for the trade
-- -- order_id string The order that this trade executed against
-- -- exchange string Will always be "gemini"
-- -- break string Optional. Will only be present if the trade is broken. See Break Types below for more information.

Get Active Orders

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/orders

Sample payload

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

Parameters

This takes no parameters other than the general ones

Parameter Type Description
request string The literal string "/v1/orders"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the orders were placed. Only available for exchange accounts.

Response

JSON response

[   {
    "order_id": "107421210",
    "id": "107421210",
    "symbol": "ethusd",
    "exchange": "gemini",
    "avg_execution_price": "0.00",
    "side": "sell",
    "type": "exchange limit",
    "timestamp": "1547241628",
    "timestampms": 1547241628042,
    "is_live": True,
    "is_cancelled": False,
    "is_hidden": False,
    "was_forced": False,
    "executed_amount": "0",
    "remaining_amount": "1",
    "options": [],
    "price": "125.51",
    "original_amount": "1"
  },
  {
    "order_id": "107421205",
    "id": "107421205",
    "symbol": "ethusd",
    "exchange": "gemini",
    "avg_execution_price": "125.41",
    "side": "buy",
    "type": "exchange limit",
    "timestamp": "1547241626",
    "timestampms": 1547241626991,
    "is_live": True,
    "is_cancelled": False,
    "is_hidden": False,
    "was_forced": False,
    "executed_amount": "0.029147",
    "remaining_amount": "0.970853",
    "options": [],
    "price": "125.42",
    "original_amount": "1"
  } ]

An array of the results of /order/status for all your live orders.

Get Past Trades

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/mytrades

Sample payload

{
    "nonce": <nonce>,
    "request": "/v1/mytrades",
    "symbol": "btcusd"
}

Parameters

Parameter Type Description
request string The literal string "/v1/mytrades"
nonce integer or timestamp The nonce, as described in Private API Invocation
symbol string Optional. The symbol to retrieve trades for
limit_trades integer Optional. The maximum number of trades to return. Default is 50, max is 500.
timestamp timestamp Optional. Only return trades on or after this timestamp. See Data Types: Timestamps for more information. If not present, will show the most recent orders.
account string Optional. Required for Master API keys as described in Private API Invocation. Specifies the account on which the orders were placed. Only available for exchange accounts.

Response

JSON reponse

[ {
    "price": "3648.09",
    "amount": "0.0027343246",
    "timestamp": 1547232911,
    "timestampms": 1547232911021,
    "type": "Buy",
    "aggressor": True,
    "fee_currency": "USD",
    "fee_amount": "0.024937655575035",
    "tid": 107317526,
    "order_id": "107317524",
    "exchange": "gemini",
    "is_clearing_fill": False,
    "symbol": "BTCUSD"
  }, {
    "price": "3633.00",
    "amount": "0.00423677",
    "timestamp": 1547220640,
    "timestampms": 1547220640195,
    "type": "Buy",
    "aggressor": False,
    "fee_currency": "USD",
    "fee_amount": "0.038480463525",
    "tid": 106921823,
    "order_id": "106817811",
    "exchange": "gemini",
    "is_clearing_fill": False,
    "symbol": "BTCUSD"
} ]

The response will be an array of trade information items.

Field Type Description
price decimal The price that the execution happened at
amount decimal The quantity that was executed
timestamp timestamp The time that the trade happened in epoch seconds
timestampms timestampms The time that the trade happened in milliseconds
type string Will be either "Buy" or "Sell", indicating the side of the original order
aggressor boolean If true, this order was the taker in the trade
fee_currency string Currency that the fee was paid in
fee_amount decimal The amount charged
tid integer Unique identifier for the trade
order_id string The order that this trade executed against
client_order_id string The optional client-specified order id that this trade is associated with
exchange string Will always be "gemini"
is_clearing_fill boolean True if the trade was a clearing trade and not an on-exchange trade
symbol string The symbol that the trade was for
break string Optional. Will only be present if the trade is broken. See Break Types below for more information.

How to retrieve your trade history

To retrieve your full trade history walking backwards,

  1. Initial request: POST to https://api.gemini.com/v1/mytrades with a JSON payload including a timestamp key with value 0 and a limit_trades key with value 500
  2. When you receive the list of trades, it will be sorted by timestamp descending - so the first element in the list will have the highest timestamp value. For this example, say that value is X.
  3. Create a second POST request with a JSON payload including a timestamp key with value X+1 and a limit_trades key with value 500.
  4. Take the first element of the list returned with highest timestamp value Y and create a third POST request with a JSON payload including a timestamp key with value Y+1 and a limit_trades key with value 500.
  5. Continue creating POST requests and retrieving trades until an empty list is returned.

Break Types

In the rare event that a trade has been reversed (broken), the trade that is broken will have this flag set. The field will contain one of these values

Value Description
manual The trade was reversed manually. This means that all fees, proceeds, and debits associated with the trade have been credited or debited to the account seperately. That means that this reported trade must be included for order for the account balance to be correct.
full The trade was fully broken. The reported trade should not be accounted for. It will be as though the transfer of fund associated with the trade had simply not happened.

Get Orders History

This API retrieves (closed) orders history for an account.

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/orders/history

Sample payload json { "request": "/v1/orders/history", "nonce": <nonce>, "timestamp": <timestamp>, "limit_orders":<limitorders>, "symbol":"btcusd" }

Parameters

Parameter Type Description
request string The string /v1/orders/history
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.
timestamp timestamp Optional. In iso datetime with timezone format from that date you will get order history
limit_orders integer Optional. The maximum number of orders to return. Default is 50, max is 500.
symbol string Optional. The symbol to retrieve orders for

Response

JSON response

[
    {
      "order_id": "73751560172006688",
      "id": "73751560172006688",
      "symbol": "ethgusd",
      "exchange": "gemini",
      "avg_execution_price": "0.00",
      "side": "buy",
      "type": "exchange limit",
      "timestamp": "1695629298",
      "timestampms": 1695629298505,
      "is_live": false,
      "is_cancelled": true,
      "is_hidden": false,
      "was_forced": false,
      "executed_amount": "0",
      "client_order_id": "fb5321b0-2114-47fd-8cca-531a66d7feaf",
      "options": [],
      "price": "420.00",
      "original_amount": "0.69",
      "remaining_amount": "0.69",
      "trades": []
    }
]
Field Type Description
order_id string The order id
symbol string The symbol of the order
exchange string Will always be "gemini"
avg_execution_price decimal The average price at which this order as been executed so far. 0 if the order has not been executed at all.
side string Either "buy" or "sell".
type string Description of the order:
  • exchange limit
  • market buy
  • market sell
timestamp timestamp The timestamp the order was submitted. Note that for compatibility reasons, this is returned as a string. We recommend using the timestampms field instead.
timestampms timestampms The timestamp the order was submitted in milliseconds.
is_live boolean true if the order is active on the book (has remaining quantity and has not been canceled)
is_cancelled boolean true if the order has been canceled. Note the spelling, "cancelled" instead of "canceled". This is for compatibility reasons.
is_hidden boolean Will always return false.
was_forced boolean Will always be false.
executed_amount decimal The amount of the order that has been filled.
client_order_id string An optional client-specified order id
options string An array containing at most one supported order execution option. See Order execution options for details.
price decimal The price the order was issued at
original_amount decimal The originally submitted amount of the order.
remaining_amount decimal The amount of the order that has not been filled.
trades array Optional. Contains an array of JSON objects with trade details.
-- -- price decimal The price that the execution happened at
-- -- amount decimal The quantity that was executed
-- -- timestamp timestamp The time that the trade happened in epoch seconds
-- -- timestampms timestampms The time that the trade happened in milliseconds
-- -- type string Will be either "Buy" or "Sell", indicating the side of the original order
-- -- aggressor boolean If true, this order was the taker in the trade
-- -- fee_currency string Currency that the fee was paid in
-- -- fee_amount decimal The amount charged
-- -- tid integer Unique identifier for the trade
-- -- order_id string The order that this trade executed against
-- -- exchange string Will always be "gemini"
-- -- break string Optional. Will only be present if the trade is broken. See Break Types below for more information.

How to retrieve your order history

To retrieve your full order history walking backwards,

  1. Initial request: POST to https://api.gemini.com/v1/orders/history with a JSON payload including a timestamp key with value 0 and a limit_orders key with value 500
  2. When you receive the list of orders, it will be sorted by timestamp descending - so the first element in the list will have the highest timestamp value. For this example, say that value is X.
  3. Create a second POST request with a JSON payload including a timestamp key with value X+1 and a limit_orders key with value 500.
  4. Take the first element of the list returned with highest timestamp value Y and create a third POST request with a JSON payload including a timestamp key with value Y+1 and a limit_orders key with value 500.
  5. Continue creating POST requests and retrieving orders until an empty list is returned.

Break Types

In the rare event that a trade has been reversed (broken), the trade that is broken will have this flag set. The field will contain one of these values

Value Description
manual The trade was reversed manually. This means that all fees, proceeds, and debits associated with the trade have been credited or debited to the account seperately. That means that this reported trade must be included for order for the account balance to be correct.
full The trade was fully broken. The reported trade should not be accounted for. It will be as though the transfer of fund associated with the trade had simply not happened.

Fee and Volume APIs

Get Notional Volume

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/notionalvolume

Sample payload

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

Parameters

Parameter Type Description
request string The literal string "/v1/notionalvolume"
nonce integer or timestamp The nonce, as described in Private API Invocation
symbol string Optional. The participating symbol for fee promotions.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the trades were placed. Only available for exchange accounts.

Response

JSON response

{
    "web_maker_fee_bps": 25,
    "web_taker_fee_bps": 35,
    "api_maker_fee_bps": 10,
    "api_taker_fee_bps": 35,
    "fix_maker_fee_bps": 10,
    "fix_taker_fee_bps": 35,
    "notional_30d_volume": 150.00,
    "last_updated_ms": 1551371446000,
    "date": "2019-02-28",
    "notional_1d_volume": [
        {
            "date": "2019-02-22",
            "notional_volume": 75.00
        },
        {
            "date": "2019-02-14",
            "notional_volume": 75.00
        }
    ]
}

The response will be a JSON object representing the volume in price currency that has been traded across all pairs over a period of 30 days.

Field Type Description
date string UTC date in yyyy-MM-dd format
last_updated_ms timestampms Unix timestamp in millisecond of the last update
web_maker_fee_bps basis point Integer value representing the maker fee for all symbols in basis point for web orders
web_taker_fee_bps basis point Integer value representing the taker fee for all symbols in basis point for web orders
api_maker_fee_bps basis point Integer value representing the maker fee for all symbols in basis point for API orders
api_taker_fee_bps basis point Integer value representing the taker fee for all symbols in basis point for API orders
fix_maker_fee_bps basis point Integer value representing the maker fee for all symbols in basis point for FIX orders
fix_taker_fee_bps basis point Integer value representing the taker fee for all symbols in basis point for FIX orders
notional_30d_volume decimal Maker plus taker trading volume for the past 30 days
notional_1d_volume array A list of 1 day notional volume for the past 30 days
notional_1d_volume[n].date string UTC date in yyyy-MM-dd format
notional_1d_volume[n].notional_volume decimal Notional volume value in USD for this single day

Get Trade Volume

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/tradevolume

Sample payload

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

Parameters

Parameter Type Description
request string The literal string "/v1/tradevolume"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the orders were placed. Only available for exchange accounts.

Response

JSON response


[
    [
        {
            "symbol": "btcusd",
            "base_currency": "BTC",
            "notional_currency": "USD",
            "data_date": "2019-01-10",
            "total_volume_base": 8.06021756,
            "maker_buy_sell_ratio": 1,
            "buy_maker_base": 6.06021756,
            "buy_maker_notional": 23461.3515203844,
            "buy_maker_count": 34,
            "sell_maker_base": 0,
            "sell_maker_notional": 0,
            "sell_maker_count": 0,
            "buy_taker_base": 0,
            "buy_taker_notional": 0,
            "buy_taker_count": 0,
            "sell_taker_base": 2,
            "sell_taker_notional": 7935.66,
            "sell_taker_count": 2
        },
        {
            "symbol": "ltcusd",
            "base_currency": "LTC",
            "notional_currency": "USD",
            "data_date": "2019-01-11",
            "total_volume_base": 3,
            "maker_buy_sell_ratio": 0,
            "buy_maker_base": 0,
            "buy_maker_notional": 0,
            "buy_maker_count": 0,
            "sell_maker_base": 0,
            "sell_maker_notional": 0,
            "sell_maker_count": 0,
            "buy_taker_base": 3,
            "buy_taker_notional": 98.22,
            "buy_taker_count": 3,
            "sell_taker_base": 0,
            "sell_taker_notional": 0,
            "sell_taker_count": 0
        }
    ]
]

The response will be an array of up to 30 days of trade volume for each symbol.

Field Type Description
symbol string The symbol
base_currency decimal quantity is denominated in this currency
notional_currency decimal price is denominated as the amount of notional currency per one unit of base currency. Notional values are denominated in this currency
data_date string UTC date in yyyy-MM-dd format
total_volume_base decimal Total trade volume for this day
maker_buy_sell_ratio decimal Maker buy/sell ratio is the proportion of maker base volume on trades where the account was on the buy side versus all maker trades. If there is no maker base volume on the buy side, then this value is 0.
buy_maker_base decimal Quantity for this day where the account was a maker on the buy side of the trade.
buy_maker_notional decimal Notional value for this day where the account was a maker on the buy side of the trade.
buy_maker_count decimal Number of trades for this day where the account was a maker on the buy side of the trade.
sell_maker_base decimal Quantity for this day where the account was a maker on the sell side of the trade.
sell_maker_notional decimal Notional value for this day where the account was a maker on the sell side of the trade.
sell_maker_count decimal Number of trades for this day where the account was a maker on the sell side of the trade.
buy_taker_base decimal Quantity for this day where the account was a taker on the buy side of the trade.
buy_taker_notional decimal Notional value for this day where the account was a taker on the buy side of the trade.
buy_taker_count decimal Number of trades for this day where the account was a taker on the buy side of the trade.
sell_taker_base decimal Quantity for this day where the account was a taker on the sell side of the trade.
sell_taker_notional decimal Notional value for this day where the account was a taker on the sell side of the trade.
sell_taker_count decimal Number of trades for this day where the account was a taker on the sell side of the trade.

FX Rate

We have a growing international institutional customer base. When pulling market data for charting, it can be useful to have access to our FX rate for the relevant currency at that time.

Please note, Gemini does not offer foreign exchange services. This endpoint is for historical reference only and does not provide any guarantee of future exchange rates.

Roles

The API key you use to access this endpoint must have the Auditor role assigned. See Roles for more information.

HTTP Request

GET https://api.gemini.com/v2/fxrate/:symbol/:timestamp

Parameters

Parameter Type Description
symbol string The string :symbol. The currency to check the USD FX rate against. We should have historical FX rates for at least GBP, EUR, CAD, SGD, AUD from BCB. (So valid symbols will be in the format of gbpusd for example)
timestamp timestamp The timestamp to pull the FX rate for. Note that we likely need to round this to the closest timestamp we received an update for from BCB. See Data Types: Timestamps for more information.

Response

JSON response


{
    "fxPair": "AUDUSD", 
    "rate": "0.69", 
    "asOf": 1594651859000, 
    "provider": "bcb", 
    "benchmark": "Spot"

}

Response is a list of objects, with the following fields:

Field Type Description
fxPair string The requested currency pair
rate decimal The fx rate of the non USD currency. USD is the base currency and will always have a value of 1
asOf timestamp The timestamp (in Epoch time format) that the requested fxrate has been retrieved for
provider string The market data provider
benchmark string The market for which the retrieved price applies to

Derivatives APIs

Open Positions

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/positions

Sample payload

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

Parameters

This takes no parameters other than the general ones

Parameter Type Description
request string The literal string "/v1/positions"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the orders were placed. Only available for exchange accounts.

Response

JSON response

[
  {
    "symbol": "btcgusdperp",
    "instrument_type": "perp",
    "quantity": "0.2",
    "notional_value": "4000.036",
    "realised_pnl": "1234.5678",
    "unrealised_pnl": "999.946",
    "average_cost": "15000.45",
    "mark_price": "20000.18"
  }
]
Field Type Description
symbol string The symbol of the order.
instrument_type string The type of instrument. Either "spot" or "perp".
quantity decimal The position size. Value will be negative for shorts.
notional_value decimal The value of position; calculated as (quantity * mark_price). Value will be negative for shorts.
realised_pnl decimal The current P&L that has been realised from the position.
unrealised_pnl decimal Current Mark to Market value of the positions.
average_cost decimal The average price of the current position.
mark_price decimal The current Mark Price for the Asset or the position.

Account Margin

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/margin

Sample payload

{
    "nonce": <nonce>,
    "request": "/v1/margin",
    "symbol": "BTC-GUSD-PERP"
}

Parameters

This takes no parameters other than the general ones

Parameter Type Description
request string The literal string "/v1/margin"
nonce integer or timestamp The nonce, as described in Private API Invocation
symbol string Trading pair symbol. See symbols and minimums
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the orders were placed. Only available for exchange accounts.

Response

JSON response

{
    "margin_assets_value": "9800",
    "initial_margin": "6000",
    "available_margin": "3800",
    "margin_maintenance_limit": "5800",
    "leverage": "12.34567",
    "notional_value": "1300",
    "estimated_liquidation_price": "1300",
    "initial_margin_positions": "3500",
    "reserved_margin": "2500",
    "reserved_margin_buys": "1800",
    "reserved_margin_sells": "700",
    "buying_power": "0.19",
    "selling_power": "0.19"
}
Field Type Description
margin_assets_value decimal The $ equivalent value of all the assets available in the current trading account that can contribute to funding a derivatives position.
initial_margin decimal The $ amount that is being required by the accounts current positions and open orders.
available_margin decimal The difference between the margin_assets_value and initial_margin.
margin_maintenance_limit decimal The minimum amount of margin_assets_value required before the account is moved to liquidation status.
leverage decimal The ratio of Notional Value to Margin Assets Value.
notional_value decimal The $ value of the current position.
estimated_liquidation_price decimal The estimated price for the asset at which liquidation would occur.
initial_margin_positions decimal The contribution to initial_margin from open positions.
reserved_margin decimal The contribution to initial_margin from open orders.
reserved_margin_buys decimal The contribution to initial_margin from open BUY orders.
reserved_margin_sells decimal The contribution to initial_margin from open SELL orders.
buying_power decimal The amount of that product the account could purchase based on current initial_margin and margin_assets_value.
selling_power decimal The amount of that product the account could sell based on current initial_margin and margin_assets_value.

Risk Stats

Roles

HTTP Request

curl "https://api.gemini.com/v1/riskstats/BTCGUSDPERP"

import requests, json

base_url = "https://api.gemini.com/v1/"
riskstat_symbol = "riskstats/BTCGUSDPERP"

response = requests.get(base_url + riskstat_symbol)
risk_stat = response.json()

print(risk_stat)

This end point retrieves the risk stats for the symbol.

Parameters

This takes no parameters other than the general ones

Parameter Type Description
symbol string Trading pair symbol. See symbols and minimums

Response

The response will be an json object

Field Type Description
product_type string Contract type for which the symbol data is fetched
mark_price string current mark price at the time of request
index_price string current index price at the time of request
open_interest string string representation of decimal value of open interest
open_interest_notional string string representation of decimal value of open interest notional 
{
    "product_type":"PerpetualSwapContract",
    "mark_price":"30080.00",
    "index_price":"30079.046",
    "open_interest":"14.439",
    "open_interest_notional":"434325.12"
}

Funding Payment

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/perpetuals/fundingPayment?since=<since>&to=<to>

Sample payload

{
  "nonce": <nonce>,
  "request": "/v1/perpetuals/fundingPayment"
}

Parameters

This takes no parameters other than the general ones

Parameter Type Description
since integer or timestamp Optional and if specified only return funding payments after this point. Default value is 24h in past
to integer or timestamp Optional and if specified only returns funding payment until this point. Default value is now
request string The literal string "/v1/perpetuals/fundingPayment"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the orders were placed. Only available for exchange accounts.

Response

JSON response

[
  {
    'eventType': 'Hourly Funding Transfer',
    'hourlyFundingTransfer': {
      'eventType': 'Hourly Funding Transfer',
      'timestamp': 1683730803940,
      'assetCode': 'GUSD',
      'action': 'Debit',
      'quantity': {
        'currency': 'GUSD',
        'value': '4.78958'
      }
    }
  },
  {
    'eventType': 'Hourly Funding Transfer',
    'hourlyFundingTransfer': {
      'eventType': 'Hourly Funding Transfer',
      'timestamp': 1683734406746,
      'assetCode': 'GUSD',
      'action': 'Debit',
      'quantity': {
        'currency': 'GUSD',
        'value': '4.78958'
      },
      'instrumentSymbol': 'BTCGUSDPERP'
    }
  }
]
Field Type Description
eventType string Event type
timestamp timestamps Time of the funding payment
assetCode string Asset symbol
action string Credit or Debit
quantity JSON object A nested JSON object describing the transaction amount
instrumentSymbol string Symbol of the underlying instrument (Note that this is only attached to requests from 16th April 2024 onwards.)

Funding Payment Report File

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

GET https://api.gemini.com/v1/perpetuals/fundingpaymentreport/records.xlsx?fromDate=<date>&toDate=<date>&numRows=<rows>

Sample Request Header. More info: Private API Invocation

{
  'Content-Type': "text/plain",
  'Content-Length': "0",
  'X-GEMINI-APIKEY': <Private API Invocation>
  'X-GEMINI-PAYLOAD': <Private API Invocation>,
  'X-GEMINI-SIGNATURE': <Private API Invocation>,
  'Cache-Control': "no-cache"
}

Sample Request Payload

{
  "nonce": <nonce>,
  "request": "/v1/perpetuals/fundingpaymentreport/records.xlsx?symbol=BTCGUSDPERP&fromDate=2024-04-10&toDate=2024-04-25&numRows=1000"
}

Query Parameters

Parameter Type Description
fromDate integer Optional. If empty, will only fetch records by numRows value
toDate string Optional. If empty, will only fetch records by numRows value
numRows integer Optional. If empty, default value '8760'

Examples

Response

csv / excel file will be downloaded

Funding Payment Report Json

Roles

The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.

The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

GET https://api.gemini.com/v1/perpetuals/fundingpaymentreport/records.json?fromDate=<date>&toDate=<date>&numRows=<rows>

Sample Request Header. More info: Private API Invocation

{
  'Content-Type': "text/plain",
  'Content-Length': "0",
  'X-GEMINI-APIKEY': <Private API Invocation>
  'X-GEMINI-PAYLOAD': <Private API Invocation>,
  'X-GEMINI-SIGNATURE': <Private API Invocation>,
  'Cache-Control': "no-cache"
}

Sample Request Payload

{
  "nonce": <nonce>,
  "request": "/v1/perpetuals/fundingpaymentreport/records.xlsx?symbol=BTCGUSDPERP&fromDate=2024-04-10&toDate=2024-04-25&numRows=1000"
}

Query Parameters

Parameter Type Description
fromDate integer Optional. If empty, will only fetch records by numRows value
toDate string Optional. If empty, will only fetch records by numRows value
numRows integer Optional. If empty, default value '8760'

Examples

Response

Sample Response Json

[
  {
    "eventType": "Hourly Funding Transfer",
    "timestamp": 1713344403617,
    "assetCode": "GUSD",
    "action": "Credit",
    "quantity": {
          "currency": "GUSD",
          "value": "35.81084"
    },
    "instrumentSymbol": "BTCGUSDPERP"
  }
Field Type Description
eventType string Event type
timestamp timestamps Time of the funding payment
assetCode string Asset symbol
action string Credit or Debit
quantity JSON object A nested JSON object describing the transaction amount
instrumentSymbol string Symbol of the underlying instrument (Note that this is only attached to requests from 16th April 2024 onwards.)

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 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.

The OAuth scope must have clearing:create assigned to access /v1/clearing/new, /v1/clearing/cancel and /v1/clearing/confirm. The OAuth scope must have clearing:read to access /v1/clearing/status. See OAuth Scopes for more information.

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 or timestamp 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
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"
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which to place the order. Only available for exchange accounts.

New Clearing Order example

import requests
import json
import base64
import hmac
import hashlib
import 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"
payload_nonce = time.time()

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 or timestamp 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.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the broker account on which to place the order. Only available for exchange accounts.

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 status payload

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

Parameters

Parameter Type Description
request string The literal string "/v1/clearing/status"
nonce integer or timestamp 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.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which the clearing order was placed. Only available for exchange accounts.

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 given 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 or timestamp 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.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which to cancel the clearing order. Only available for exchange accounts.

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

HTTP Request

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 or timestamp 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
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account that was sent and is confirming the clearing order. Only available for exchange accounts.

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

Clearing Order List

HTTP Request

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

Sample clearing list payload

{
    "request": "/v1/clearing/list",
    "nonce": <nonce>,
    "symbol": "BTCEUR",
    "counterparty": "KQ4P3XWE",
    "side": "buy",
    "expiration_start": 1642222800000,
    "expiration_end": 1642309200000,
    "submission_start": 1641790800000,
    "submission_end": 1641791100000,
    "funded": false
}

Parameters

Parameter Type Description
request string The literal string "/v1/clearing/list"
nonce integer or timestamp The nonce, as described in Private API Invocation
symbol string Optional. Trading pair
counterparty string Optional. counterparty_id or counterparty_alias
side string "buy" or "sell"
expiration_start timestamp Optional. UTC timestamp. Requires expiration_end if set
expiration_end timestamp Optional. UTC timestamp. Requires expiration_start if set
submission_start timestamp Optional. UTC timestamp. Requires submission_end if set
submission_end timestamp Optional. UTC timestamp. Requires submission_start if set
funded boolean Optional. Default value false if not set
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Only available for exchange accounts.

JSON response - successful list

{
    "result": "success",
    "orders": [
    {
        "clearing_id": "9LVQE9X5",
        "counterparty_id": "YZ43LX81",
        "symbol": "BTCEUR",
        "side": "sell",
        "price": 2,
        "quantity": 10,
        "status": "AwaitTargetConfirm",
        "submission": 1641790800020,
        "expiration": 1641963600000
    }, {
        "clearing_id": "2MYR07XP",
        "order_id": "trade1SrcOrderId",
        "counterparty_id": "KQ4P3XWE",
        "broker_id": "WV4V1DGN",
        "symbol": "BTCEUR",
        "side": "buy",
        "price": 1,
        "quantity": 50,
        "status": "AwaitSourceConfirm",
        "submission": 1641790800016,
        "expiration": 1642222800000
    }, {
        "clearing_id": "EM8WO7LQ",
        "order_id": "trade4SrcOrderId",
        "broker_id": "WV4V1DGN",
        "symbol": "BTCEUR",
        "side": "buy",
        "price": 4,
        "quantity": 8,
        "status": "AwaitSourceTargetConfirm",
        "submission": 1641790800028,
        "expiration": 1642136400000
    }
  ]
}

Response

The response will be an object containing clearing list

Field Type Description
result string A description of the status of the clearing list. This reponse will return the string "success" upon success, or "failed" upon failure.
orders array Array of JSON objects with clearing details
-- -- clearing_id string A unique identifier for the clearing order. Always set.
-- -- order_id string Optional. Only provided if order was submitted with it.
-- -- counterparty_id string Optional. A symbol that corresponds with a counterparty to which you completed the trade with.
-- -- counterparty_alias string Optional. Counterparty alias
-- -- broker_id string Optional. A symbol that corresponds with a broker id.
-- -- symbol string Trading pair. Always set.
-- -- side string "buy" or "sell". Always set.
-- -- price decimal The price the clearing order was executed at
-- -- quantity decimal The amount that was executed
-- -- status string A description of the status of the order given in the clearing_id field. See order status descriptions for more information
-- -- submission timestamp UTC timestamp. Always set.
-- -- expiration timestamp UTC timestamp. Always set.

Clearing Broker List

HTTP Request

POST https://api.gemini.com/v1/clearing/broker/list

Sample clearing broker list payload

{
    "request": "/v1/clearing/broker/list",
    "nonce": <nonce>,
    "symbol": "BTCEUR",
    "expiration_start": 1642222800000,
    "expiration_end": 1642309200000,
    "submission_start": 1641790800000,
    "submission_end": 1641791100000,
    "funded": false
}

Parameters

Parameter Type Description
request string The literal string "/v1/clearing/broker/list"
nonce integer or timestamp The nonce, as described in Private API Invocation
symbol string Optional. Trading pair
expiration_start timestamp Optional. UTC timestamp. Requires expiration_end if set
expiration_end timestamp Optional. UTC timestamp. Requires expiration_start if set
submission_start timestamp Optional. UTC timestamp. Requires submission_end if set
submission_end timestamp Optional. UTC timestamp. Requires submission_start if set
funded boolean Optional. Default value false if not set
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Only available for exchange accounts.

JSON response - successful broker list

{
    "result": "success",
    "orders": [
    {
        "clearing_id": "9LVQ98X5",
        "source_counterparty_id": "R54L3DG1",
        "source_order_id": "trade1SrcOrderId",
        "target_counterparty_id": "KQ4P3XWE",
        "target_order_id": "trade1TgtOrderId",
        "symbol": "BTCEUR",
        "source_side": "buy",
        "price": 1,
        "quantity": 50,
        "status": "AwaitSourceConfirm",
        "submission": 1641790800016,
        "expiration": 1642222800000
    }, {
        "clearing_id": "VXQ341X4",
        "source_counterparty_id": "R54L3DG1",
        "source_order_id": "trade4SrcOrderId",
        "symbol": "BTCEUR",
        "source_side": "buy",
        "price": 4,
        "quantity": 8,
        "status": "AwaitSourceTargetConfirm",
        "submission": 1641790800028,
        "expiration": 1642136400000
    }
  ]
}

Response

The response will be an object containing clearing broker list

Field Type Description
result string A description of the status of the clearing broker list. This reponse will return the string "success" upon success, or "failed" upon failure.
orders array Array of JSON objects with clearing broker list details
-- -- clearing_id string A unique identifier for the clearing order. Always set.
-- -- source_counterparty_id string Source counterparty id. Always set.
-- -- source_order_id string Optional. Only provided if order was submitted with it.
-- -- target_counterparty_id string Optional. Only provided if target counterparty was already set.
-- -- target_order_id string Optional. Only provided if target counterparty set this field.
-- -- symbol string Trading pair. Always set.
-- -- source_side string "buy" or "sell". Always set.
-- -- price decimal The price the clearing order was executed at
-- -- quantity decimal The amount that was executed
-- -- status string A description of the status of the order given in the clearing_id field. See order status descriptions for more information
-- -- submission timestamp UTC timestamp. Always set.
-- -- expiration timestamp UTC timestamp. Always set.

Clearing Trades

HTTP Request

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

Sample clearing trades payload

{
    "request": "/v1/clearing/trades",
    "nonce": <nonce>,
    "timestamp_nanos": 1630382206000000000,
    "limit": 50,
}

Parameters

Parameter Type Description
request string The literal string "/v1/clearing/trades"
nonce integer or timestamp The nonce, as described in Private API Invocation
timestamp_nanos timestamp Optional. Only return transfers on or after this timestamp in nanos.
limit integer Optional. The maximum number of transfers to return. The default is 100 and the maximum is 300.
account string Optional. Only required when using a master api-key. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint. Only available for exchange accounts.

JSON response - successful clearing trades

{
  "results": [
    {
      "sourceAccount": "primary",
      "targetAccount": "primary",
      "pair": "BTCUSD",
      "sourceSide": "buy",
      "price": "1",
      "quantity": "1000",
      "clearingId": "41M23L5Q",
      "status": "Settled",
      "expirationTimeMs": 1662567706120,
      "createdMs": 1662481306139,
      "lastUpdatedMs": 1662481561668,
      "hasBroker": false,
      "wasNotified": false
    },
    {
      "sourceAccount": "primary",
      "targetAccount": "primary",
      "pair": "BTCUSD",
      "sourceSide": "buy",
      "price": "12",
      "quantity": "1000",
      "clearingId": "0EMOYLJ5",
      "status": "AwaitTargetConfirm",
      "expirationTimeMs": 1662567728123,
      "createdMs": 1662481328126,
      "lastUpdatedMs": 1662481561415,
      "hasBroker": false,
      "wasNotified": true
    }
  ]
}

Response

The response will be an object containing clearing trades

Field Type Description
sourceAccount string An account that corresponds with the counterparty sourcing the clearing trade.
targetAccount string An account that corresponds with the counterparty where the clearing trade is targeted.
pair string The trading pair of the clearing trade.
sourceSide string "buy" or "sell". Always set.
price string The price the clearing order was executed at.
quantity string The amount that was executed.
clearingId string The clearing ID.
status string A description of the status of the order given in the clearing_id field. See order status descriptions for more information.
expirationTimeMs timestampms The time that the clearing trade expires.
createdMs timestampms The time that the clearing trade was created.
lastUpdatedMs timestampms The last time the clearing trade was updated.
hasBroker boolean Broker trade.
wasNotified boolean Broker was notified.

Fund Management APIs

Get Available Balances

This will show the available balances in the supported currencies

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

The OAuth scope must have balances:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/balances

Sample payload

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

Parameters

No fields are expected in the request, other than the request name and the nonce

Parameter Type Description
request string The literal string "/v1/balances"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

Response

An array of elements, with one block per currency

JSON response

[
    {
        "type": "exchange",
        "currency": "BTC",
        "amount": "1154.62034001",
        "available": "1129.10517279",
        "availableForWithdrawal": "1129.10517279"
    },
    {
        "type": "exchange",
        "currency": "USD",
        "amount": "18722.79",
        "available": "14481.62",
        "availableForWithdrawal": "14481.62"
    },
    {
        "type": "exchange",
        "currency": "ETH",
        "amount": "20124.50369697",
        "available": "20124.50369697",
        "availableForWithdrawal": "20124.50369697"
    }
]
Field Type Description
currency string Currency code, see symbols
amount decimal The current balance
available decimal The amount that is available to trade
availableForWithdrawal decimal The amount that is available to withdraw
type string "exchange"

Get Notional Balances

This will show the available balances in the supported currencies as well as the notional value in the currency specified.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

The OAuth scope must have balances:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/notionalbalances/:currency

Sample payload

{
    "nonce": <nonce>,
    "request": "/v1/notionalbalances/usd"
}

Parameters

Parameter Type Description
request string The literal string "/v1/notionalbalances/:currency" where :currency is a supported three-letter fiat currency code, e.g. usd or gbp.
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

Response

An array of elements, with one block per currency

JSON response

[
    {
        "currency": "BTC",
        "amount": "1154.62034001",
        "amountNotional": "10386000.59",
        "available": "1129.10517279",
        "availableNotional": "10161000.71",
        "availableForWithdrawal": "1129.10517279",
        "availableForWithdrawalNotional": "10161000.71"
    },
    {
        "currency": "USD",
        "amount": "18722.79",
        "amountNotional": "18722.79",
        "available": "14481.62",
        "availableNotional": "14481.62",
        "availableForWithdrawal": "14481.62",
        "availableForWithdrawalNotional": "14481.62"
    },
    {
        "currency": "ETH",
        "amount": "20124.50369697",
        "amountNotional": "100621.31",
        "available": "20124.50369697",
        "availableNotional": "100621.31",
        "availableForWithdrawal": "20124.50369697",
        "availableForWithdrawalNotional": "100621.31"
    }
]
Field Type Description
currency string Currency code, see symbols
amount decimal The current balance
amountNotional decimal Amount, in notional
available decimal The amount that is available to trade
availableNotional decimal Available, in notional
availableForWithdrawal decimal The amount that is available to withdraw
availableForWithdrawalNotional decimal AvailableForWithdrawal, in notional

Transfers

This endpoint shows deposits and withdrawals in the supported currencies. When deposits show as Advanced or Complete they are available for trading.

This endpoint does not currently show cancelled advances, returned outgoing wires or ACH transactions, or other exceptional transaction circumstances.

Fiat transfers between non-derivative and derivatives accounts are prohibited.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/transfers

Sample payload

{
    "nonce": <nonce>,
    "request": "/v1/transfers",
    "currency": "BTC"
}

Parameters

Parameter Type Description
request string The literal string "/v1/transfers"
nonce integer or timestamp The nonce, as described in Private API Invocation
currency string Optional. Currency code, see symbols
timestamp timestamp Optional. Only return transfers on or after this timestamp. See Data Types: Timestamps for more information. If not present, will show the most recent transfers.
limit_transfers integer Optional. The maximum number of transfers to return. The default is 10 and the maximum is 50.
account string Optional. Only required when using a master api-key. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.
show_completed_deposit_advances boolean Optional. Whether to display completed deposit advances. False by default. Must be set True to activate.

Response

The response will be an array of JSON objects, sorted by timestamp, with the newest transfer events shown first. When including currency in the payload, the response will only include the specified symbol (e.g. btc or doge). Without currency in the payload, the response will include all transfers.

JSON response

[
   {
      "type":"Reward",
      "status":"Advanced",
      "timestampms":1507943543575,
      "eid":320033681,
      "currency":"USD",
      "amount":"125.00",
      "method":"CreditCard"
   },
   {
      "type":"Deposit",
      "status":"Advanced",
      "timestampms":1507913541275,
      "eid":320013281,
      "currency":"USD",
      "amount":"36.00",
      "method":"ACH"
   },
   {
      "type":"Deposit",
      "status":"Advanced",
      "timestampms":1499990797452,
      "eid":309356152,
      "currency":"ETH",
      "amount":"100",
      "txHash":"605c5fa8bf99458d24d61e09941bc443ddc44839d9aaa508b14b296c0c8269b2"
   },
   {
      "type":"Deposit",
      "status":"Complete",
      "timestampms":1495550176562,
      "eid":298112782,
      "currency":"BTC",
      "amount":"1500",
      "txHash":"163eeee4741f8962b748289832dd7f27f754d892f5d23bf3ea6fba6e350d9ce3",
      "outputIdx":0
   },
   {
      "type":"Deposit",
      "status":"Advanced",
      "timestampms":1458862076082,
      "eid":265799530,
      "currency":"USD",
      "amount":"500.00",
      "method":"ACH"
   },
   {
      "type":"Deposit",
      "status":"Complete",
      "timestampms":1608153246319,
      "eid":683262665,
      "currency":"BTC",
      "amount":"125.00",
      "txHash":"27lff0d6c80061da473f500577b95ba324b1efdf926ce1681fe7a16390da104a",
      "outputIdx":0,
      "destination":"az1qlptkvnus8g5k26ulm8ownwt7sknbckp3hl6mol",
      "advanceEid":683248625
   },
   {
      "type":"Deposit",
      "status":"Advanced",
      "timestampms":1608152635765,
      "eid":683248625,
      "currency":"BTC",
      "amount":"125.00",
      "txHash":"27lff0d6c80061da473f500577b95ba324b1efdf926ce1681fe7a16390da104a",
      "outputIdx":0,
      "destination":"az1qlptkvnus8g5k26ulm8ownwt7sknbkcp3hl6mol"
   },
   {
      "type":"Withdrawal",
      "status":"Complete",
      "timestampms":1450403787001,
      "eid":82897811,
      "currency":"BTC",
      "amount":"5",
      "txHash":"c458b86955b80db0718cfcadbff3df3734a906367982c6eb191e61117b810bbb",
      "withdrawalId":"02176a83-a6b1-4202-9b85-1c1c92dd25c4",
      "outputIdx":0,
      "destination":"mqjvCtt4TJfQaC7nUgLMvHwuDPXMTEUGqx"
   },
   {
      "type": "Withdrawal", 
      "status": "Complete", 
      "timestampms": 1535451930431, 
      "eid": 341167014, 
      "currency": "USD", 
      "amount": "1.00", 
      "txHash": "7bffd85893ee8e72e31061a84d25c45f2c4537c2f765a1e79feb06a7294445c3", 
      "destination": "0xd24400ae8BfEBb18cA49Be86258a3C749cf46853" 
   }
]

JSON response

[
   {
      "type":"AdminDebit",
      "status":"Complete",
      "timestampms":1626990636645,
      "eid":1001248356,
      "currency":"BTC",
      "amount":"6",
      "purpose":"Administrative debit"
   },
   {
      "type":"AdminCredit",
      "status":"Complete",
      "timestampms":1626990476421,
      "eid":1001245359,
      "currency":"BTC",
      "amount":"4",
      "purpose":"Fee reimbursement credit"
   },
   {
      "type":"AdminCredit",
      "status":"Complete",
      "timestampms":1626988128372,
      "eid":1001206783,
      "currency":"BTC",
      "amount":"3",
      "purpose":"Administrative credit"
   }
]
Field Type Description
type string Transfer type. Deposit, Withdrawal, or Reward.
status string Transfer status. Advanced or Complete.
timestampms timestampms The time of the transfer in milliseconds
eid integer Transfer event id
advanceEid integer Deposit advance event id
currency string Currency code, see symbols
amount decimal The transfer amount
feeAmount decimal The fee amount charged
feeCurrency string Currency that the fee was paid in
method string Optional. When currency is a fiat currency, the method field will attempt to supply ACH, Wire,SEN, or CreditCard. If the transfer is an internal transfer between subaccounts the method field will return Internal.
txHash string Optional. When currency is a cryptocurrency, supplies the transaction hash when available.
withdrawalId string Optional. When currency is a cryptocurrency and type is Withdrawal, supplies the withdrawalId1.
outputIdx integer Optional. When currency is a cryptocurrency, supplies the output index in the transaction when available.
destination string Optional. When currency is a cryptocurrency, supplies the destination address when available.
purpose string Optional. Administrative field used to supply a reason for certain types of advances.

Transactions

This endpoint shows trade detail and transactions. There is a continuation_token that is a pagination token used for subsequent requests.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned and have the master account scope. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/transactions

Sample payload

{
    "request": "/v1/transactions",
    "nonce": <nonce>,
    "timestamp_nanos": 1630382206000000000,
    "limit": 50,
    "continuation_token": "daccgrp_123421:n712621873886999872349872349:a71289723498273492374978424:m2:iForward"
}

Parameters

Parameter Type Description
nonce integer or timestamp The nonce, as described in Private API Invocation
request string The literal string "/v1/transactions"
timestamp_nanos timestamp Optional. Only return transfers on or after this timestamp in nanos. If this is defined, do not define “continuation_token”.
limit integer Optional. The maximum number of transfers to return. The default is 100 and the maximum is 300.
continuation_token string Optional. For subsequent requests, use the returned continuation_token value for next page. If this is defined, do not define “timestamp_nanos”.

Response

The response will be an array of JSON objects, sorted by trade and transfer as well as a continuationToken to be used in subsequent requests.

JSON response

{
  "results": [
    {
      "account": "primary",
      "amount": "0.001",
      "price": "1730.95",
      "timestampms": 1659201465069,
      "side": "SIDE_TYPE_BUY",
      "isAggressor": true,
      "feeAssetCode": "ETH",
      "feeAmount": "0.000000000000000605",
      "orderId": 73716687406755680,
      "exchange": "Gemini Trust Co",
      "isAuctionFill": false,
      "isClearingFill": false,
      "symbol": "ETHUSD",
      "type": "trade"
    },
    {
      "account": "primary",
      "amount": "0.001",
      "price": "1679.02",
      "timestampms": 1659201465222,
      "side": "SIDE_TYPE_SELL",
      "isAggressor": true,
      "feeAssetCode": "ETH",
      "feeAmount": "0.00000000000000000587",
      "orderId": 73716687406755680,
      "exchange": "Gemini Trust Co",
      "isAuctionFill": false,
      "isClearingFill": false,
      "symbol": "ETHUSD",
      "type": "trade"
    }
  ],
  "continuationToken": "daccgrp_1500611:n7126218738869976937315434496:a7126216029949884380085223424:m2:iForward"
}

Trade Response

Field Type Description
account string The account.
amount string The quantity that was executed.
price string The price that the execution happened at.
timestampms timestampms The time that the trade happened in milliseconds.
side string Indicating the side of the original order.
isAggressor boolean If true, this order was the taker in the trade.
feeAssetCode string The symbol that the trade was for
feeAmount string The fee amount charged
orderId long The order that this trade executed against.
exchange string Will always be "Gemini Trust Co".
isAuctionFill boolean True if the trade was a auction trade and not an on-exchange trade.
isClearingFill boolean True if the trade was a clearing trade and not an on-exchange trade.
symbol string The symbol that the trade was for.

Transfer Response

Field Type Description
timestampms timestampms The time that the trade happened in milliseconds.
source string The account you are transferring from.
destination string The account you are transferring to.
operationReason string The operation reason.
status string The status of the transfer.
eid long Transfer event id.
currency string Currency code, see symbols
amount string The quantity that was transferred.
method string Type of transfer method.
correlationId long Correlation ID.
transferType string Transfer type.
bankId string Optional. Bank ID.
purpose string Optional. Purpose.
transactionHash string Optional. Supplies the transaction hash when available.
transferId string Optional. Transfer ID.
withdrawalId string Optional. Withdrawal ID.
clientTransferId string Optional. Client Transfer ID. Client transfer ID is an optional client-supplied unique identifier for each withdrawal or internal transfer.
advanceEid long Optional. Deposit advance event ID.
pendingEid long Optional. Pending event ID.
withdrawalEid long Optional. Withdrawal event ID.
feeId string Optional. Fee ID.

Custody Account Fees

This endpoint shows Custody fee records in the supported currencies.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

The OAuth scope must have history:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/custodyaccountfees

Sample payload

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

Parameters

Parameter Type Description
request string The literal string "/v1/custodyaccountfees"
nonce integer or timestamp The nonce, as described in Private API Invocation
timestamp timestamp Optional. Only return Custody fee records on or after this timestamp. See Data Types: Timestamps for more information. If not present, will show the most recent Custody fees.
limit_transfers integer Optional. The maximum number of Custody fee records to return. The default is 10 and the maximum is 50.
account string Optional. Only required when using a master api-key. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

Response

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

[

   {
    "txTime": 1657236174056,
    "feeAmount": "10",
    "feeCurrency": "BTC",
    "eid": 256627,
    "eventType": "Withdrawal"
  },
  {
    "txTime": 1652279045196,
    "feeAmount": "10000000",
    "feeCurrency": "ETH",
    "eid": 15364,
    "eventType": "CustodyFeeDebit"
  },
  {
    "txTime": 1652279025196,
    "feeAmount": "1850",
    "feeCurrency": "WFIL",
    "eid": 9016,
    "eventType": "RiaFeeDebit"
  },
  {
    "txTime": 1652279025196,
    "feeAmount": "1850",
    "feeCurrency": "WFIL",
    "eid": 9016,
    "eventType": "RiaFeeCredit"
  }
]
Field Type Description
txTime timestampms Time of Custody fee record in milliseconds
feeAmount string The fee amount charged
feeCurrency string Currency that the fee was paid in
eid integer Custody fee event id
eventType string Custody fee event type

Get Deposit Addresses

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

The OAuth scope must have addresses:read or addresses:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/addresses/:network

Sample payload to return Bitcoin addresses

{
  "request" : "/v1/addresses/bitcoin",
  "nonce" : <nonce>
}

Parameters

Parameter Type Description
request string The string /v1/addresses/:network where :network can be bitcoin, ethereum, bitcoincash, litecoin, zcash, filecoin, dogecoin, tezos, solana, polkadot, avalanche, cosmos, or xrpl
nonce integer or timestamp The nonce, as described in Private API Invocation
timestamp timestampms Optional. Only returns addresses created on or after this timestamp.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account to return deposit addresses for

Response

Get Bitcoin deposit addresses response

[
  {
    "address" : "n2saq73aDTu42bRgEHd8gd4to1gCzHxrdj",
    "timestamp" : 1424285102000,
    "label" : "my bitcoin address"
  },
  {
    "address" : "n2wpl14aJEu10bRgMNd0gdjH8dHJ3h2a3ks",
    "timestamp" : 1824785101000
  }
]

An array of objects with the following fields:

Field Type Description
address string String representation of the new cryptocurrency address.
timestamp timestampms Creation date of the address.
label string Optional. if you provided a label when creating the address, it will be echoed back here.
memo string Optional. it would be present if applicable, it will be present for cosmos address.

New Deposit Address

Roles

The API key you use to access this endpoint must have the Fund Manager role assigned. See Roles for more information.

The OAuth scope must have addresses:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/deposit/:network/newAddress

Sample payload for BTC address generation

{
  "request" : "/v1/deposit/bitcoin/newAddress",
  "nonce" : <nonce>,
  "label" : "optional test label"
}

Sample payload for legacy LTC address generation

{
  "request": "/v1/deposit/litecoin/newAddress",
  "nonce" : <nonce>,
  "label" : "LTC legacy deposit address",
  "legacy" : True
}

Parameters

Parameter Type Description
request string The string /v1/deposit/:network/newAddress where :network can be bitcoin, ethereum, bitcoincash, litecoin, zcash, filecoin, dogecoin, tezos, solana, polkadot, avalanche, cosmos, or xrpl
nonce integer or timestamp The nonce, as described in Private API Invocation
label string Optional. Label for the deposit address
legacy boolean Optional. Whether to generate a legacy P2SH-P2PKH litecoin address. False by default.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account that will have the new deposit address. Only available for exchange accounts.

Response

New BTC deposit address response

{
  "network" : "bitcoin",
  "address" : "n2saq73aDTu42bRgEHd8gd4to1gCzHxrdj",
  "label" : "optional test label"
}

New LTC deposit address response

{
  "network" : "litecoin",
  "address" : "MJRSgZ3UUFcTBTBAcN38XAXvZLwRe8WVw7",
  "label" : "LTC legacy deposit address"
}

An object with the following fields:

Field Type Description
request string The string network where network can be bitcoin, ethereum, bitcoincash, litecoin, zcash, filecoin, dogecoin, tezos, solana, polkadot, avalanche, cosmos, or xrpl
address string String representation of the new cryptocurrency address.
label string Optional. if you provided a label when requesting the address, it will be echoed back here.
memo string Optional. it will be included if aplicable. Cosmos addresses will include a memo.

Withdraw Crypto Funds

Before you can withdraw cryptocurrency funds to an approved address, you need three things:

  1. You must have an approved address list for your account
  2. The address you want to withdraw funds to needs to already be on that approved address list
  3. An API key with the Fund Manager role added

If you would like to withdraw via API to addresses that are not on your approved address list, please reach out to trading@gemini.com. We can enable this feature for you provide a set of approved IP addresses. This functionality is only available for exchange accounts. Pre-approved IP addresses and addresses added to your approved address list are required to enable withdrawal APIs for custody accounts.

See Roles for more information on how to add the Fund Manager role to the API key you want to use.

Roles

The API key you use to access this endpoint must have the Fund Manager role assigned. See Roles for more information.

The OAuth scope must have crypto:send assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

Sample payload for BTC withdrawal

{
   "request":"/v1/withdraw/btc",
   "nonce": <nonce>,
   "address":"mi98Z9brJ3TgaKsmvXatuRahbFRUFKRUdR",
   "amount":"1"
}

Sample payload for ETH withdrawal

{
   "request":"/v1/withdraw/eth",
   "nonce": <nonce>,
   "address":"0xA63123350Acc8F5ee1b1fBd1A6717135e82dBd28",
   "amount":"2.34567",
   "clientTransferId":"AA97B177-9383-4934-8543-0F91A7A02838"
}

POST https://api.gemini.com/v1/withdraw/:currency

where :currency is a supported cryptocurrency, e.g. btc or eth.

Parameters

Parameter Type Description
request string The string /v1/withdraw/:currency where :currency is replaced with the currency code of a supported crypto-currency, e.g. btc, eth, aave, etc. See Symbols and minimums.
nonce integer or timestamp The nonce, as described in Private API Invocation
address string Standard string format of cryptocurrency address.
amount string Quoted decimal amount to withdraw
account string Optional. Only required when using a master api-key. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.
memo string Optional. For addresses that require a memo
clientTransferId string Optional. A unique identifier for the withdrawal, in uuid4 format

Response

JSON reponse for BTC withdrawal

{
    "address":"mi98Z9brJ3TgaKsmvXatuRahbFRUFKRUdR",
    "amount":"1",
    "fee":"0",
    "withdrawalId":"02176a83-a6b1-4202-9b85-1c1c92dd25c4",
    "message":"You have requested a transfer of 1 BTC to mi98Z9brJ3TgaKsmvXatuRahbFRUFKRUdR. This withdrawal will be sent to the blockchain within the next 60 seconds."
}

JSON response for ETH withdrawal

{
   "address":"0xA63123350Acc8F5ee1b1fBd1A6717135e82dBd28",
   "amount":"2.34567"
}

Upon successful response, the system will return the following:

An object with the following fields:

Field Type Description
address string Standard string format of the withdrawal destination address.
amount string The withdrawal amount.
fee string The fee in kind applied to the transaction.
withdrawalID string A unique ID for the withdrawal.
message string A human-readable English string describing the withdrawal.

Errors

Error when account does not have whitelists enabled

{
   "result":"error",
   "reason":"CryptoAddressWhitelistsNotEnabled",
   "message":"Cryptocurrency withdrawal address whitelists are not enabled for account 24.  Please contact support@gemini.com for information on setting up a withdrawal address whitelist."
}

Error when account has whitelists enabled but this specific address is not whitelisted

{
   "result":"error",
   "reason":"CryptoAddressNotWhitelisted",
   "message":"'moXiuoPh6oe2edoFQvxbyxQZgiYkNzjXZ9' is not a whitelisted BTC address.  Please contact support@gemini.com for information on adding addresses to your withdrawal whitelist."
}

Upon error, a response will contain details to help resolve the error as follows:

The response will contain the following fields:

Field Type Description
result string "error"
reason string short description
message string detailed error message

Gas Fee Estimation

API users will not be aware of the transfer fees before starting the withdrawal process. This endpoint allows you to find out the estimated gas fees before you start a withdrawal.

Roles

The API key you use to access this endpoint can have the Trader, Fund Manager, Auditor, WealthManager or Administrator role assigned.

See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/withdraw/{currencyCodeLowerCase}/feeEstimate

where :currencyCodeLowerCase is a supported cryptocurrency, e.g. eth.

Sample payload for ETH withdrawal

{
   "request":"/v1/withdraw/eth/feeEstimate",
   "nonce": <nonce>,
   "address": "0x31c2105b8dea834167f32f7ea7d877812e059230",
   "amount":"0.01",
   "account": ["primary"]
}

Parameters

Parameter Type Description
request string The string /v1/withdraw/{currencyCodeLowerCase}/feeEstimate where :currency is replaced with the currency code of a supported crypto-currency, e.g. eth, aave, etc. See Symbols and minimums.
nonce integer or timestamp The nonce, as described in Private API Invocation.
address string Standard string format of cryptocurrency address.
amount string Quoted decimal amount to withdraw.
account string The name of the account within the subaccount group.

Response

JSON response for ETH withdrawal

{
   "currency": "ETH",
   "fee": "{currency: 'ETH', value: '0'}",
   "isOverride": false,
   "monthlyLimit": 1,
   "monthlyRemaining": 1
}

Upon a successful response, the system will return the following:

An object with the following fields:

Field Type Description
currency string Currency code, see symbols.
fee {currency: string, value: string} The estimated gas fee.
isOverride boolean Value that shows if an override on the customer's account for free withdrawals exists.
monthlyLimit integer Total nunber of allowable fee-free withdrawals.
monthlyRemaining integer Total number of allowable fee-free withdrawals left to use.

Errors

Error for an invalid exchange or non eth network currency

{
   "result":"error",
   "reason":"CurrencyNotSupported",
   "message":"CurrencyNotSupported"
}

Error when the address is invalid

{
   "result":"error",
   "reason":"InvalidCryptoAddress",
   "message":"Ethereum address had too many or too few characters. Are you sure you typed or pasted it correctly?"
}

Upon error, a response will contain details to help resolve the error as follows:

The response will contain the following fields:

Field Type Description
result string "error"
reason string short description
message string detailed error message

Internal Transfers

This API allows you to execute an internal transfer between any two accounts within your Master Group. In the scenario of exchange account to exchange account there will be no activity on a blockchain network. All other combinations will result in a movement of funds on a blockchain network.

Gemini Custody account withdrawals will not occur until the daily custody run occurs. In the case of funds moving from a Gemini Custody account to a Gemini Exchange account, the exchange account will get a precredit for the amount to be received. The exchange account will be able to trade these funds but will be unable to withdraw until the funds are processed on the blockchain and received.

Gemini Custody accounts request withdrawals to approved addresses in all cases and require the request to come from an approved IP address. Please reach out to trading@gemini.com to enable API withdrawals for custody accounts.

Gemini Custody accounts do not support fiat currency transfers.

Fiat transfers between non-derivative and derivatives accounts are prohibited.

Roles

The API key you use to access this endpoint must be a Master level key and have the Fund Manager role assigned. See Roles for more information.

HTTP Request

Sample payload for BTC transfer

{
   "request":"/v1/account/transfer/btc",
   "nonce": <nonce>,
   "sourceAccount":"my-account",
   "targetAccount":"my-other-account",
   "amount":"1",
   "clientTransferId":"AA97B177-9383-4934-8543-0F91A7A02838"
}

POST https://api.gemini.com/v1/account/transfer/:currency

where :currency is either a fiat currency, e.g. usd or gbp, or a supported crypto-currency, e.g. gusd, btc, eth, aave, etc.

Parameters

Parameter Type Description
request string The string /v1/account/transfer/:currency where :currency is replaced with either usd or a supported crypto-currency, e.g. gusd, btc, eth, aave, etc. See Symbols and minimums.
nonce integer or timestamp The nonce, as described in Private API Invocation
sourceAccount string Nickname of the account you are transferring from. Use the Get Accounts endpoint to get all account names in the group.
targetAccount string Nickname of the account you are transferring to. Use the Get Accounts endpoint to get all account names in the group.
amount string Quoted decimal amount to withdraw
clientTransferId string Optional. A unique identifier for the internal transfer, in uuid4 format
withdrawalId string Optional. Unique ID of the requested withdrawal.

Response

JSON reponse for BTC transfer

{
   "fromAccount":"my-account",
   "toAccount":"my-other-account",
   "amount": "1",
   "currency":"Bitcoin",
   "uuid":"9c153d64-83ba-4532-a159-ebe3f6797766",
   "message": "Success, transfer completed."
}

Upon successful response, the system will return the following:

An object with the following fields:

Field Type Description
fromAccount string Source account where funds are sent from
toAccount string Target account to receive funds in the internal transfer
amount string Quantity of assets being transferred
fee string Fee taken for the transfer. Exchange account to exchange account transfers will always be free and will not be deducted from the free monthly transfer amount for that account.
currency string Display Name. Can be Bitcoin, Ether, Zcash, Litecoin, Dollar, etc.
withdrawalId string Excludes exchange to exchange. Unique ID of the requested withdrawal.
uuid string Only for exchange to exchange. Unique ID of the completed transfer
message string Message describing result of withdrawal. Will inform of success, failure, or pending blockchain transaction.
txHash string Only for Ethereum network transfers. Excludes exchange to exchange transfers. Transaction hash for ethereum network transfer.

Add Bank

The add bank API allows for banking information to be sent in via API. However, for the bank to be verified, you must still send in a wire for any amount from the bank account.

Roles

This API requires the FundManager role. See Roles for more information.

The OAuth scope must have banks:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/payments/addbank

Sample Payload

{
  "request": "/v1/payments/addbank",
  "nonce": <nonce>,
  "accountnumber": "account-number-string",
  "routing": "routing-number-string",
  "type": "checking",
  "name": "Satoshi Nakamoto Checking"
}

Parameters

Parameter Type Description
request string The literal string "/v1/payments/addbank"
nonce integer or timestamp The nonce, as described in Private API Invocation
accountnumber string Account number of bank account to be added
routing string Routing number of bank account to be added
type string Type of bank account to be added. Accepts checking or savings
name string The name of the bank account as shown on your account statements
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

Sample Response

{"referenceId": "BankAccountRefId(18428)"}
Field Type Description
referenceId string Reference ID for the new bank addition request. Once received, send in a wire from the requested bank account to verify it and enable withdrawals to that account.

Add A Bank CAD

The add bank API allows for CAD banking information to be sent in via API. However, for the bank to be verified, you must still send in a wire for any amount from the bank account.

Roles

This API requires the FundManager role. See Roles for more information.

The OAuth scope must have banks:create assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/payments/addbank/cad

Sample Payload

{
  "request": "/v1/payments/addbank/cad",
  "nonce": <nonce>,
  "swiftcode": "swift-code-string",
  "accountnumber": "account-number-string",
  "institutionnumber": "institution-number-string",
  "branchnumber": "branch-number-string",
  "type": "checking",
  "name": "Satoshi Nakamoto Checking",
  "account": "account-string"
}

Parameters

Parameter Type Description
request string The literal string "/v1/payments/addbank/cad"
nonce integer or timestamp The nonce, as described in Private API Invocation
swiftcode string The account SWIFT code
accountnumber string Account number of bank account to be added
institutionnumber string Optional. The institution number of the account - optional but recommended.
branchnnumber string Optional. The branch number - optional but recommended.
type string Type of bank account to be added. Accepts checking or savings
name string The name of the bank account as shown on your account statements
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

Sample Response

{"result": "OK"}
Field Type Description
result string Status of the request. "OK" indicates the account has been created successfully.

Payment Methods

The payments methods API will return data on balances in the account and linked banks.

Roles

The API key you use to access this endpoint can be either a Master or Account level key with any role assigned. See Roles for more information.

The OAuth scope must have banks:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/payments/methods

Sample Payload

{
    "request": "/v1/payments/methods",
    "account": "primary",
    "nonce": <nonce>
}

Parameters

Parameter Type Description
request string The literal string "/v1/payments/methods"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

JSON Response

{
  "balances": [
    {
      "type": "exchange",
      "currency": "USD",
      "amount": "50893484.26",
      "available": "50889972.01",
      "availableForWithdrawal": "50889972.01"
    }
  ],
  "banks": [
    {
      "bank": "Jpmorgan Chase Bank Checking  - 1111",
      "bankId": "97631a24-ca40-4277-b3d5-38c37673d029"
    }
  ]
}

Response

A JSON object containing balance and banking information.

Field Type Description
balances array Array of JSON objects with available fiat currencies and their balances.
-- type string Account type. Will always be exchange
-- currency string Symbol for fiat balance.
-- amount string Total account balance for currency.
-- available string Total amount available for trading
-- availableForWithdrawal string Total amount available for withdrawal
banks array Array of JSON objects with banking information
-- bank string Name of bank account
-- bankId string Unique identifier for bank account

Gemini Staking

To learn more about Staking, please visit https://www.gemini.com/staking

Get Staking Balances

This will show the available balance in Staking as well as the available balance for withdrawal.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/balances/staking

Parameters

Parameter Type Description
request string The string /v1/balances/staking
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

Response

JSON response

[
  {
    "type": "Staking",
    "currency": "MATIC",
    "balance": 10,
    "available": 0,
    "availableForWithdrawal": 10,
    "balanceByProvider": {
      "62b21e17-2534-4b9f-afcf-b7edb609dd8d": {
        "balance": 10
      }
    }
  },
  {
    "type": "Staking",
    "currency": "ETH",
    "balance": 3,
    "available": 0,
    "availableForWithdrawal": 3,
    "balanceByProvider": {
      "62b21e17-2534-4b9f-afcf-b7edb609dd8d": {
        "balance": 3
      }
    }
  }
]

Response is a list of objects, one for each currency, with the following fields:

Field Type Description
type string Staking
currency string Currency code, see symbols
balance decimal The current Staking balance
available decimal The amount that is available to trade
availableForWithdrawal decimal The Staking amount that is available to redeem to exchange account
balanceByProvider JSON object A nested JSON object of balances organized by provider
-- balance decimal The current Staking balance per providerId

Get Staking Rates

This will return the current Gemini Staking interest rates (in bps). When including the specific asset(s) in the request, the response will include the specific assets' (e.g. eth, matic) Staking rate. When not including the specific asset in the request, the response will include all Staking rates.

HTTP Request

GET https://api.gemini.com/v1/staking/rates

Response

JSON response

{
  "62bb4d27-a9c8-4493-a737-d4fa33994f1f": {
    "MATIC": {
      "providerId": "62bb4d27-a9c8-4493-a737-d4fa33994f1f",
      "rate": 429.386,
      "apyPct": 4.39,
      "ratePct": 4.29386,
      "depositUsdLimit": 500000
    },
    "ETH": {
      "providerId": "62bb4d27-a9c8-4493-a737-d4fa33994f1f",
      "rate": 388.8325,
      "apyPct": 3.96,
      "ratePct": 3.888325,
      "depositUsdLimit": 500000
    }
  }
}

Upon successful response, the system will return the following:

A nested JSON object, organized by provider, then currency. Each object will have the following format:

Field Type Description
providerId string Provider Id, in uuid4 format
rate int Staking interest rate in bps (Expressed as a simple rate. Interest on Staking balances compounds daily. In mobile and web applications, APYs are derived from this rate and rounded to 1/10th of a percent.)
apyPct float Staking interest APY (Expressed as a percentage derived from the rate and rounded to 1/10th of a percent.)
ratePct float rate expressed as a percentage
depositUsdLimit int Maximum new amount in USD notional of this crypto that can participate in Gemini Staking per account per month

Get Staking Rewards

This will show the historical Staking reward payments and accrual.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/staking/rewards

Parameters

Parameter Type Description
request string The string /v1/staking/rewards
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.
since string In iso datetime with timezone format
until string Optional. In iso datetime with timezone format, default to current time as of server time
providerId string Optional. Borrower Id, in uuid4 format. providerId is accessible from the Staking rates response
currency string Optional. Currency code, see symbols

Response

JSON response

{
  "62b21e17-2534-4b9f-afcf-b7edb609dd8d": {
    "MATIC": {
      "providerId": "62b21e17-2534-4b9f-afcf-b7edb609dd8d",
      "currency": "MATIC",
      "accrualTotal": 0.103994,
      "ratePeriods": [
        {
          "providerId": "62b21e17-2534-4b9f-afcf-b7edb609dd8d",
          "currency": "MATIC",
          "apyPct": 5.75,
          "ratePct": 5.592369,
          "numberOfAccruals": 1,
          "accrualTotal": 0.0065678,
          "firstAccrualAt": "2022-08-23T20:00:00.000Z",
          "lastAccrualAt": "2022-08-23T20:00:00.000Z"
        },
        {
          "providerId": "62b21e17-2534-4b9f-afcf-b7edb609dd8d",
          "currency": "MATIC",
          "apyPct": 5.2,
          "ratePct": 5.073801,
          "numberOfAccruals": 1,
          "accrualTotal": 0.0037971687995651837,
          "firstAccrualAt": "2022-10-28T20:00:00.000Z",
          "lastAccrualAt": "2022-10-28T20:00:00.000Z"
        }
      ]
    }
  },
  "ETH": {
    "providerId": "62b21e17-2534-4b9f-afcf-b7edb609dd8d",
    "currency": "ETH",
    "accrualTotal": 0.017999076209977,
    "ratePeriods": [
      {
        "providerId": "62b21e17-2534-4b9f-afcf-b7edb609dd8d",
        "currency": "ETH",
        "apyPct": 0.66,
        "ratePct": 0.65913408,
        "numberOfAccruals": 1,
        "accrualTotal": 0.00014802170517505,
        "firstAccrualAt": "2022-11-02T20:00:00.000Z",
        "lastAccrualAt": "2022-11-02T20:00:00.000Z"
      }
    ]
  }
}

Upon successful response, the system will return the following:

A nested JSON object, organized by provider, then currency. Each object will have the following format:

Field Type Description
providerId string Provider Id, in uuid4 format. providerId
currency string Currency code, see symbols
accrualTotal decimal The total accrual
ratePeriods array Array of JSON objects with period accrual information
-- providerId string Provider Id, in uuid4 format. providerId
-- currency string Currency code, see symbols
-- apyPct decimal Staking reward rate expressed as an APY at time of accrual. Interest on Staking balances compounds daily based on the simple rate which is available from /v1/staking/rates/
-- numberOfAccruals int Number of accruals in the specific aggregate, typically one per day. If the rate is adjusted, new accruals are added.
-- accrualTotal decimal The total accrual
-- firstAccrualAt string Time of first accrual. In iso datetime with timezone format
-- lastAccrualAt string Time of last accrual. In iso datetime with timezone format

Get Staking History

This will show all staking deposits, redemptions and interest accruals.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Auditor role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/staking/history

Parameters

Parameter Type Description
request string The string /v1/staking/history
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.
since timestampms Optional. In iso datetime with timezone format. Defaults to the timestamp of the first deposit into Staking.
until timestampms Optional. In iso datetime with timezone format, default to current time as of server time
limit integer Optional. The maximum number of transactions to return. Default is 50, max is 500.
providerId string Optional. Borrower Id, in uuid4 format. providerId is accessible from the Staking rates response
currency string Optional. Currency code, see symbols
interestOnly boolean Optional. Toggles whether to only return daily interest transactions. Defaults to false.
sortAsc boolean Optional. Toggles whether to sort the transactions in ascending order by datetime. Defaults to false.

Response:

JSON Response

[
  {
    "providerId": "62b21e17-2534-4b9f-afcf-b7edb609dd8d",
    "transactions": [
      {
        "transactionId": "MPZ7LDD8",
        "transactionType": "Redeem",
        "amountCurrency": "MATIC",
        "amount": 20,
        "dateTime": 1667418560153
      },
      {
        "transactionId": "65QN4XM5",
        "transactionType": "Deposit",
        "amountCurrency": "MATIC",
        "amount": 30,
        "dateTime": 1667418287795
      },
      {
        "transactionId": "YP22OK4P",
        "transactionType": "Deposit",
        "amountCurrency": "ETH",
        "amount": 3,
        "dateTime": 1667397368929
      },
      {
        "transactionId": "TQN9OPN",
        "transactionType": "Interest",
        "amountCurrency": "MATIC",
        "amount": 0.01,
        "priceCurrency": "USD",
        "priceAmount": 0.1,
        "dateTime": 1667418287795
      }
    ]
  }
]

Upon successful response, the system will return the following:

A nested JSON object, organized by provider. Each object will have the following format:

Field Type Description
providerId string provider Id, in uuid4 format. providerId
transactionId string A unique identifier for the staking transaction
transactionType string Can be any one of the following: Deposit, Redeem, Interest, RedeemPayment, AdminRedeem, AdminCreditAdjustment, AdminDebitAdjustment
amountCurrency string Currency code, see symbols
amount decimal The amount that is defined by the transactionType above
priceCurrency string A supported three-letter fiat currency code, e.g. usd
priceAmount decimal Current market price of the underlying token at the time of the reward
dateTime timestampms The time of the transaction in milliseconds

How to iterate through all transactions:

To retrieve your full Staking history walking backwards,

  1. Initial request: POST to https://api.gemini.com/v1/staking/history with a JSON payload including sortAsc set to false and a limit key with value 500.
  2. When you receive the list of Staking transactions, they will be sorted by datetime descending - so the last element in the list will have the lowest timestamp value. For this example, say that value is X.
  3. Create a second POST request with a JSON payload including a until timestamp key with value X-1, sortAsc set to false, and a limit key with value 500.
  4. Take the last element of the list returned with lowest datetime value Y and create a third POST request with a JSON payload including a until timestamp key with value Y-1, sortAsc set to false, and a limit key with value 500.
  5. Continue creating POST requests and retrieving Staking transactions until an empty list is returned.

Staking Deposits

Initiates Staking deposits.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Trader role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/staking/stake

Parameters

Parameter Type Description
request string The string v1/staking/stake
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.
providerId string Provider Id, in uuid4 format. providerId is accessible from the Staking rates response
currency string Currency code, see symbols
amount decimal The amount of currency to deposit

Response

JSON response

{
  "transactionId": "65QN4XM5",
  "providerId": "62b21e17-2534-4b9f-afcf-b7edb609dd8d",
  "currency": "MATIC",
  "amount": 30,
  "rates": {
    "rate": 540
  }
}

Upon successful response, the system will return the following:

Field Type Description
transactionId string A unique identifier for the staking transaction
providerId string Provider Id, in uuid4 format. providerId
currency string Currency code, see symbols
amount decimal The amount deposited
accrualTotal decimal The total accrual
rates list A JSON object including one or many rates. If more than one rate it would be an array of rates.
-- rate int Staking interest rate in bps (Expressed as a simple rate. Interest on Staking balances compounds daily. In mobile and web applications, APYs are derived from this rate and rounded to 1/10th of a percent.)

Staking Withdrawals

Initiates Staking withdrawals.

Roles

The API key you use to access this endpoint must have the Trader, Fund Manager or Trader role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/staking/unstake

Parameters

Parameter Type Description
request string The string v1/staking/unstake
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.
providerId string Provider Id, in uuid4 format. providerId is accessible from the Staking rates response
currency string Currency code, see symbols
amount decimal The amount of currency to deposit

Response

JSON response

{
  "transactionId": "MPZ7LDD8",
  "amount": 20,
  "amountPaidSoFar": 20,
  "amountRemaining": 0,
  "currency": "MATIC",
  "requestInitiated": "2022-11-02T19:49:20.153Z"
}

Upon successful response, the system will return the following:

Field Type Description
transactionId string A unique identifier for the staking transaction
amount decimal The amount deposited
amountPaidSoFar decimal The amount redeemed successfully
amountRemaining decimal The amount pending to be redeemed
requestInitiated string In iso datetime with timezone format

Approved Address APIs

Gemini offers withdrawal address whitelisting to restrict withdrawals only to addresses on the list. Single-user accounts require a 7 day waiting period for addresses newly added to be approved, while multi-user accounts require dual control from 2 users for approval. The users must have the Fund Manager role to approve dual control address list additions. Please see roles for more information.

Approved address lists can be set at the account or group level.

Create an Address Request

Allows for creation of an approved address addition. Once the request is made, the 7 day waiting period will begin. Please note that all approved address requests are subject to the 7 day waiting period.

If you add an address using an account-scoped API key, then the address will be added to your account specific approved address list. If you use a master-scoped API key, the address will be added to your group-level approved address list unless you specify an account.

Please reach out to trading@gemini.com if you have any questions about approved addresses.

Roles

This API requires the FundManager role. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/approvedAddresses/:network/request

Sample Payload for Address Addition for Account-level approved address list

{
    "request": "/v1/approvedAddresses/ethereum/request",
    "nonce": <nonce>,
    "address": "0x0000000000000000000000000000000000000000",
    "label": "api_added_ETH_address",
    "account": "primary"
}
Parameter Type Description
request string The literal string "/v1/approvedAddresses/:network/request" where :network can be bitcoin, ethereum, bitcoincash, litecoin, zcash, filecoin, dogecoin, tezos, solana, polkadot, avalanche, cosmos, or xrpl
nonce integer or timestamp The nonce, as described in Private API Invocation
address string A string of the address to be added to the approved address list.
label string The label of the approved address.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to add the approved address.
memo string Optional. it would be present if applicable, it will be present for cosmos address.

Sample Response

{
    "message": "Approved address addition is now waiting a 7-day approval hold before activation."
}
Field Type Description
message string Upon successful request, the endpoint will return a string indicating the 7-day approval hold period has begun.

View Approved Addresses

Allows viewing of Approved Address list.

Roles

This API can accept any role. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/approvedAddresses/account/:network

Sample payload to view Approved Address list

{
    "request": "/v1/approvedAddresses/account/ethereum",
    "nonce": <nonce>,
    "account": "primary"
}
Parameter Type Description
request string The literal string "/v1/approvedAddresses/account/:network" where :network can be bitcoin, ethereum, bitcoincash, litecoin, zcash, filecoin, dogecoin, tezos, solana, polkadot, avalanche, cosmos, or xrpl
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to view the approved address list.

Sample Response for Ethereum Approved Address

{
  "approvedAddresses": [
    {
      "network": "ethereum",
      "scope": "account",
      "label": "api_added_ETH_address",
      "status": "pending-time",
      "createdAt": "1602692572349",
      "address": "0x0000000000000000000000000000000000000000"
    },
    {
      "network": "ethereum",
      "scope": "group",
      "label": "api_added_ETH_address",
      "status": "pending-time",
      "createdAt": "1602692542296",
      "address": "0x0000000000000000000000000000000000000000"
    },
    {
      "network": "ethereum",
      "scope": "group",
      "label": "hardware_wallet",
      "status": "active",
      "createdAt": "1602087433270",
      "address": "0xA63123350Acc8F5ee1b1fBd1A6717135e82dBd28"
    },
    {
      "network": "ethereum",
      "scope": "account",
      "label": "hardware_wallet",
      "status": "active",
      "createdAt": "1602086832986",
      "address": "0xA63123350Acc8F5ee1b1fBd1A6717135e82dBd28"
    }
  ]
}
Field Type Description
approvedAddresses array Array of approved addresses on both the account and group level.
-- network string The network of the approved address. Network can be bitcoin, ethereum, bitcoincash, litecoin, zcash, filecoin, dogecoin, tezos, solana, polkadot, avalanche, cosmos, or xrpl
-- scope string Will return the scope of the address as either "account" or "group"
-- label string The label assigned to the address
-- status string The status of the address that will return as "active", "pending-time" or "pending-mua". The remaining time is exactly 7 days after the initial request. "pending-mua" is for multi-user accounts and will require another administator or fund manager on the account to approve the address.
-- createdAt string UTC timestamp in millisecond of when the address was created.
-- address string The address on the approved address list.

Remove Addresses From Approved Address List

Allows for removal of active or time-pending addresses from the Approved Address list. Addresses that are pending approval from another user on the account cannot be removed via API.

Roles

This API requires the FundManager role. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/approvedAddresses/:network/remove

Sample Payload for Address Removal

{
    "request": "/v1/approvedAddresses/ethereum/remove",
    "nonce": <nonce>,
    "address": "0x0000000000000000000000000000000000000000"
}
Parameter Type Description
request string The literal string "/v1/approvedAddresses/:network/remove" where :network can be bitcoin, ethereum, bitcoincash, litecoin, zcash, filecoin, dogecoin, tezos, solana, polkadot, avalanche, cosmos, or xrpl
nonce integer or timestamp The nonce, as described in Private API Invocation
address string A string of the address to be removed from the approved address list.
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Specifies the account on which you intend to remove the approved address.

Sample Response for removal of address from group approved address list

{
    "message": "0x0000000000000000000000000000000000000000 removed from group pending-time approved addresses."
}
Field Type Description
message string Upon successful request, the endpoint will return a string indicating the address and whether it was removed from the group-level or account-level approved address list.

Account Administration APIs

Account Detail

The account API will return detail about the specific account requested such as users, country codes, etc.

Roles

The API key you use to access this endpoint can be either a Master or Account level key with any role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/account

Sample Payload

{
    "request": "/v1/account",
    "account": "primary",
    "nonce": <nonce>
}

Sample Response

{
  "account": {
    "accountName": "Primary",
    "shortName": "primary",
    "type": "exchange",
    "created": "1498245007981"
  },
  "users": [
    {
      "name": "Satoshi Nakamoto",
      "lastSignIn": "2020-07-21T13:37:39.453Z",
      "status": "Active",
      "countryCode": "US",
      "isVerified": true
    },
    {
      "name": "Gemini Support",
      "lastSignIn": "2018-07-11T20:04:36.073Z",
      "status": "Suspended",
      "countryCode": "US",
      "isVerified": false
    }
  ],
  "memo_reference_code": "GEMPJBRDZ"
}

Parameters

No fields are expected in the request, other than the request name and the nonce

Parameter Type Description
request string The literal string "/v1/account"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Optional. Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

Response

A JSON object containing basic information about the requested account and its users

Field Type Description
account JSON object Contains information on the requested account
-- accountName string The name of the account provided upon creation. Will default to Primary
-- shortName string Nickname of the specific account (will take the name given, remove all symbols, replace all " " with "-" and make letters lowercase)
-- type string The type of account. Will return either exchange or custody
-- created timestampms The timestamp of account creation, displayed as number of milliseconds since 1970-01-01 UTC. This will be transmitted as a JSON number
users array Contains an array of JSON objects with user information for the requested account
-- -- name string Full legal name of the user
-- -- lastSignIn string Timestamp of the last sign for the user. Formatted as yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
-- -- status string Returns user status. Will inform of active users or otherwise not active
-- -- countryCode string 2 Letter country code indicating residence of user.
-- -- isVerified bool Returns verification status of user.
memo_reference_code string Returns wire memo reference code for linked bank account.

Create Account

A Master API key can create a new exchange account within the group. This API will return the name of your new account for use with the account parameter in when using Master API keys to perform account level functions. Please see the example below

Roles

The API key you use to access this endpoint must be a Master level key and have the Administrator role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/account/create

Sample payload

{
    "request": "/v1/account/create",
    "nonce": <nonce>,
    "name": "My Secondary Account",
    "type": "exchange"
}

Parameters

The request expects a nonce, and an account name

Parameter Type Description
request string The literal string "/v1/account/create"
nonce integer or timestamp The nonce, as described in Private API Invocation
name string A unique name for the new account
type string Optional. Either exchange or custody is accepted. Will generate an exchange account if exchange or parameter is missing. Will generate a custody account if custody

Response

An element containing basic information about the created account

Field Type Description
account string Account reference string for use in APIs based off the provided name field
type string Will return the type of account generated. exchange if an exchange account was created, custody if a custody account was created

JSON response

{
    "account": "my-secondary-account",
    "type": "exchange"
}

Rename Account

A Master or Account level API key can rename an account within the group.

Roles

The API key you use to access this endpoint can be either a Master or Account level API key and must have the Administrator role assigned. See Roles for more information.

HTTP Request

POST https://api.gemini.com/v1/account/rename

Sample payload

{
    "request": "/v1/account/rename",
    "nonce": <nonce>,
    "account": "my-exchange-account",
    "newName": "My Exchange Account New Name",
    "newAccount": "my-exchange-account-new-name"
}

Parameters

The request expects a nonce, an account name, and a new account name or shortcode.

Parameter Type Description
request string The literal string "/v1/account/rename".
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Only required when using a master api-key. The shortname of the account within the subaccount group. Master API keys can get all account shortnames from the account field returned by the Get Accounts endpoint.
newName string Optional. A unique name for the new account. If not provided, name will not change.
newAccount string Optional. A unique shortname for the new account. If not provided, shortname will not change.

Response

An element containing the updated name of the account.

Field Type Description
name string New name for the account based off the provided newName field. Only returned if newName was provided in the request.
account string New shortname for the account based off the provided newAccount field. Only returned if newAccount was provided in the request.

JSON response

{
    "name": "My Exchange Account New Name",
    "account": "my-exchange-account-new-name"
}

Get Accounts in Master Group

A Master API key can be used to get the accounts within the group. A maximum of 500 accounts can be listed in a single API call.

Roles

The API key you use to access this endpoint must be a Master level key. See Roles for more information.

The OAuth scope must have account:read assigned to access this endpoint. See OAuth Scopes for more information.

HTTP Request

POST https://api.gemini.com/v1/account/list

Sample Payload

{
    "request": "/v1/account/list",
    "nonce": <nonce>,
    "limit_accounts": 100,
    "timestamp": 1632485834721
}

Parameters

Parameter Type Description
request string The literal string "/v1/account/list"
nonce integer or timestamp The nonce, as described in Private API Invocation
limit_accounts integer Optional. The maximum number of accounts to return. Maximum and default values are both 500.
timestamp timestamp Optional. Only return accounts created on or before the supplied timestamp. If not provided, the 500 most recently created accounts are returned.

Response

The response will be a JSON object containing all accounts within the master group

Field Type Description
name string The name of the account provided upon creation.
account string Nickname of the specific account (will take the name given, remove all symbols, replace all " " with "-" and make letters lowercase)
type string Either "exchange" or "custody" depending on type of account
counterparty_id string The Gemini clearing counterparty ID associated with the API key making the request. Will return None for custody accounts
created timestampms The timestamp of account creation, displayed as number of milliseconds since 1970-01-01 UTC. This will be transmitted as a JSON number
status string Either "open" or "closed"

JSON response

[
    {
        "name": "Primary",
        "account": "primary",
        "type": "exchange",
        "counterparty_id": "EMONNYXH",
        "created": 1495127793000,
        "status": "open"
    },
    {
        "name": "My Custody Account",
        "account": "my-custody-account",
        "type": "custody",
        "counterparty_id": None,
        "created": 1565970772000,
        "status": "open"
    },
    {
        "name": "Other exchange account!",
        "account": "other-exchange-account",
        "type": "exchange",
        "counterparty_id": "EMONNYXK",
        "created": 1565970772000,
        "status": "closed"
    }
]

Using Master API Keys

Gemini supports sub-account functionality which allows users to create multiple Gemini accounts off of their primary account. Administrators on the primary account can create a master API key via API Settings on the Gemini web UI.

Master API keys can be used for any account level endpoint as well if the proper roles are assigned to it. For example, if a master API key has the Administrator and Fund Manager roles assigned, the key can be used to check balances, create new deposit addresses and withdraw. The master API key will need to pass the account parameter in order to specify the account where the trade is placed.

HTTP Request

POST https://api.gemini.com/v1/balances

Sample payload for master API key - /v1/balances

{
    "request": "/v1/balances",
    "nonce": <nonce>,
    "account": "primary"
}

This payload will be the same as the regular balances endpoint but includes the account parameter.

Parameters

Parameter Type Description
request string The literal string "/v1/balances"
nonce integer or timestamp The nonce, as described in Private API Invocation
account string Only required when using a master api-key. The name of the account within the subaccount group. Master API keys can get all account names using the Get Accounts endpoint.

Response

The response will be the same as using an account API key.

Session APIs

Heartbeat

This will prevent a session from timing out and canceling orders if the require heartbeat flag has been set. Note that this is only required if no other private API requests have been made. The arrival of any message resets the heartbeat timer.

HTTP Request

Sample payload

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

POST https://api.gemini.com/v1/heartbeat

Parameters

No fields are expected in this request other than the request name and the nonce

Parameter Type Description
request string The literal string "/v1/heartbeat"
nonce integer or timestamp The nonce, as described in Private API Invocation

Response

JSON response

{
    "result": "ok"
}

The response will be a JSON object with a single field "result" with value "true"

Field Type Description
result string "ok"

Error Codes

If a response is in error, then the HTTP response code will be set to reflect this, and a JSON body will be returned that will contain information about the failure.

HTTP Error Codes

HTTP Status Meaning
200 Request was successful
30x API entry point has moved, see Location: header. Most likely an http: to https: redirect.
400 Market not open, or the request was malformed; in the case of a private API request, missing or malformed Gemini private API authentication headers
403 The API key is missing the role necessary to access this private API endpoint
404 Unknown API entry point or Order not found
406 Insufficient Funds
429 Rate Limiting was applied
500 The server encountered an error
502 Technical issues are preventing the request from being satisfied
503 The exchange is down for maintenance

Error payload


{
    "result": "error",
    "reason": "BadNonce",
    "message": "Out-of-sequence nonce <1234> precedes previously used nonce <2345>"
}

In the event of an error, a non-200 error code will be returned, and the response body will be a json object with three fields:

  1. result, which will always be "error"
  2. reason, which will be one of the strings listed in the table below
  3. message, a human-readable English string indicating additional error information.
Reason Meaning
ClientOrderIdTooLong The Client Order ID must be under 100 characters
ClientOrderIdMustBeString The Client Order ID must be a string
ConflictingOptions New orders using a combination of order execution options are not supported
ConflictingAccountName The specified name is already in use within the master group
EndpointMismatch The request was submitted to an endpoint different than the one in the payload
EndpointNotFound No endpoint was specified
GTSTradeIDMustBeString The Clearing ID must be a string
InsufficientFunds The order was rejected because of insufficient funds
InvalidJson The JSON provided is invalid
InvalidNonce The nonce was not greater than the previously used nonce or was not within +/- 30 seconds of Unix Epoch timestamp
InvalidOrderType An unknown order type was provided
InvalidPrice For new orders, the price was invalid
InvalidStopPrice For new stop limit orders, the price was invalid
InvalidStopPriceSell For new stop limit sell orders, the "stop_price" price was lower than the "sell" price
InvalidStopPriceBuy For new stop limit buy orders, the "stop_price" price was greater than the "buy" price
InvalidStopPriceRatio For new stop limit orders, the "buy" or "sell" price was not within 50% of the "stop_price"
InvalidQuantity A negative or otherwise invalid quantity was specified
InvalidSide For new orders, and invalid side was specified
InvalidSignature The signature did not match the expected signature
InvalidSymbol An invalid symbol was specified
InvalidTimestampInPayload The JSON payload contained a timestamp parameter with an unsupported value.
InvalidAccountName The specified name did not match any accounts within the master group
InvalidAccountType The specified type did not match exchange or custody
InvalidFundTransfer The fund transfer was not successful
Maintenance The system is down for maintenance
MarketNotOpen The order was rejected because the market is not accepting new orders
MissingAccountName A required account name was not specified in a field requiring one
MissingAccounts A required account field was not specified
MissingApikeyHeader The X-GEMINI-APIKEY header was missing
MissingOrderField A required order_id field was not specified
MissingRole The API key used to access this endpoint does not have the required role assigned to it
MissingPayloadHeader The X-GEMINI-PAYLOAD header was missing
MissingPayloadKey The payload is missing a required key
MissingSignatureHeader The X-GEMINI-SIGNATURE header was missing
MissingName A required name field was not specified
MissingNonce A nonce was not provided in the payload. See Private API Invocation for more detail.
MoreThanOneAccount More than one account was specified on an API that only accepts a single account
AccountClosed Account account is closed and cannot be used for this operation.
AccountsOnGroupOnlyApi The account field was specified on a non-master API key
AccountLimitExceeded The account field specified more than the maximum supported accounts for that API
NoAccountOfTypeRequired The account field specified multiple accounts and some were not of the required account type
AccountNotOfTypeRequired The account specified in the account field was not of the required account type
NotGroupApiCompatible A master API key was used to invoke an account only API
ExceededMaxAccountsInGroup An account could not be created as the master group already has the maximum number of allowed accounts in it
NoSSL You must use HTTPS to access the API
OptionsMustBeArray The options parameter must be an array.
OrderNotFound The order specified was not found
RateLimit Requests were made too frequently. See Rate Limits below.
System We are experiencing technical issues
UnsupportedOption This order execution option is not supported.
HasNotAgreedToCustodyTerms The Group has not yet agreed to the Custody terms and conditions. Please visit https://exchange.gemini.com/custody to read the terms and conditions of custody accounts.
BadAccountType The type parameter must contain a string of either exchange or custody.
RemoteAddressForbidden Request received from an IP address that is not whitelisted under the group.

Revision History

Date Notes
2015/10/05 Initial REST API documentation
2015/12/22 Document sandbox usage
2016/04/27 Document marker-or-cancel and immediate-or-cancel order placement options.
2016/05/31 Add ETH to supported symbols
2016/08/23 New feature: auction documentation added to new order placement, public APIs, and streaming market data.
2016/12/14 New feature: API key roles, crypto deposit and withdrawal endpoints
2017/02/08 Better explanation of how Gemini rate limits public and private API requests; better client order id documentation
2017/02/22 Added recipe for retrieving full trade history from Get Past Trades endpoint
2017/03/30 Improved documentation for Get Past Trades and Get Available Balances
2017/05/02 Clarify how rate limits are applied.
2017/05/15 Better JSON examples for all the Order Status API endpoints
2017/05/19 API Change order status JSON changed to always include an options array with order execution options. If no order execution options were submitted with the original order, the array will be empty.

Affected endpoints:
2017/05/22 API Change bugfix to timestamp handing in POST requests. Previously a timestamp submitted as a string was silently ignored; timestamps submitted as strings will now be parsed. No timestamp request parameter will be silently discarded. Updated documentation at Data Types: Timestamps to reflect timestamp behavior in requests and responses.

Affected endpoints:
2017/05/31 Added explanation about using limit orders with the immediate-or-cancel execution option instead of market orders to New Order endpoint
2017/07/27
2017/11/30 API Change clarify that only seven calendar days of data will be available through public API endpoints at Trade History and Auction History. Email support@gemini.com for information about Gemini market data.

Please note this seven day limit on retrieving historical data does not affect your private API endpoints Get Past Trades or Order Status.
2017/12/01 API Change added collar_price to Current Auction and Auction History
2018/02/09 API Change update API Error Codes
2018/04/06 New Feature: Document block trading support.
2018/04/06 New Feature: Document Transfers endpoint.
2018/09/10 Added Gemini dollar example to Transfers.
2018/09/14 Document new fill-or-kill order placement options.
2019/03/01 Document changes to Notional Volume
2019/03/22 Add Gemini Dollar section and detail changes to Withdrawals
2019/05/31 Add legacy parameter for LTC address generation
2019/06/07 Add documentation for ticker v2 and candles endpoints
2019/08/08 New Feature Documentation for Gemini Clearing functionality
2019/08/16 New Feature Documentation for Account Administration APIs and Group Level API keys
2019/11/12 New Feature Documentation for Stop Orders and Group->Master API key reference changes
2019/11/18 New Feature Updating Stop order documentation
2020/03/05 New Feature Documentation for Retrieving deposit addresses, Price Feed, and Notional Balances
2020/04/09 Documentation for new token support: BAT, DAI, LINK, OXT
2020/07/23 New Feature Documentation for Adding a Bank, Viewing Payment Methods and Account Detail
2020/08/28 Removing DAIBTCand DAIETH trading pairs
2020/09/11 Documentation for new token support: AMP, COMP, PAXG
2020/09/24 Documentation for new token support: MKR, ZRX, KNC, MANA, STORJ, SNX, CRV, BAL, UNI, REN, UMA, YFI
2020/10/26 Documentation for new fiat support: GBP and EUR
2020/10/28 New Feature Documentation for new Symbol Details endpoint.
2021/01/28 Documentation for new symbol support: BTCSGD and ETHSGD
2021/02/23 New Feature Documentation for Order Status now includes an optional include_trades parameter.
2021/03/22 Documentation for new token support: SKL, GRT, BNT, 1INCH, ENJ, LRC, SAND
2021/04/08 API Change Symbol Details endpoint has updated parameters
2021/04/16 API Change View Approved Addresses has changed from a GET to a POST HTTP request
2021/04/27 Documentation for new token support: CUBE, LPT, BOND, MATIC, INJ, SUSHI
2021/05/05 Documentation for new token support: DOGE
2021/05/06 New Feature Documentation for SEN Withdrawals
2021/06/07 API Change Added is_clearing_fill to Get Past Trades response
2021/06/16 Documentation for new token support: ALCX, MIR, FTM, ANKR
2021/07/14 Documentation for new token support: CTX
2021/07/21 Documentation for new token support: XTZ
2021/08/06 New Feature Documentation for Earn Balances, Earn Rates and Earn Interest
2021/09/15 Documentation for new token support: AXS, SLP, LUNA, UST, MCO2
2021/10/06 New Feature Documentation for Wrap Order
2021/11/13 Documentation for new token support: WCFG, RARE, RAD, QNT, NMR, MASK, FET, ASH, AUDIO, API3, USDC, SHIB
2021/12/20 Documentation for new token support: RNDR, MC, GALA, ENS, KP3R, CVC, ELON, MIM, SPELL
2022/01/28 New Feature Documentation for Earn History
2022/02/01 Documentation for new token support: TOKE, LDO, RLY
2022/02/08 API Change Added new parameter clientTransferId to Internal Transfers and Withdraw Crypto Funds
2022/02/28 Documentation for new token support: SOL
2022/03/01 Documentation for new token support: RAY, SBR
2022/03/16 Documentation for new token support: APE
2022/03/29 Documentation for new token support: RBN, FXS, DPI, LQTY, LUSD, FRAX, INDEX, MPL
2022/04/26 Documentation for new token support: GUSDSGD
2022/04/27 Documentation for new token support: METIS, QRDO, ZBC, CHZ, REVV, JAM, FIDA, GMT
2022/05/17 Documentation for new token support: GFI, ORCA
2022/05/18 New Feature Documentation for Clearing Order List, Clearing Broker List and Custody Account Fees
2022/05/25 New Feature Documentation for Adding A Bank CAD
2022/06/01 New Feature Documentation for Renaming an Account
2022/06/07 New Feature Documentation for FX Rates
2022/06/14 Documentation for new token support: ALI, TRU
2022/06/14 API Change Removed parameter client_order_id from the trades array of order-status
2022/06/15 New Feature Documentation for Gas Fee Estimation
2022/06/15 Documentation improvement to json example for Symbol Details
2022/06/22 Documentation for new token support: GUSDGBP
2022/06/22 API Change Adding since_tid parameter to Trade History
2022/06/23 Deprecating documentation for Auction and Block trading support
2022/06/29 API Change Adding symbol parameter to Get Notional Volume
2022/07/06 Documentation for new token support: DOT, ERN
2022/08/01 Documentation for new token support: GAL, EUL, SAMO
2022/08/23 Documentation for new token support: BICO, IMX, PLA, IOTX
2022/09/07 Documentation for new token support: BUSD
2022/09/14 New Feature Documentation for Transactions and Clearing Trades
2022/10/03 Remove Gemini Dollar section
2022/10/11 Documentation for new token support: AVAX
2022/11/03 New Feature Documentation for Gemini Staking
2023/01/10 Documentation for new token support: ATOM, USDT
2023/01/19 Updated json response for Transfers to include type:Reward and method:CreditCard.
2023/05/09 Documentation for new token support: PEPE
2023/05/23 Removed: Fund Management APIs -> SEN Withdrawals
2023/05/29 Updated /v1/order/status to specify orderId as negative
2023/08/04 Documentation for token delist: ENJ
2023/08/10 Documentation for new token support: XRP
2023/09/11 Documentation for new token support: HNT
2023/09/18 Removed Documentation for new token support: MPL, MC, METIS, RBN, GFI, LQTY, and LUSD
2023/11/15 Remove Documentation for delisted token: MIR, UST, FXS, FRAX, BUSD
2024/02/06 Documentation for new perps support XPR, SOL
2024/02/29 Documentation for new perps support MATIC, DOGE, LINK, AVAX, LTC, DOT
2024/04/05 Documentation for new perps support WIF
2024/05/05 Remove Documentation for delisted token: OXT-BTC,OXT-ETH,BAT-BTC,BAT-ETH, BTC-DAI, ETH-DAI
2024/09/18 Documentation for new token support WIF
2024/09/18 API Change Remove Documentation for support /v1/balances/earn, /v1/earn/rates, /v1/earn/interest
2024/09/20 Remove Documentation for delisted token: LUNA,SNX,QRDO,ZBC
2024/11/04 Documentation for new token support BONK, POPCAT, OP
2024/11/15 Documentation for new token support MOODENG
2024/11/19 Documentation for new token support PNUT, GOAT, MEW, BOME
python shell