Trade

Run the end-to-end Go Account trade workflow: place an order, track updates, get order details, and settle in testnet. See the Guide.

  1. View the trading pairs available for a Go Account before depositing assets. Depositing an unsupported asset may make it unrecoverable.

    API Reference

  2. Place a market, limit, or TWAP order from the Go Account. The example shows a market order. Set TRADING_PAIR to a pair from Step 1, such as TTRUMP-TUSD, and QUANTITY_CURRENCY to its base or quote currency. For a full breakdown of order types, fill behavior, and trading intent, see Place Trade Orders.

    API Reference

  3. Subscribe to the Trade WebSocket for live order and market data updates. To receive notifications when trades complete, subscribe to an organization-level trade webhook. This is a one-time setup. Your webhook receives two signals per completed trade: one at trade execution and one when settlement completes. Act on the first signal where status is "completed" and no settleDate is present.

    API Reference

  4. After receiving a trade completion webhook notification, retrieve the full order to get the fields you need: filledQuantity, filledQuoteQuantity, averagePrice, product, and side. Track processed order identifiers to prevent duplicate processing from webhook retries.

    API Reference

  5. In testnet, settle a completed trade by transferring part of the order balance to another Go Account. Settlement uses the same build-authenticate-send flow as any other Go Account transfer.

    Note

    In testnet, tsol:trump is the only asset you can settle. Testnet settlement is available in the US and EU regions, with automatic settlement capped at 100 tsol:trump per order.

    Build Transaction

    Build a wallet transfer from the source Go Account to the destination Go Account. For fee capture, transfer the calculated fee amount from the end user's Go Account to your collection Go Account. This is an internal ledger movement (book transfer) with no on-chain transaction.

    Important

    You must disclose to your end users that you charge a fee on top of the trade execution price.

    Calculate the fee based on the trade direction:

    • Buy (fiat to crypto): fee = (filledQuoteQuantity * feeBps / 10000) / averagePrice. The fee is denominated in the base token, such as BTC. Set COIN to the OFC-prefixed base asset, such as ofctbtc4.
    • Sell (crypto to fiat): fee = filledQuoteQuantity * feeBps / 10000. The fee is denominated in the quote token, such as USD. Set COIN to the OFC-prefixed quote asset, such as ofctusd.

    Pass the destination Go Account wallet ID as the value of the address field in the recipient object.

    API Reference

    Authenticate Transaction

    Use the Go Account passphrase to authenticate the transaction. To keep the passphrase off the internet, use BitGo Express in external-signing mode or the JavaScript SDK.

    Send Transaction

    Send the signed payload to BitGo. The halfSigned object takes the payload and signature returned by the previous step.

    API Reference

    Approve Transaction (Optional)

    If you configure an approval requirement for transfers, another admin must approve the transaction — you can't approve your own.

    API Reference

// 1. List Trading Pairs (Optional)
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export ACCOUNT_ID="<YOUR_GO_ACCOUNT_WALLET_ID>"
export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"

curl -X GET \
  "https://app.bitgo-test.com/api/prime/trading/v1/accounts/$ACCOUNT_ID/products" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 2. Place Trade Order
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export ACCOUNT_ID="<YOUR_GO_ACCOUNT_WALLET_ID>"
export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export TRADING_PAIR="<TRADING_PAIR>"
export QUANTITY_CURRENCY="<QUANTITY_CURRENCY>"

curl -X POST \
  "http://$BITGO_EXPRESS_HOST/api/prime/trading/v1/accounts/$ACCOUNT_ID/orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientOrderId": "myorder1",
    "type": "market",
    "product": "'"$TRADING_PAIR"'",
    "side": "buy",
    "quantity": "10000",
    "quantityCurrency": "'"$QUANTITY_CURRENCY"'"
  }'
// 3. Subscribe to Order Updates
export ORGANIZATION_ID="<YOUR_ORGANIZATION_ID>"
export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export URL="<YOUR_WEBHOOK_URL>"
export LABEL="<YOUR_WEBHOOK_NAME>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/organization/$ORGANIZATION_ID/webhook \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "type": "tradeOrder",
    "url": "'"$URL"'",
    "label": "'"$LABEL"'"
  }'
// 4. Get Order Details
export ACCOUNT_ID="<YOUR_GO_ACCOUNT_WALLET_ID>"
export ORDER_ID="<ORDER_ID_FROM_WEBHOOK>"
export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"

curl -X GET \
  "https://app.bitgo-test.com/api/prime/trading/v1/accounts/$ACCOUNT_ID/orders/$ORDER_ID" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
// 5. Settle Trade
export COIN="<ASSET_ID>"
export WALLET_ID="<SOURCE_GO_ACCOUNT_WALLET_ID>"
export ACCESS_TOKEN="<SERVICE_USER_ACCESS_TOKEN>"
export AMOUNT="<AMOUNT_IN_BASE_UNITS>"
export ADDRESS="<DESTINATION_GO_ACCOUNT_WALLET_ID>"

// 5.1 Build Transaction
curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/tx/build \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "recipients": [
      {
        "amount": "'"$AMOUNT"'",
        "address": "'"$ADDRESS"'"
      }
    ]
}'

// 5.2 Authenticate Transaction
export BITGO_EXPRESS_HOST="<YOUR_LOCAL_HOST>"
export WALLET_PASSPHRASE="<YOUR_GO_ACCOUNT_PASSPHRASE>"
export PAYLOAD="<PAYLOAD_FROM_BUILD_STEP>"

curl -X POST \
  http://$BITGO_EXPRESS_HOST/api/v2/ofc/signPayload \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "walletId": "'"$WALLET_ID"'",
    "walletPassphrase": "'"$WALLET_PASSPHRASE"'",
    "payload": "'"$PAYLOAD"'"
  }'

// 5.3 Send Transaction
export SIGNATURE="<SIGNATURE_FROM_AUTH_STEP>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/$COIN/wallet/$WALLET_ID/tx/send \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "halfSigned": {
      "payload": "'"$PAYLOAD"'",
      "signature": "'"$SIGNATURE"'"
    }
  }'

// 5.4 Approve Transaction (Optional)
export APPROVAL_ID="<APPROVAL_ID>"
export OTP="<OTP>"

curl -X PUT \
  https://app.bitgo-test.com/api/v2/pendingApprovals/$APPROVAL_ID \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "state": "approved",
    "otp": "'"$OTP"'"
  }'
Response
// 1. List Trading Pairs (Optional) Response
{
  "data": [
    {
      "id": "0d75f716-680b-11eb-a7a5-0a34d7f8426c",
      "name": "TTRUMP-TUSD",
      "baseCurrencyId": "8a93fece-6878-4b27-88eb-a83a40af0318",
      "baseCurrency": "TTRUMP",
      "quoteCurrencyId": "e708df52-ba80-42cd-868c-5dab42fe6bac",
      "quoteCurrency": "TUSD",
      "baseMinSize": "",
      "baseMaxSize": "",
      "baseIncrement": "0.000001",
      "quoteMinSize": "10",
      "quoteIncrement": "0.01",
      "quoteDisplayPrecision": 4,
      "isTradeDisabled": false,
      "isMarginTradeSupported": true
    }
  ]
}

// 2. Place Trade Order Response
{
  "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": "funded",
  "type": "market",
  "status": "completed",
  "product": "TTRUMP-TUSD",
  "side": "buy",
  "quantity": "1000",
  "quantityCurrency": "TUSD",
  "filledQuantity": "0.02457152",
  "averagePrice": "40697.32"
}

// 4. Get Order Details Response
{
  "id": "67fd640c-cb6c-4218-80ae-49e79ec15646",
  "accountId": "60e740e7898f7d00064d43769a73dc48",
  "clientOrderId": "myorderid1",
  "completionDate": "2021-08-05T18:05:23.431Z",
  "settleDate": "2021-08-05T20:00:00.000Z",
  "fundingType": "funded",
  "type": "market",
  "status": "completed",
  "product": "TTRUMP-TUSD",
  "side": "buy",
  "quantity": "1000",
  "quantityCurrency": "TUSD",
  "filledQuantity": "0.02457152",
  "filledQuoteQuantity": "1000",
  "averagePrice": "40697.32"
}

// 5.1 Build Transaction Response
{
  "payload": "<PAYLOAD_FROM_BUILD_STEP>",
  "feeInfo": {
    "feeString": "0"
  },
  "coin": "ofc",
  "token": "ofctsol:trump"
}

// 5.2 Authenticate Transaction Response
{
  "coin": "ofctsol:trump",
  "payload": "<PAYLOAD_FROM_BUILD_STEP>",
  "signature": "<SIGNATURE_FROM_AUTH_STEP>"
}

// 5.3 Send Transaction Response
{
  "transfer": {
    "id": "65155c4a72fddb000774edbee5fa75fd",
    "coin": "ofctsol:trump",
    "wallet": "6a57cf1c41a5e2087587970efd1db9ef",
    "type": "send",
    "state": "signed"
  },
  "tx": {
    "transactionType": "BOOK_TRANSFER"
  },
  "status": "signed"
}