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. The API rate-limits trading to 10 requests per second. In testnet, BitGo confirms trade orders but does not settle them — settlement only occurs in production.

Note

Margin trading through CaaS is currently only available for end users who are business entities. This feature isn't available for end users who are individuals.

Prerequisites

1. Fund Collateral Account

Transfer assets from the Go Account to the Collateral Account. Once transferred, assets remain locked — withdrawal requires contacting support@bitgo.com.

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 \
  http://$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, BitGo blocks further trades until the account returns to a healthy state.

Margin trading supports all order types: Market, Limit, TWAP, and Stop. The key difference from funded trades is setting "fundingType": "margin" in the request body. Stop orders also require a triggerPrice. When you include a limitPrice, the order executes as a stop limit; when you omit it, the order executes as a stop market.

Note

For the complete validation matrix and field-by-field rules for stop orders, see Place Trade Orders.

Endpoint: Place Order

export BITGO_EXPRESS_HOST="<YOUR_LOCALHOST>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
curl -X POST \
    http://$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*"
         }'

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 \
  http://$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
      }'

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 \
  http://$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
      }'

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 settlement has not yet finalized.
  • 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 \
  http://$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

BitGo configures risk settings as limits for your account:

  • Total Short Position Limit — The maximum total value of short positions allowed.
  • Margin Call Percentage — The margin utilization level at which BitGo issues a margin call.
  • Liquidation Threshold Percentage — The margin utilization level at which BitGo liquidates positions.
  • 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 \
  http://$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 \
  http://$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