Ctrl+K

Create Settlements

Overview

At least once every 24 hours you must 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
  • JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X POST http://$BITGO_EXPRESS_HOST:3080/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"
      }
    }
  }
}'

Step Result

  • JSON
1
2
3
4
5

{
  payload: string, // "{ \"this\": { \"is\": { \"a\": \"payload\" } } }"
  signature: string // "20169c2c4201aa95c312bbb4293998e..."
}

2. Send Settlement Payload

Endpoint: Perform Partner Settlement

  • cURL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -X POST http://$BITGO_EXPRESS_HOST:3080/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

  • JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  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