Copy page

Authentication

OAuth 2.0

Gemini supports OAuth 2.0 for user-authorized API access. Gemini implements the authorization code grant flow with refresh tokens (response_type=code).

To get started, create an OAuth application in API Settings. Enter your application name, description, logo, and requested scopes.

When you create an app you choose its client type, and that choice is permanent:

• A confidential client receives a client_id and a client_secret. Use this for applications running on secure servers you control.
• A public client receives a client_id only. Use this for single-page apps, mobile apps, and desktop clients. Public clients must use PKCE.

Your client_id identifies your app in every request. Confidential clients also send a client_secret in token POST requests. Public clients never send secrets and use PKCE instead. You cannot change a client type after creation.

Gemini reviews your registered application before activating it in production. You can register applications immediately in the Sandbox Environment for testing. Email trading@gemini.com with questions.

OAuth 2.0 uses short-lived access tokens (24-hour expiration) for API requests and non-expiring refresh tokens to generate new access tokens.

Authorization Code Grant Flow

In the authorization code flow, you redirect users to Gemini to grant permissions. Gemini returns an authorization code that your backend exchanges for access and refresh tokens.

Authorization Request

Redirect users to Gemini to authorize access to your application. Users log in and approve requested scopes.

GET https://exchange.gemini.com/auth

GET https://exchange.gemini.com/auth?client_id=my_id&response_type=code&redirect_uri=www.example.com/redirect&state=82350325&scope=balances:read,orders:create

GET https://exchange.gemini.com/auth?client_id=my_id&response_type=code&redirect_uri=http://127.0.0.1:51234/callback&state=82350325&scope=balances:read,orders:create&code_challenge=5S_YsMh19iBDX5plIVTXdtF3iJCbJ388EEVd5CVlWxU&code_challenge_method=S256

URL Parameters

Parameter	Type	Description
client_id	string	Unique id of your application. This is provided in your API settings
response_type	string	The literal string "code"
redirect_uri	string	The URL users should be returned to when they authorize. Note, this URL must be included in your list of approved redirect_uris in your app registration
state	string	A random string that will be returned to you in the response. Required (and must be non-empty) for public clients to protect against CSRF; strongly recommended for confidential clients.
scope	string	A comma separated list of scopes corresponding to the access you're requesting for your application. Note, these scopes must be included in your list of scopes in your app registration
code_challenge	string	Required for public clients. The PKCE code challenge: BASE64URL-no-padding(SHA-256(code_verifier)). Always 43 characters for the S256 method. See Public Clients and PKCE
code_challenge_method	string	Required for public clients. The literal string "S256". plain is not accepted

Authorization Response

https://www.example.com/redirect?code=90123465-86ee-44ef-b4e3-835cc89bc8a3&state=82350325

On successful authorization Gemini will redirect your user to the redirect_uri you supplied with additional parameters code and state. The parameter state should match the state you provided, otherwise you should not trust the response. code is a temporary code which you will then use to obtain access and refresh tokens.

Authorization Token Request

Once you have received a code you can exchange it for access and refresh tokens.

POST https://exchange.gemini.com/auth/token

Parameter	Type	Description
client_id	string	Unique id of your application. This is provided in your API settings
client_secret	string	Secret of your application, provided when you register a confidential client in API settings. Confidential clients only — public clients must not send this, and a request that includes it will fail
code	string	The code you received from the authorization request
redirect_uri	string	This must match the redirect_uri provided in the authorization request
grant_type	string	The literal string "authorization_code"
code_verifier	string	Required for public clients. The original code_verifier you generated before the authorization request (43–128 characters from [A-Za-z0-9-._~]). Gemini hashes it and compares it to the code_challenge you sent

Code
{
    "client_id": "my_id",
    "client_secret": "my_secret",
    "code": "90123465-86ee-44ef-b4e3-835cc89bc8a3",
    "redirect_uri": "www.example.com/redirect",
    "grant_type": "authorization_code"
}

Code
{
    "client_id": "my_id",
    "code": "90123465-86ee-44ef-b4e3-835cc89bc8a3",
    "redirect_uri": "http://127.0.0.1:51234/callback",
    "grant_type": "authorization_code",
    "code_verifier": "M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakx-fkdq"
}

Authorization Token Response

Field	Type	Description
access_token	string	A short-lived token to use in API call authentication. Is valid until the expires_in time reaches 0
refresh_token	string	A refresh token to be used to generate new access tokens
token_type	string	The literal string "bearer"
scope	string	The scopes the access token will have access to
expires_in	integer	The lifetime in seconds of the access token, as measured in seconds from the current time

Code
{
    "access_token": "d9af2411-3e85-41bb-89f4-cf53750f04df",
    "refresh_token": "215c5a89-6df7-457b-ba0b-70695da8c91f",
    "token_type": "bearer",
    "scope": "balances:read,orders:create",
    "expires_in": 86399
}

Public Clients and PKCE

A public client is an OAuth app that runs somewhere it cannot keep a secret — a native mobile app, a desktop app, or a single-page app. Because the code ships to the user's device or browser, anyone can read it, so there is no client_secret to protect the token exchange. Public clients close that gap with PKCE (Proof Key for Code Exchange, RFC 7636).

PKCE is required for every public client, and it only works with the authorization code flow. Your app generates a one-time secret before it starts, sends only a hash of that secret when it asks for an authorization code, and reveals the original secret when it exchanges the code for tokens. Gemini hashes what you reveal and checks it against the hash you sent earlier. An attacker who intercepts the authorization code cannot use it, because they never saw the original secret.

How PKCE works

1. Generate a code_verifier. A high-entropy random string of 43–128 characters using only A-Z, a-z, 0-9, -, ., _, ~ (RFC 7636 §4.1).
2. Derive the code_challenge. BASE64URL-no-padding(SHA-256(code_verifier)) — exactly 43 characters for S256.
3. Send the challenge on the authorization request. On GET https://exchange.gemini.com/auth, include code_challenge, code_challenge_method=S256, and a non-empty state. S256 is the only method Gemini accepts; plain is rejected.
4. Send the verifier on the token request. On POST https://exchange.gemini.com/auth/token, include the original code_verifier. Do not include a client_secret. Gemini hashes the verifier and compares it to the challenge from step 3.

Public clients must also send a non-empty state on the authorization request. For confidential clients state is strongly recommended; for public clients it is required, because there is no secret to anchor the request and state is your protection against CSRF. Compare the state in the response to the value you sent, and reject the response if they don't match.

Refresh works the same way for a public client as for a confidential one, with one difference: omit the client_secret. There is no code_verifier on a refresh request.

Redirect URIs for public clients. To support native and desktop apps (RFC 8252), a public client may register an http loopback redirect URI — http://localhost, http://127.0.0.1, or http://[::1] — and the port may vary at runtime, so an ephemeral port chosen by the OS will be accepted. Loopback redirect URIs must use http (not https) and must not include user info. Every other (non-loopback) redirect URI must match your registered URI exactly.

Code
import hashlib
import base64
import secrets

# 1. High-entropy code_verifier (token_urlsafe uses the unreserved set; 64 bytes -> ~86 chars)
code_verifier = secrets.token_urlsafe(64)

# 2. code_challenge = BASE64URL-no-padding( SHA-256( code_verifier ) )
digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")

# Send code_challenge + code_challenge_method=S256 on the authorization request,
# then send code_verifier on the token request.

Using Refresh Tokens

The access token you receive will be relatively short-lived (default 24 hours). Once an access token has expired you can use your refresh token to generate a new access token. Refresh tokens never expire, however they are one-time use only as your request for a new access token will also return a new refresh token.

Getting a new access token is similar to getting the initial access and refresh tokens with slightly different parameters

Refresh Token Request

POST https://exchange.gemini.com/auth/token

Code
{
    "client_id": "my_id",
    "client_secret": "my_secret",
    "refresh_token": "215c5a89-6df7-457b-ba0b-70695da8c91f",
    "grant_type":"refresh_token"
}

Parameter	Type	Description
client_id	string	Unique id of your application
client_secret	string	Secret of your application. This is provided when you first register an app in API settings
refresh_token	string	Your refresh token
grant_type	string	The literal string "refresh_token"

Refresh Token Response

The response is the same as the initial token response – it will contain a new access token to query APIs and a new refresh token for when the access token expires.

Parameter	Type	Description
access_token	string	A short-lived token to use in API call authentication
refresh_token	string	A refresh token to be used to generate new access tokens
token_type	string	The literal string "bearer"
scope	string	The scopes the access token will have access to
expires_in	integer	The lifetime in seconds of the access token, as measured in seconds from the current time

Code
{
  "access_token": "c5e9459d-dc6f-4567-bce4-050ec965f22e",
  "expires_in": 86399,
  "scope": "balances:read,orders:create",
  "refresh_token": "ce0f14af-74dd-4767-a4e7-286e98b944c1",
  "token_type": "bearer"
}

Using Access Tokens

Once you have an access token you can use it to call any Gemini API.

Most of the examples for the private APIs in these docs make use of API keys and corresponding headers, to use an access token simply update your header:

Header	Description
Authorization	The literal string "Bearer " concatenated to your temporary access_token
X-GEMINI-PAYLOAD	The base64-encoded JSON payload (the payloads on OAuth do not require a nonce)

Code
import requests
import json
import base64

url = "https://api.gemini.com/v1/mytrades"
access_token = "Bearer d9af2411-3e85-41bb-89f4-cf53750f04df"

payload = {
    "request": "/v1/mytrades",
    "symbol": "btcusd"
}
encoded_payload = json.dumps(payload).encode()
b64 = base64.b64encode(encoded_payload)

request_headers = { 
    "Authorization": access_token,
    "X-GEMINI-PAYLOAD": b64
}

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

my_trades = response.json()

Code
import requests
import json
import base64

url = "https://api.gemini.com/v1/orders/history"
access_token = "Bearer d9af2411-3e85-41bb-89f4-cf53750f04df"

payload = {
    "request": "/v1/orders/history",
    "symbol": "btcusd"
}
encoded_payload = json.dumps(payload).encode()
b64 = base64.b64encode(encoded_payload)

request_headers = { 
    "Authorization": access_token,
    "X-GEMINI-PAYLOAD": b64
}

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

my_orders = response.json()

OAuth Scopes

Gemini uses a role-based system for its API. All OAuth applications are limited to the scopes in the following chart:

Endpoint	URI	Scope
Get Deposit Addresses	/v1/addresses/:network	addresses:read, addresses:create
New Deposit Address	/v1/deposit/:network/newAddress	addresses:create
List Approved Addresses	/v1/approvedAddresses/account/:network	addresses:read
Remove Approved Address	/v1/approvedAddresses/:network/remove	addresses:create
Get Available Balances	/v1/balances	balances:read
Get Notional Balances	v1/notionalbalances/:currency	balances:read
Add A Bank	/v1/payments/addbank	banks:create
Add A Bank CAD	/v1/payments/addbank/cad	banks:create
View Payment Methods	/v1/payments/methods	banks:read, banks:create
New Clearing Order	/v1/clearing/new	clearing:create
Cancel Clearing Order	/v1/clearing/cancel	clearing:create
Confirm Clearing Order	/v1/clearing/confirm	clearing:create
Clearing Order Status	/v1/clearing/status	clearing:read
Clearing Order List	/v1/clearing/list	clearing:read
Clearing Broker List	/v1/clearing/broker/list	clearing:read
Clearing Trades	/v1/clearing/trades	clearing:read
Withdraw Crypto Funds	/v2/withdraw/:network/:ticker	crypto:send
List Past Trades	/v1/mytrades	history:read
Get Orders History	/v1/orders/history	history:read
Get Notional Volume	/v1/notionalvolume	history:read
Get Trade Volume	/v1/tradevolume	history:read
Transfers	/v2/transfers	history:read
Custody Account Fees	/v1/custodyaccountfees	history:read
Create New Order	/v1/order/new	orders:create
Cancel Order	/v1/order/cancel	orders:create
Cancel All Session Orders	/v1/order/cancel/session	orders:create
Cancel All Active Orders	/v1/order/cancel/all	orders:create
Wrap Order	/v1/wrap/:symbol	orders:create
Get Instant Quote	/v1/instant/quote	orders:create
Execute Instant Order	/v1/instant/execute	orders:create
Get Order Status	/v1/order/status	orders:read
Get Active Orders	/v1/orders	orders:read
Account Detail	/v1/account	account:read
Get Terms Status	/v1/prediction-markets/terms/status	orders:read
Accept Terms	/v1/prediction-markets/terms/accept	orders:create
Place Prediction Market Order	/v1/prediction-markets/order	orders:create
Place Prediction Market Batch Orders	/v1/prediction-markets/order/batch	orders:create
Cancel Prediction Market Order	/v1/prediction-markets/order/cancel	orders:create
Cancel Prediction Market Batch Orders	/v1/prediction-markets/order/batch/cancel	orders:create
Get Active Prediction Market Orders	/v1/prediction-markets/orders/active	orders:read
Get Prediction Market Order History	/v1/prediction-markets/orders/history	orders:read
Get Prediction Market Positions	/v1/prediction-markets/positions	orders:read
Prediction Market WebSocket Position Updates	positions@account, positions@account@1s	positions:read or predictions:positions:read
Get Settled Prediction Market Positions	/v1/prediction-markets/positions/settled	orders:read
Get Prediction Market Volume Metrics	/v1/prediction-markets/metrics/volume	orders:read
List Maker Rebate Payouts	/v1/prediction-markets/maker-rebate/payouts	orders:read
Get Maker Rebate Lifetime Summary	/v1/prediction-markets/maker-rebate/summary/total	orders:read
Get Liquidity Rewards Daily Summary	/v1/prediction-markets/liquidity-rewards/summary/daily	orders:read
Get Liquidity Rewards Lifetime Summary	/v1/prediction-markets/liquidity-rewards/summary/total	orders:read

API keys use different roles for to access Gemini APIs. Please see roles for descriptions of each role and scope for API keys.

Revoke OAuth Token

Clients can programmatically revoke an active access token or refresh token using the OAuth 2.0 Token Revocation endpoint (RFC 7009).

POST https://exchange.gemini.com/auth/token/revoke

Request Parameters

Parameter	Type	Description
token	string	Required. The access token or refresh token to revoke.
client_id	string	Required. Unique client ID of your application.
client_secret	string	Secret of your application (Confidential clients only).

Code
{
  "client_id": "my_id",
  "client_secret": "my_secret",
  "token": "215c5a89-6df7-457b-ba0b-70695da8c91f"
}

Response

On success, Gemini returns HTTP 200 OK with an empty response body. In accordance with RFC 7009 §2.2, HTTP 200 OK is returned regardless of whether the token was currently active or previously revoked.

---

Token Introspection & Authorization Metadata

Gemini also provides standard OAuth 2.0 endpoints for token introspection and server metadata discovery:

• Token Introspection (RFC 7662): POST https://exchange.gemini.com/auth/token/introspect Pass client_id and token to inspect whether a token is active, its scopes, and its expiration timestamp.

• Authorization Server Metadata (RFC 8414): GET https://exchange.gemini.com/.well-known/oauth-authorization-server Returns supported grant types (authorization_code, refresh_token), response types (code), PKCE challenge methods (S256), and endpoint URIs.

---

Revision History

Date	Notes
2020/08/20	Initial OAuth documentation
2026/08/03	Updated OAuth 2.0 verification and added PKCE, token revocation, introspection, and server metadata specifications