Off-Exchange Settlement: Create Settlements - Partner (Without Disputes)
Create settlements for trading activity on your platform and send signed requests to BitGo. Use this cookbook when disputes are not enabled for your integration. See the Guide.
-
You request a signing payload from BitGo for the settlement. This payload must be cryptographically signed with your trading account private key to provide integrity, authenticity, and nonrepudiation. Settlement typically occurs during a pre-determined window, usually once every 24 hours.
Prerequisites: Client trading must have occurred on your platform, and you must have allocated and connected clients.
-
You send the signed settlement payload to BitGo to complete the settlement. This transfers assets off-chain between your BitGo account and client BitGo accounts for all trading that occurred on your platform. BitGo processes settlement synchronously and the response has a
statusofcompletedorfailedif there were insufficient client allocated balances or partner Go Account balances to process the settlement. Once funding is in place you can make the exact same call again to post the settlement and BitGo will retry and respond with the updated settlement.
// 1. Get Signing Payload
curl -X GET http://$BITGO_EXPRESS_HOST/api/network/v1/enterprises/{enterpriseId}/partners/settlements-signing \
-H "Authorization: Bearer v123xyz..." \
-H "Content-Type: application/json" \
-d '{
"externalId": "string",
"notes": "string",
"settlementAmounts": {
"additionalProp": {
"additionalProp": "string"
}
},
"nonce": "string"
}'
// 2. Send Signed Settlement Payload
curl -X POST http://$BITGO_EXPRESS_HOST/api/network/v1/enterprises/{enterpriseId}/partners/settlements \
-H "Content-Type: application/json" \
-d '{
"externalId": "idForSettlementAtPartner",
"notes": "this is a settlement note",
"settlementAmounts": {
"09684b38-49ed-4cf6-a28e-c3a459494c69": {
"BTC": "100",
"ETH": "-200"
},
"136c1c69-8654-484f-8c5f-591b334a084f": {
"XRP": "300",
"BTC": "-400"
}
},
"nonce": "1",
"payload": "<payload string from step 1>",
"signature": "<signature>"
}'
import superagent from 'superagent';
import { BitGoAPI } from '@bitgo/sdk-api';
import { coins } from '@bitgo/sdk-core';
require('dotenv').config({ path: '../../.env' });
const bitgo = new BitGoAPI({
accessToken: process.env.TESTNET_ACCESS_TOKEN,
env: 'test',
});
const coin = 'ofc';
bitgo.register(coin, coins.Ofc.createInstance);
function getWalletPwFromEnv(walletId: string): string {
const name = `WALLET_${walletId}_PASSPHRASE`;
const walletPw = process.env[name];
if (walletPw === undefined) {
throw new Error(`Could not find wallet passphrase ${name} in environment`);
}
return walletPw;
}
async function main() {
const enterpriseId = '<YOUR_ENTERPRISE_ID>';
const walletId = 'xyz123';
const wallet = await bitgo.coin(coin).wallets().get({ id: walletId });
const walletPassphrase = getWalletPwFromEnv(wallet.id());
const tradingAccount = wallet.toTradingAccount();
const settlementBody = {
externalId: 'idForSettlementAtPartner',
notes: 'this is a settlement note',
settlementAmounts: {
'09684b38-49ed-4cf6-a28e-c3a459494c69': {
BTC: '100',
ETH: '-200',
},
'136c1c69-8654-484f-8c5f-591b334a084f': {
XRP: '300',
BTC: '-400',
},
},
nonce: '1',
};
// 1. Get Signing Payload
const signingResponse = await superagent
.get(`${process.env.BITGO_EXPRESS_HOST}/api/network/v1/enterprises/${enterpriseId}/partners/settlements-signing`)
.set('Authorization', `Bearer ${process.env.TESTNET_ACCESS_TOKEN}`)
.set('Content-Type', 'application/json')
.send(settlementBody);
const { payload } = signingResponse.body;
// 2. Sign the payload
const signature = tradingAccount.signPayload({
payload,
walletPassphrase,
});
// 3. Send Signed Settlement Payload
const settlementResponse = await superagent
.post(`${process.env.BITGO_EXPRESS_HOST}/api/network/v1/enterprises/${enterpriseId}/partners/settlements`)
.set('Content-Type', 'application/json')
.send({
...settlementBody,
payload,
signature,
});
console.log('Settlement:', settlementResponse.body);
}
// 1. Get Signing Payload Response
{
"payload": "{ \"externalId\": \"idForSettlementAtPartner\", \"settlementAmounts\": { \"09684b38-49ed-4cf6-a28e-c3a459494c69\": { \"BTC\": \"100\", \"ETH\": \"-200\" }, \"136c1c69-8654-484f-8c5f-591b334a084f\": { \"XRP\": \"300\", \"BTC\": \"-400\" } }, \"nonce\": \"1\" }"
}
// 2. Send Signed Settlement Payload Response
{
"settlement": {
"id": "string",
"partnerId": "string",
"externalId": "string",
"status": "completed",
"settlementType": "onchain",
"reconciled": true,
"initiatedBy": "string",
"notes": "string",
"createdAt": "2025-11-11T19:12:37.874Z",
"updatedAt": "2025-11-11T19:12:37.874Z",
"finalizedAt": "2025-11-11T19:12:37.874Z",
"rtId": "string",
"lossSLAAlertSent": true,
"gainSLAAlertSent": true,
"cutoffAt": null,
"disputed": false
}
}