Settle

Create Settlements

Overview

When you're done trading, create multi-asset settlements with your counterparties. Either party can initiate a settlement. However, both parties must acknowledge a settlement before it finalizes and assets transfer between Go Accounts. Settlements can only occur between partners who connect Go Accounts, using the Counterparties.

Prerequisites

Cookbook

Need just the steps? Expand the cookbook below to get started:

Create SettlementsOpen Cookbook

1. Create Settlement

The addressBookConnectionId and addressBookConnectionUpdatedAt timestamp identify your counterparty for the settlement. If you need to find these values, you can call the Lists counterparty Go Account connections endpoint.

Endpoint: Create settlement

export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export CONNECTION_ID="<CONNECTION_ID>"
export CONNECTION_UPDATED_AT="<CONNECTION_UPDATED_AT>"
export COUNTERPARTY_ACCOUNT_ID="<COUNTERPARTY_ACCOUNT_ID>"
export CURRENCY="<SENDING_ASSET>"
export QUANTITY="<SENDING_QUANTITY>"
export EXTERNAL_ID="<YOUR_EXTERNAL_ID>"

curl -X POST \
  https://app.bitgo-test.com/api/clearing/v1/enterprise/$ENTERPRISE_ID/account/$ACCOUNT_ID/settlement \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "externalId": "'"$EXTERNAL_ID"'",
    "addressBookConnectionId": "'"$CONNECTION_ID"'",
    "addressBookConnectionUpdatedAt": "'"$CONNECTION_UPDATED_AT"'",
    "assetTransfers": [
      {
        "currency": "'"$CURRENCY"'",
        "quantity": "'"$QUANTITY"'"
      }
    ]
  }'

Step Result

{
  "approvalRequests": [
    {
      "createdAt": "2019-08-24",
      "updatedAt": "2019-08-24",
      "id": "23d3e6c5-72d2-41e8-9e79-8d7e09a19b74",
      "accountId": "yourAccountId",
      "status": "acknowledged",
      "payload": "{\"nonce\":\"216c7312-5af8-463a-963d-8a91535b7ed5\",\"version\":\"3.0.0\",\"signerAccount\":\"yourAccountId\",\"settlementTransfers\":[{\"id\":\"b5f1ab55-b510-4bf6-92cd-214a7e23321\",\"sourceTradingAccountId\":\"yourAccountId\",\"destinationTradingAccountId\":\"counterpartiesAccountId\",\"currency\":\"$CURRENCY\",\"quantity\":\"$QUANTITY\"}]}",
    },
    {
      "createdAt": "2019-08-24",
      "updatedAt": "2019-08-24",
      "id": "54586c2b-adfd-40bd-8115-ea3a37f3f4df",
      "accountId": "counterpartiesAccountId",
      "status": "initialized",
      "payload":  "{\"nonce\":\"d51a9909-0b25-4ebc-b864-eba6e76e77d1\",\"version\":\"3.0.0\",\"signerAccount\":\"counterpartiesAccountId\",\"settlementTransfers\":[{\"id\":\"b5f1ab55-b510-4bf6-92cd-214a7e23321\",\"sourceTradingAccountId\":\"yourAccountId\",\"destinationTradingAccountId\":\"counterpartiesAccountId\",\"currency\":\"$CURRENCY\",\"quantity\":\"$QUANTITY\"}]}",
    }
  ],
  "settlementTransfers": [
    {
      "id": "b5f1ab55-b510-4bf6-92cd-214a7e23321",
      "sourceTradingAccountId": "yourAccountId",
      "destinationTradingAccountId": "counterpartiesAccountId",
      "currency":"$CURRENCY",
      "quantity":"$QUANTITY",
      "txIds": [],
      "createdAt": "2019-08-24",
      "updatedAt": "2019-08-24"
    }
  ],
  "requesterAccountName": "string",
  "bypassCounterpartySigning": false,
  "createdAt": "2019-08-24",
  "updatedAt": "2019-08-24",
  "id": "string", // settlementId for signing
  "externalId": "string",
  "requesterAccountId": "string",
  "status": "pending",
  "type": "direct"
}

2. Sign Settlement (Optional)

If you're sending assets in the settlement, you must sign the settlement to confirm the transaction. However, if you're only receiving assets in a settlement, signing is optional.

2.1 Apply Signature

import { BitGoAPI } from '@bitgo/sdk-api';
import { coins } from '@bitgo/sdk-core';

const OFC_WALLET_ID = process.env.OFC_WALLET_ID;
const payload = process.env.PAYLOAD;
const walletPassphrase = process.env.OFC_WALLET_PASSPHRASE;

const bitgo = new BitGoAPI({
  accessToken: process.env.TESTNET_ACCESS_TOKEN,
  env: 'test',
});

const coin = 'ofc';
bitgo.register(coin, coins.Ofc.createInstance);

async function main() {
  const wallet = await bitgo.coin('ofc').wallets().get({ id: OFC_WALLET_ID });

  console.log('Wallet:', wallet);

  const tradingAccount = wallet.toTradingAccount();

  const signature = await tradingAccount.signPayload({payload, walletPassphrase});

  console.log('Signature:', signature);
}

main().catch((e) => console.error(e));

Substep Result

"1f2f62b22832940d82819eccc9e2fbcb5339ae863bc9fba4d6cc62f01550fc325a7e007fb8b753d0e862145e716d4a6054f75c2da2b7c2ac5d41679683a4996349"

2.2 Submit Signed Settlement

Endpoint: Sign settlement

export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>"
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export SETTLEMENT_ID="<SETTLEMENT_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export PAYLOAD="<SETTLEMENT_PAYLOAD>"
export SIGNATURE="<YOUR_PUBLIC_KEY>"

curl -X POST \
  https://app.bitgo-test.com/api/clearing/v1/enterprise/$ENTERPRISE_ID/account/$ACCOUNT_ID/settlement/$SETTLEMENT_ID/signing \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "payload": "'"$PAYLOAD"'",
    "signature": "'"$SIGNATURE"'"
  }'

Substep Result

Signing a settlement places the assets in your Go Account into a held state, preventing them from use in other transactions. If your Go Account has an insufficient balance to cover the settlement, then BitGo rejects the request.

Note: If the signing fails for any reason, the settlement cancels.

{}

3. Approve Settlement (Optional)

Note: If you configure an approval requirement for settlements, you can't approve a settlement you initiated - another admin must always approve it.

Endpoint: Update Pending Approval

export APPROVAL_ID="<APPROVAL_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export OTP="<YOUR_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"'"
  }'

Step Result

{
    "id": "65529448bd87efe59c3b0156ddfce867",
    "coin": "tbtc4",
    "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
    "enterprise": "62c5ae8174ac860007aff138a2d74df7",
    "creator": "62ab90e06dfda30007974f0a52a12995",
    "createDate": "2023-11-13T21:25:28.022Z",
    "info": {
        "type": "transactionRequest",
        "transactionRequest": {
            "requestedAmount": "10000",
            "fee": 20451,
            "sourceWallet": "654ec786c07fe8dc0dcfe03916ec5bb0",
            "policyUniqueId": "654ec786c07fe8dc0dcfe03f",
            "recipients": [
                {
                    "address": "2N1UvKhtSHLUa9YomSH7n9YMFCkMG2pbmsQ",
                    "amount": "10000",
                    "_id": "65529448bd87efe59c3b0158"
                }
            ],
            "coinSpecific": {
                "tbtc4": {
                    "txHex": "010000000001010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000023220020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467dafffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e626983990500483045022100db45a8d94ee2144f7e29baa855d94a2bf0120707a7ab2fc93734ed94af972c460220558d00b91275aafc7805dfaaf9ab796adbe9f4e66dc467f7eb93b790671a323201000069522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae00000000"
                }
            },
            "validTransaction": "010000000001010e4d3af014f9efe311062965d561b67f78a1759e7016605cd506ddd7041762d50000000023220020510ded26d712922bbb61bc68ef6766f836a03527820cbdc8b1551914eb467dafffffffff02102700000000000017a9145a581567fd2a630e61e34a696ab3bb887972886d87ad0f010000000000225120850d0ab466d15cb1565dd528d4d9709f3e46f41d41fe6d94aa01378e626983990400483045022100db45a8d94ee2144f7e29baa855d94a2bf0120707a7ab2fc93734ed94af972c460220558d00b91275aafc7805dfaaf9ab796adbe9f4e66dc467f7eb93b790671a323201473044022049e20c0073f42c9636408efc6c833ebf0e1a8ef13e8cb818dde2f4e2af7f7b7f022000cb3a321d65605b9d51d7f87e34306169607646c8d54a44011b021eff3dbe500169522103c10ac628c880629ed0fd2a0563a898f4882baca45e15668a4d3064cf1ea379882103e56f84be4460080618ef869bb7b07096880760f748ba23efab533c2359f923bd21020ae81372264b5eac5c9dc7fe0b9a32bad00771c3a2c71f6e2c971823c3182ed653ae00000000",
            "validTransactionHash": "5ea8d2b93997ed9fa3597a2f3113817c8216f573a0278c2533bb5db50fdb0dff"
        }
    },
    "state": "approved",
    "scope": "wallet",
    "userIds": [
        "62ab90e06dfda30007974f0a52a12995",
        "621d08a634ad8a0007fcddffd7c429cc"
    ],
    "approvalsRequired": 1,
    "singleRunResults": [
        {
            "ruleId": "Custody Enterprise Transaction ID Verification",
            "triggered": false,
            "_id": "65529448bd87efe59c3b0157"
        }
    ],
    "resolvers": [
        {
            "user": "621d08a634ad8a0007fcddffd7c429cc",
            "date": "2023-11-13T21:44:27.794Z",
            "resolutionType": "pending"
        }
    ]
}

See Also