Guides
Start typing to search…
  1. Use-Case Guides
  2. Crypto-as-a-Service

Margin Trade

Overview

Trading on margin allows CaaS end users to execute trades beyond the balance of their Go Account. After transferring funds from a Go Account into a Collateral Account, they can trade using a Margin Trading Account.

Accepted collateral assets: USD, USDT, USDC, BTC.

Trades are subject to Net Open Position (NOP) limits. Trading by API is rate-limited to 10 requests per second. Trade orders in testnet are confirmed but not settled — settlement only occurs in production.

Prerequisites

1. Fund Collateral Account

Transfer assets from the Go Account to the Collateral Account. Once transferred, assets are locked — withdrawal requires contacting [email protected].

Endpoint: Transfer Collateral for Margin

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export CURRENCY="<ASSET_ID>"
export QUANTITY="<AMOUNT_IN_BASE_UNITS>"
curl -X POST \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/collateral/transfer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
        "currency": "'"$CURRENCY"'",
        "quantity": "'"$QUANTITY"'"
      }'

Step Result

{
  "currency": "BTC",
  "quantity": "2",
  "balanceValue": {
    "quantity": "1000000",
    "currency": "USD"
  }
}

2. Place Margin Order

Margin orders withdraw from the Margin Trade Account instead of the Go Account. BitGo runs a NOP check before execution. If a trade causes the account to violate margin limits, further trades are blocked until the account returns to a healthy state.

All order types are supported: Market, Limit, and TWAP. The key difference from funded trades is setting "fundingType": "margin" in the request body.

Endpoint: Place Order

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X POST \
    https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/orders \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{
           "clientOrderId": "myorder1",
           "type": "market",
           "product": "TBTC-TUSD*",
           "fundingType": "margin",
           "side": "buy",
           "quantity": "10000",
           "quantityCurrency": "TUSD*"
         }'
export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X POST \
    https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/orders \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{
           "clientOrderId": "myorder1",
           "type": "limit",
           "product": "TBTC-TUSD*",
           "fundingType": "margin",
           "side": "buy",
           "quantity": "1",
           "quantityCurrency": "TBTC",
           "limitPrice": "10005",
           "duration": 60
         }'
export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X POST \
    https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/orders \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{
           "clientOrderId": "myorder1",
           "type": "twap",
           "product": "TBTC-TUSD*",
           "fundingType": "margin",
           "side": "buy",
           "quantity": "100000",
           "quantityCurrency": "TUSD*",
           "duration": 60,
           "interval": 5
         }'

Step Result

{
  "id": "67fd640c-cb6c-4218-80ae-49e79ec15646",
  "accountId": "60e740e7898f7d00064d43769a73dc48",
  "clientOrderId": "myorderid1",
  "time": "2021-08-05T18:05:23.431Z",
  "creationDate": "2021-08-05T18:05:22.286Z",
  "scheduledDate": "2021-08-05T18:05:00.000Z",
  "lastFillDate": "2021-08-05T18:05:23.302Z",
  "completionDate": "2021-08-05T18:05:23.431Z",
  "settleDate": "2021-08-05T20:00:00.000Z",
  "fundingType": "margin",
  "type": "market",
  "status": "completed",
  "product": "TBTC-TUSD*",
  "side": "buy",
  "quantity": "1000",
  "quantityCurrency": "TUSD*",
  "filledQuantity": "0.02457152",
  "averagePrice": "40697.32"
}

3. Cover Short Positions

When selling assets purchased with margin funds, you have an open short position. Cover short positions by buying back assets to reduce the amount owed. You can cover by specific asset or cover all positions.

Endpoint: Cover Short Positions

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X POST \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/positions/cover \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
        "all": true
      }'
export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export CURRENCIES="<ASSET_ID>"
curl -X POST \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/positions/cover \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
        "currencies": ["'"$CURRENCIES"'"]
      }'

4. Close Positions

Close open positions by asset or close all. When closing all, BitGo starts an async process to buy and sell assets to net positions to zero.

Endpoint: Close All Margin Positions

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X POST \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/positions/close \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
        "all": true
      }'
export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export CURRENCIES="<ASSET_ID>"
curl -X POST \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/positions/close \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
        "currencies": ["'"$CURRENCIES"'"]
      }'

5. View Positions and Risk

Risk Profile

The risk profile helps you make trading decisions to prevent margin calls or liquidation. It includes the following values:

  • Net Open Position — The total value of open positions.
  • Collateral — Assets posted as collateral.
  • Unrealized PnL — Profit or loss on open positions that have not yet been settled.
  • Margin Balance — The effective balance available for margin trading.
  • Margin Requirement — The minimum margin required to hold open positions.
  • Margin Utilization Percentage — The percentage of available margin currently in use.

Endpoint: Get Margin Risk Profile

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X GET \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/risk/profile \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Step Result

{
  "netOpenPosition": {
    "quantity": "5000.00",
    "currency": "USD"
  },
  "collateral": {
    "quantity": "10000.00",
    "currency": "USD"
  },
  "unrealizedPnl": {
    "quantity": "-200.00",
    "currency": "USD"
  },
  "marginBalance": {
    "quantity": "9800.00",
    "currency": "USD"
  },
  "marginRequirement": {
    "quantity": "500.00",
    "currency": "USD"
  },
  "marginUtilizationPercentage": "5.10"
}

Risk Settings

Risk settings are limits set by BitGo for your account:

  • Total Short Position Limit — The maximum total value of short positions allowed.
  • Margin Call Percentage — The margin utilization level at which a margin call is issued.
  • Liquidation Threshold Percentage — The margin utilization level at which positions are liquidated.
  • Margin Requirement Percentage — The percentage of position value required as margin.

Endpoint: Get Margin Risk Settings

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X GET \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/risk/settings \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Step Result

{
  "totalShortPositionLimit": {
    "quantity": "100000.00",
    "currency": "USD"
  },
  "marginCallPercentage": "80.00",
  "liquidationThresholdPercentage": "95.00",
  "marginRequirementPercentage": "10.00"
}

Net Open Positions

Endpoint: Get Net Open Margin Position

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X GET \
  https://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/margin/positions \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Step Result

{
  "data": [
    {
      "currency": "BTC",
      "quantity": "0.5",
      "value": {
        "quantity": "20000.00",
        "currency": "USD"
      }
    },
    {
      "currency": "ETH",
      "quantity": "-2.0",
      "value": {
        "quantity": "-6000.00",
        "currency": "USD"
      }
    }
  ]
}

See Also

Updated 6 days ago