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.
-
View the trading pairs available for a Go Account before depositing assets. Depositing an unsupported asset may make it unrecoverable.
-
Place a market, limit, or TWAP order from the Go Account. The example shows a market order. Set
TRADING_PAIRto a pair from Step 1, such asTTRUMP-TUSD, andQUANTITY_CURRENCYto its base or quote currency. For a full breakdown of order types, fill behavior, and trading intent, see Place Trade Orders. -
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
statusis"completed"and nosettleDateis present. -
After receiving a trade completion webhook notification, retrieve the full order to get the fields you need:
filledQuantity,filledQuoteQuantity,averagePrice,product, andside. Track processed order identifiers to prevent duplicate processing from webhook retries. -
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:trumpis the only asset you can settle. Testnet settlement is available in the US and EU regions, with automatic settlement capped at 100tsol:trumpper 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. SetCOINto the OFC-prefixed base asset, such asofctbtc4. - Sell (crypto to fiat):
fee = filledQuoteQuantity * feeBps / 10000. The fee is denominated in the quote token, such as USD. SetCOINto the OFC-prefixed quote asset, such asofctusd.
Pass the destination Go Account wallet ID as the value of the
addressfield in the recipient object.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
halfSignedobject takes thepayloadandsignaturereturned by the previous step.Approve Transaction (Optional)
If you configure an approval requirement for transfers, another admin must approve the transaction — you can't approve your own.
- Buy (fiat to crypto):
// 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"'"
}'
// 1. List Trading Pairs (Optional)
// Use the REST API for this step (see cURL tab)
// 2. Place Trade Order
// Use the REST API for this step (see cURL tab)
// 3. Subscribe to Order Updates
// Use the REST API for this step (see cURL tab)
// 4. Get Order Details
// Use the REST API for this step (see cURL tab)
// 5. Settle Trade
// 5.1 Build Transaction
const transaction = await wallet.prebuildTransaction({
recipients: [
{
amount: '<AMOUNT_IN_BASE_UNITS>',
address: '<DESTINATION_GO_ACCOUNT_WALLET_ID>',
},
],
});
// 5.2 Authenticate Transaction
const walletPassphrase = '<YOUR_GO_ACCOUNT_PASSPHRASE>';
const tradingAccount = wallet.toTradingAccount();
const stringifiedPayload = '<PAYLOAD_FROM_BUILD_STEP>';
const signature = await tradingAccount.signPayload({
payload: stringifiedPayload,
walletPassphrase,
});
// 5.3 Send Transaction
const sendUrl = wallet.baseCoin.url('/wallet/' + wallet.id() + '/tx/send');
await bitgo
.post(sendUrl)
.send({ halfSigned: { payload: stringifiedPayload, signature } })
.result();
// 5.4 Approve Transaction (Optional)
const baseCoin = bitgo.coin(initialPendingApproval.coin);
const pendingApproval = await baseCoin.pendingApprovals().get({ id: initialPendingApproval.id });
const result = await pendingApproval.approve(params);
// 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"
}