Guides
Start typing to search…

Partner - Create Settlements

Overview

Settlement between your partner platform and BitGo must occur during a pre-determined settlement window, typically once every 24 hours. At that time you create settlements for all trading that occurs on your platform. Settlements transfer assets off chain between your BitGo account to client BitGo accounts.

Signature and Verification

Settlement requests from you to BitGo must be cryptographically signed and verified to provide integrity, authenticity, and nonrepudiation. Use the BitGo JavaScript SDK or Express to sign the payload with the trading account private key.

Prerequisites

Use the following steps to generate a payload and send a signed settlement request.

1. Get Signing Payload

Add the externalId, settlementAmounts, and nonce attributes to the request.

Endpoint: Get Signing Payload for Partner Settlement

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"
}'
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 walletId = 'xyz123';
  const wallet = await bitgo.coin(coin).wallets().get({ id: walletId });
  const payload = {
    this: {
      is: {
        a: 'payload',
      },
    },
  };
  const walletPassphrase = getWalletPwFromEnv(wallet.id());
  const tradingAccount = wallet.toTradingAccount();
  const stringifiedPayload = JSON.stringify(req.body.payload);
  const signature = tradingAccount.signPayload({
    payload: stringifiedPayload,
    walletPassphrase,
  });

  console.log(`Signature: ${signature}`);
}

Step Result

{
  payload: string, // "{ \"this\": { \"is\": { \"a\": \"payload\" } } }"
}

2. Send Signed Settlement Payload

Endpoint: Perform Partner Settlement

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": {...},
  "signature": "<signature>"
}'

Step Result

{
  "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": "2025-11-11T19:12:37.874Z",
    "disputed": true
  }
}

Next

Deallocate Assets

See Also

API Reference: Perform Partner Settlement

Updated 13 days ago