REST API

Clearing (1.0.0)

Endpointhttps://api.sandbox.gemini.com

Create New Clearing Order

POST

https://api.sandbox.gemini.com

/v1/clearing/new

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 this endpoint. See OAuth Scopes for more information.

Create New Clearing Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Create New Clearing Order › Request Body

request

string · required

The literal string "/v1/clearing/new"

required

The nonce, as described in Private API Invocation

symbol

string · required

The trading pair

amount

string · required

The amount to trade

price

string · required

The price

side

string · enum · required

The direction of the trade

Enum values:

buy

sell

counterparty_id

string

The counterparty ID

expires_in_hrs

integer

The number of hours until the order expires

account

string

Required for Master API keys. The name of the account within the subaccount group.

Create New Clearing Order › Responses

Successful operation

clearing_id

string

The clearing ID

symbol

string

The trading pair

price

string

The order price

amount

string

The order amount

side

string · enum

Enum values:

buy

sell

status

string

The order status

timestamp

timestampms

integer

The timestamp in milliseconds

is_confirmed

boolean

Whether the order is confirmed

POST/v1/clearing/new

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/new \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/new",
  "nonce": "<nonce>",
  "counterparty_id": "OM9VNL1G",
  "expires_in_hrs": 24,
  "symbol": "btcusd",
  "amount": "100",
  "price": "9500.00",
  "side": "buy"
}
'

shell

Example Request Body

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

json

JSON payload for creating a new clearing order

application/json

Example Responses

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

json

application/json

Get Clearing Order

POST

https://api.sandbox.gemini.com

/v1/clearing/status

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:read assigned to access this endpoint. See OAuth Scopes for more information.

Get Clearing Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Get Clearing Order › Request Body

request

string · required

The literal string "/v1/clearing/status"

required

The nonce, as described in Private API Invocation

clearing_id

string · required

The clearing ID

account

string

Required for Master API keys. The name of the account within the subaccount group.

Get Clearing Order › Responses

Successful operation

clearing_id

string

The clearing ID

symbol

string

The trading pair

price

string

The order price

amount

string

The order amount

side

string · enum

Enum values:

buy

sell

status

string

The order status

timestamp

timestampms

integer

The timestamp in milliseconds

is_confirmed

boolean

Whether the order is confirmed

POST/v1/clearing/status

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/status \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/status",
  "nonce": "<nonce>",
  "clearing_id": "OM9VNL1G"
}
'

shell

Example Request Body

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

json

JSON payload for checking clearing order status

application/json

Example Responses

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

json

application/json

Cancel Clearing Order

POST

https://api.sandbox.gemini.com

/v1/clearing/cancel

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 this endpoint. See OAuth Scopes for more information.

Cancel Clearing Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Cancel Clearing Order › Request Body

request

string · required

The literal string "/v1/clearing/cancel"

required

The nonce, as described in Private API Invocation

clearing_id

string · required

The clearing ID

account

string

Required for Master API keys. The name of the account within the subaccount group.

Cancel Clearing Order › Responses

Successful operation

result

string

Status of the cancel operation

details

string

Detailed description of the result

POST/v1/clearing/cancel

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/cancel",
  "nonce": "<nonce>",
  "clearing_id": "P0521QDV"
}
'

shell

Example Request Body

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

json

JSON payload for canceling a clearing order

application/json

Example Responses

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

json

JSON response for successful order cancellation

application/json

Confirm Clearing Order

POST

https://api.sandbox.gemini.com

/v1/clearing/confirm

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 this endpoint. See OAuth Scopes for more information.

Confirm Clearing Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Confirm Clearing Order › Request Body

request

string · required

The literal string "/v1/clearing/confirm"

required

The nonce, as described in Private API Invocation

clearing_id

string · required

The clearing ID

symbol

string · required

The trading pair

amount

string · required

The amount to trade

price

string · required

The price

side

string · enum · required

The direction of the trade

Enum values:

buy

sell

account

string

Required for Master API keys. The name of the account within the subaccount group.

Confirm Clearing Order › Responses

Successful operation

result

string

Status of the confirmation operation

POST/v1/clearing/confirm

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/confirm \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/confirm",
  "nonce": "<nonce>",
  "clearing_id": "OM9VNL1G",
  "symbol": "btcusd",
  "amount": "100",
  "price": "9500.00",
  "side": "sell"
}
'

shell

Example Request Body

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

json

JSON payload for confirming a clearing order

application/json

Example Responses

{
  "result": "confirmed"
}

json

JSON response for successful order confirmation

application/json

List Clearing Orders

POST

https://api.sandbox.gemini.com

/v1/clearing/list

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:read assigned to access this endpoint. See OAuth Scopes for more information.

List Clearing Orders › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

List Clearing Orders › Request Body

request

string · required

The literal string "/v1/clearing/list"

required

The nonce, as described in Private API Invocation

symbol

string

Trading pair

counterparty

string

counterparty_id or counterparty_alias

side

string · enum

"buy" or "sell"

Enum values:

buy

sell

UTC timestamp. Requires expiration_end if set

UTC timestamp. Requires expiration_start if set

UTC timestamp. Requires submission_end if set

UTC timestamp. Requires submission_start if set

funded

boolean

Default value false if not set

status

string

Filter by status

Only return orders after this timestamp

limit_orders

integer

The maximum number of orders to return

account

string

Required for Master API keys. The name of the account within the subaccount group.

List Clearing Orders › Responses

Successful operation

result

string

Status of the operation

object[]

POST/v1/clearing/list

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/list \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/list",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/clearing/list",
  "nonce": "<nonce>"
}

json

Basic request to get clearing orders

application/json

Example Responses

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

json

JSON response with clearing orders

application/json

List Clearing Brokers

POST

https://api.sandbox.gemini.com

/v1/clearing/broker/list

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:read assigned to access this endpoint. See OAuth Scopes for more information.

List Clearing Brokers › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

List Clearing Brokers › Request Body

request

string · required

The literal string "/v1/clearing/broker/list"

required

The nonce, as described in Private API Invocation

symbol

string

Trading pair

UTC timestamp. Requires expiration_end if set

UTC timestamp. Requires expiration_start if set

UTC timestamp. Requires submission_end if set

UTC timestamp. Requires submission_start if set

funded

boolean

Default value false if not set

status

string

Filter by status

Only return orders after this timestamp

limit_orders

integer

The maximum number of orders to return

account

string

Required for Master API keys. The name of the account within the subaccount group.

List Clearing Brokers › Responses

Successful operation

result

string

Status of the operation

object[]

POST/v1/clearing/broker/list

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/broker/list \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/broker/list",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/clearing/broker/list",
  "nonce": "<nonce>"
}

json

Basic request to get broker clearing orders

application/json

Example Responses

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

json

JSON response with broker clearing orders

application/json

Create New Broker Order

POST

https://api.sandbox.gemini.com

/v1/clearing/broker/new

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.

Create New Broker Order › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

Create New Broker Order › Request Body

request

string · required

The literal string "/v1/clearing/broker/new"

required

The nonce, as described in Private API Invocation

source_counterparty_id

string · required

A symbol that corresponds with the counterparty sourcing the clearing trade

target_counterparty_id

string · required

A symbol that corresponds with the counterparty where the clearing trade is targeted

symbol

string · required

The symbol of the order

amount

string · decimal · required

Quoted decimal amount to purchase

expires_in_hrs

integer · float · required

The number of hours before the trade expires. Your counterparty will need to confirm the order before this time expires.

price

string · decimal · required

Quoted decimal amount to spend per unit

side

string · enum · required

"buy" or "sell". This side will be assigned to the source_counterparty_id. The opposite side will be sent to the target_counterparty_id

Enum values:

buy

sell

account

string

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.

Create New Broker Order › Responses

Successful operation

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.

POST/v1/clearing/broker/new

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/broker/new \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/broker/new",
  "nonce": "<nonce>",
  "source_counterparty_id": "R485E04Q",
  "target_counterparty_id": "Z4929ZDY",
  "symbol": "ethusd",
  "amount": "175.00",
  "expires_in_hrs": 1,
  "price": "200",
  "side": "sell"
}
'

shell

Example Request Body

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

json

Sample payload for broker order initiation

application/json

Example Responses

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

json

application/json

List Clearing Trades

POST

https://api.sandbox.gemini.com

/v1/clearing/trades

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:read assigned to access this endpoint. See OAuth Scopes for more information.

List Clearing Trades › Headers

X-GEMINI-APIKEY

string · required

Your API key

X-GEMINI-SIGNATURE

string · required

HEX-encoded HMAC-SHA384 of payload signed with API secret

X-GEMINI-PAYLOAD

string · required

Base64-encoded JSON payload

Content-Type

string

Default: text/plain

Content-Length

string

Default: 0

Cache-Control

string

Default: no-cache

List Clearing Trades › Request Body

request

string · required

The literal string "/v1/clearing/trades"

required

The nonce, as described in Private API Invocation

timestamp_nanos

integer

Only return transfers on or after this timestamp in nanos

limit_per_account

integer

The maximum number of clearing trades to return. The default is 100 and the maximum is 300.

account

string

Only required when using a master api-key. The name of the account within the subaccount group.

symbol

string

The trading pair

Only return trades after this timestamp

limit_trades

integer

The maximum number of trades to return

List Clearing Trades › Responses

Successful operation

object[]

POST/v1/clearing/trades

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/clearing/trades \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/clearing/trades",
  "nonce": "<nonce>"
}
'

shell

Example Request Body

{
  "request": "/v1/clearing/trades",
  "nonce": "<nonce>"
}

json

Basic request to get clearing trades

application/json

Example Responses

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

json

JSON response with clearing trades

application/json

Session Instant