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 signature and send a signed settlement request.

1. Sign Settlement Payload

Add the payload, signature, and nonce attributes to the request and sign the payload.

Endpoint: Perform Partner Settlement

curl -X POST http://$BITGO_EXPRESS_HOST/api/network/v1/enterprises/{enterpriseId}/partners/settlements \
curl -X POST /api/v2/ofc/signPayload \
-H "Authorization: Bearer v123xyz..." \
-H "Content-Type: application/json" \
-d '{
  "walletId": "6407b22ec86799000706e578332735a3",
  "payload": {
    "this": {
      "is": {
        "a": "payload"
      }
    }
  }
}'
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\" } } }"
  signature: string // "20169c2c4201aa95c312bbb4293998e..."
}

2. Send 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: 'ea4b2f0b-de79-4664-91f9-79a30475ba10',
    partnerId: 'b5ea2e6e-4430-44fa-8dc1-bf3cb21463d0',
    externalId: 'idForSettlementAtPartner',
    cutoffAt: '2023-01-26T00:31:26+0000',
    reason: null,
    status: 'completed',
    reconciled: false,
    notes: 'this is a settlement note',
    createdAt: '2024-05-07T13:00:01.131Z',
    updatedAt: '2024-05-07T13:00:01.131Z',
  }
}

Next

Deallocate Assets

See Also

API Reference: Perform Partner Settlement

Updated 1 day ago