REST API

Margin Trading (1.0.0)

Endpointhttps://api.sandbox.gemini.com

Get Margin Account Summary

POST

https://api.sandbox.gemini.com

/v1/margin/account

Retrieves comprehensive margin account information including collateral, leverage, buying/selling power, and liquidation risk.

This endpoint provides real-time margin statistics for spot margin trading accounts, helping you monitor your account health and manage risk.

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.

Account Type

This endpoint is only available for margin trading accounts. Standard exchange accounts will receive an error.

Get Margin Account Summary › 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 Margin Account Summary › Request Body

request

string · required

The literal string "/v1/margin/account"

required

The nonce, as described in Private API Invocation

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

Get Margin Account Summary › Responses

Margin account summary with risk statistics

object · required

leverage

string · decimal · required

The current leverage ratio (notionalValue / marginAssetValue)

Example: 1.5

object · required

object

POST/v1/margin/account

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

shell

Example Request Body

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

json

application/json

Example Responses

{
  "marginAssetValue": {
    "currency": "USD",
    "value": "10000.00"
  },
  "availableCollateral": {
    "currency": "USD",
    "value": "8500.00"
  },
  "notionalValue": {
    "currency": "USD",
    "value": "15000.00"
  },
  "totalBorrowed": {
    "currency": "USD",
    "value": "5000.00"
  },
  "leverage": "1.5",
  "buyingPower": {
    "currency": "USD",
    "value": "8500.00"
  },
  "sellingPower": {
    "currency": "USD",
    "value": "8500.00"
  },
  "liquidationRisk": {
    "lossPercentage": "0.1550",
    "liquidationPrice": {
      "currency": "USD",
      "value": "50000.00"
    }
  },
  "interestRate": {
    "rate": "0.00001141552511",
    "interval": "hour"
  },
  "reservedBuyOrders": {
    "currency": "USD",
    "value": "1000.00"
  },
  "reservedSellOrders": {
    "currency": "USD",
    "value": "500.00"
  }
}

json

application/json

Get Margin Interest Rates

POST

https://api.sandbox.gemini.com

/v1/margin/rates

Retrieves current margin interest rates for all borrowable assets.

Returns hourly, daily, and annual borrow rates for each currency that can be borrowed on margin. Interest is charged on borrowed amounts at the hourly rate and compounds over time.

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.

Account Type

This endpoint is only available for margin trading accounts.

Get Margin Interest Rates › 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 Margin Interest Rates › Request Body

request

string · required

The literal string "/v1/margin/rates"

required

The nonce, as described in Private API Invocation

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

Get Margin Interest Rates › Responses

Current margin interest rates for all borrowable assets

object[] · required

Array of interest rates for all borrowable currencies

POST/v1/margin/rates

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

shell

Example Request Body

{
  "request": "/v1/margin/rates",
  "nonce": "<nonce>"
}

json

application/json

Example Responses

{
  "rates": [
    {
      "currency": "BTC",
      "borrowRate": "0.00001141552511",
      "borrowRateDaily": "0.00027397260264",
      "borrowRateAnnual": "0.1",
      "lastUpdated": 1700000000000
    },
    {
      "currency": "ETH",
      "borrowRate": "0.00001141552511",
      "borrowRateDaily": "0.00027397260264",
      "borrowRateAnnual": "0.1",
      "lastUpdated": 1700000000000
    },
    {
      "currency": "USD",
      "borrowRate": "0.00000913242009",
      "borrowRateDaily": "0.00021917808216",
      "borrowRateAnnual": "0.08",
      "lastUpdated": 1700000000000
    }
  ]
}

json

application/json

Preview Margin Order Impact

POST

https://api.sandbox.gemini.com

/v1/margin/order/preview

Previews the margin impact of a hypothetical spot order without actually placing it.

Returns both pre-order and post-order margin risk statistics, allowing you to understand how an order would affect your margin account before execution. This is useful for risk management and planning 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 orders:read assigned to access this endpoint. See OAuth Scopes for more information.

Account Type

This endpoint is only available for margin trading accounts.

Preview Margin Order Impact › 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

Preview Margin Order Impact › Request Body

request

string · required

The literal string "/v1/margin/order/preview"

required

The nonce, as described in Private API Invocation

symbol

string · required

The trading pair symbol (e.g., "btcusd")

Example: btcusd

side

string · enum · required

The order side

Enum values:

buy

sell

Example: buy

type

string · enum · required

The order type

Enum values:

market

limit

Example: limit

amount

string · decimal

The order amount in base currency (required for limit orders and sell market orders)

Example: 0.5

price

string · decimal

The limit price (required for limit orders)

Example: 50000.00

totalSpend

string · decimal

Total spend in quote currency (required for buy market orders)

Example: 25000.00

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

Preview Margin Order Impact › Responses

Pre-order and post-order margin risk statistics

object · required

POST/v1/margin/order/preview

curl --request POST \
  --url https://api.sandbox.gemini.com/v1/margin/order/preview \
  --header 'Content-Type: application/json' \
  --header 'X-GEMINI-APIKEY: <string>' \
  --header 'X-GEMINI-PAYLOAD: <string>' \
  --header 'X-GEMINI-SIGNATURE: <string>' \
  --data '
{
  "request": "/v1/margin/order/preview",
  "nonce": "<nonce>",
  "symbol": "btcusd",
  "side": "buy",
  "type": "limit",
  "amount": "0.5",
  "price": "50000.00"
}
'

shell

Example Request Body

{
  "request": "/v1/margin/order/preview",
  "nonce": "<nonce>",
  "symbol": "btcusd",
  "side": "buy",
  "type": "limit",
  "amount": "0.5",
  "price": "50000.00"
}

json

Preview a limit buy order

application/json

Example Responses

{
  "preorder": {
    "marginAssetValue": {
      "currency": "USD",
      "value": "10000.00"
    },
    "availableCollateral": {
      "currency": "USD",
      "value": "8500.00"
    },
    "notionalValue": {
      "currency": "USD",
      "value": "15000.00"
    },
    "totalBorrowed": {
      "currency": "USD",
      "value": "5000.00"
    },
    "leverage": "1.5",
    "reservedBuyOrders": {
      "currency": "USD",
      "value": "0.00"
    },
    "reservedSellOrders": {
      "currency": "USD",
      "value": "0.00"
    },
    "buyingPower": {
      "currency": "USD",
      "value": "8500.00"
    },
    "sellingPower": {
      "currency": "USD",
      "value": "8500.00"
    }
  },
  "postorder": {
    "marginAssetValue": {
      "currency": "USD",
      "value": "10000.00"
    },
    "availableCollateral": {
      "currency": "USD",
      "value": "6000.00"
    },
    "notionalValue": {
      "currency": "USD",
      "value": "40000.00"
    },
    "totalBorrowed": {
      "currency": "USD",
      "value": "30000.00"
    },
    "leverage": "4.0",
    "reservedBuyOrders": {
      "currency": "USD",
      "value": "0.00"
    },
    "reservedSellOrders": {
      "currency": "USD",
      "value": "0.00"
    },
    "buyingPower": {
      "currency": "USD",
      "value": "6000.00"
    },
    "sellingPower": {
      "currency": "USD",
      "value": "6000.00"
    },
    "liquidationRisk": {
      "lossPercentage": "0.6000",
      "liquidationPrice": {
        "currency": "USD",
        "value": "30000.00"
      }
    }
  }
}

json

application/json

Fund Management Session

Get Margin Account Summary

POST

https://api.sandbox.gemini.com

/v1/margin/account

Retrieves comprehensive margin account information including collateral, leverage, buying/selling power, and liquidation risk.

This endpoint provides real-time margin statistics for spot margin trading accounts, helping you monitor your account health and manage risk.

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.

Account Type

This endpoint is only available for margin trading accounts. Standard exchange accounts will receive an error.

Get Margin Account Summary › 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 Margin Account Summary › Request Body

request

string · required

The literal string "/v1/margin/account"

required

The nonce, as described in Private API Invocation

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

Get Margin Account Summary › Responses

Margin account summary with risk statistics

object · required

leverage

string · decimal · required

The current leverage ratio (notionalValue / marginAssetValue)

Example: 1.5

object · required

object

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

{ "marginAssetValue": { "currency": "USD", "value": "10000.00" }, "availableCollateral": { "currency": "USD", "value": "8500.00" }, "notionalValue": { "currency": "USD", "value": "15000.00" }, "totalBorrowed": { "currency": "USD", "value": "5000.00" }, "leverage": "1.5", "buyingPower": { "currency": "USD", "value": "8500.00" }, "sellingPower": { "currency": "USD", "value": "8500.00" }, "liquidationRisk": { "lossPercentage": "0.1550", "liquidationPrice": { "currency": "USD", "value": "50000.00" } }, "interestRate": { "rate": "0.00001141552511", "interval": "hour" }, "reservedBuyOrders": { "currency": "USD", "value": "1000.00" }, "reservedSellOrders": { "currency": "USD", "value": "500.00" } }

Get Margin Interest Rates

POST

https://api.sandbox.gemini.com

/v1/margin/rates

Retrieves current margin interest rates for all borrowable assets.

Returns hourly, daily, and annual borrow rates for each currency that can be borrowed on margin. Interest is charged on borrowed amounts at the hourly rate and compounds over time.

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.

Account Type

This endpoint is only available for margin trading accounts.

Get Margin Interest Rates › 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 Margin Interest Rates › Request Body

request

string · required

The literal string "/v1/margin/rates"

required

The nonce, as described in Private API Invocation

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

Get Margin Interest Rates › Responses

Current margin interest rates for all borrowable assets

object[] · required

Array of interest rates for all borrowable currencies

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

{ "rates": [ { "currency": "BTC", "borrowRate": "0.00001141552511", "borrowRateDaily": "0.00027397260264", "borrowRateAnnual": "0.1", "lastUpdated": 1700000000000 }, { "currency": "ETH", "borrowRate": "0.00001141552511", "borrowRateDaily": "0.00027397260264", "borrowRateAnnual": "0.1", "lastUpdated": 1700000000000 }, { "currency": "USD", "borrowRate": "0.00000913242009", "borrowRateDaily": "0.00021917808216", "borrowRateAnnual": "0.08", "lastUpdated": 1700000000000 } ] }

Preview Margin Order Impact

POST

https://api.sandbox.gemini.com

/v1/margin/order/preview

Previews the margin impact of a hypothetical spot order without actually placing it.

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.

Account Type

This endpoint is only available for margin trading accounts.

Preview Margin Order Impact › 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

Preview Margin Order Impact › Request Body

request

string · required

The literal string "/v1/margin/order/preview"

required

The nonce, as described in Private API Invocation

symbol

string · required

The trading pair symbol (e.g., "btcusd")

Example: btcusd

side

string · enum · required

The order side

Enum values:

buy

sell

Example: buy

type

string · enum · required

The order type

Enum values:

market

limit

Example: limit

amount

string · decimal

The order amount in base currency (required for limit orders and sell market orders)

Example: 0.5

price

string · decimal

The limit price (required for limit orders)

Example: 50000.00

totalSpend

string · decimal

Total spend in quote currency (required for buy market orders)

Example: 25000.00

account

string

Required for Master API keys as described in Private API Invocation. The name of the account within the subaccount group.

Preview Margin Order Impact › Responses

Pre-order and post-order margin risk statistics

object · required

curl --request POST \ --url https://api.sandbox.gemini.com/v1/margin/order/preview \ --header 'Content-Type: application/json' \ --header 'X-GEMINI-APIKEY: <string>' \ --header 'X-GEMINI-PAYLOAD: <string>' \ --header 'X-GEMINI-SIGNATURE: <string>' \ --data ' { "request": "/v1/margin/order/preview", "nonce": "<nonce>", "symbol": "btcusd", "side": "buy", "type": "limit", "amount": "0.5", "price": "50000.00" } '

{ "preorder": { "marginAssetValue": { "currency": "USD", "value": "10000.00" }, "availableCollateral": { "currency": "USD", "value": "8500.00" }, "notionalValue": { "currency": "USD", "value": "15000.00" }, "totalBorrowed": { "currency": "USD", "value": "5000.00" }, "leverage": "1.5", "reservedBuyOrders": { "currency": "USD", "value": "0.00" }, "reservedSellOrders": { "currency": "USD", "value": "0.00" }, "buyingPower": { "currency": "USD", "value": "8500.00" }, "sellingPower": { "currency": "USD", "value": "8500.00" } }, "postorder": { "marginAssetValue": { "currency": "USD", "value": "10000.00" }, "availableCollateral": { "currency": "USD", "value": "6000.00" }, "notionalValue": { "currency": "USD", "value": "40000.00" }, "totalBorrowed": { "currency": "USD", "value": "30000.00" }, "leverage": "4.0", "reservedBuyOrders": { "currency": "USD", "value": "0.00" }, "reservedSellOrders": { "currency": "USD", "value": "0.00" }, "buyingPower": { "currency": "USD", "value": "6000.00" }, "sellingPower": { "currency": "USD", "value": "6000.00" }, "liquidationRisk": { "lossPercentage": "0.6000", "liquidationPrice": { "currency": "USD", "value": "30000.00" } } } }