Guides

Automatic Fund Conslidation

Suggest Edits

Once a deposit is successful, it will run through an auto consolidation phase, moving the funds from the deposit address to a central pooled wallet, meaning funds arent left spread across multiple wallets. If this is the first deposit of this cryptocurrency type to the asset pool, a master wallet will be automatically created

Auto-creation of a Master Pooling Wallet

The following webhook of event type layer1:digital:address:created is intially sent once the despoist has been updated to SUCCESS:

{
  "event": "layer1:digital:address:created",
  "timestamp": "2024-06-05T20:40:31.443861137Z",
  "data": {
    "id": "8e1fcdb5-8edc-49b7-9289-1c41c5bcd818",
    "address": "0x96073c4b415d60ade18de32e43efc2914731e03d",
    "network": "ETHEREUM",
    "keyPairId": "fdc9f5a0-698c-4163-ab21-df85f343a2a4",
    "reference": "AssetPoolTwo",
    "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
  }
}

the address 0x96073c4b415d60ade18de32e43efc2914731e03d is now set up for funds to be swept into.

The Balance Updated Webhook

When auto-consolidation takes place, the balance will be updated for the deposit address, as well as the new master address. Three balance updated webooks will be received during consolidation.


  1. The funds-reserved Balance Update, which shows the amount actioned in the consolidation move from AVAILABLE to RESERVED in the original deposit address.
  2. The new funds-available Balance Update, which shows the funds have been received by the new master address as shown in the AVAILABLE section. Note it is slightly less due to network fees.
  3. The funds-released Balance Update, which shows the amount released from the RESERVED section and the BLOCKCHAIN section once the consolidation has been successful. Note the small leftover funds or 'dust'.

Balance Updated Webhook Example

{
  "event": "layer1:digital:balance:updated",
  "timestamp": "2024-06-05T20:40:31.641988100Z",
  "data": {
    "reference": "First Eth Address",
    "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
    "asset": "ETH",
    "funds": [
      {
        "type": "AVAILABLE",
        "balance": "0.00",
        "delta": "-0.20"
      },
      {
        "type": "BLOCKCHAIN",
        "balance": "0.20",
        "delta": "0.00"
      },
      {
        "type": "RESERVED",
        "balance": "0.20",
        "delta": "0.20"
      }
    ]
  }
}

{
  "event": "layer1:digital:balance:updated",
  "timestamp": "2024-06-05T20:41:27.349393331Z",
  "data": {
    "reference": "AssetPoolTwo",
    "address": "0x96073c4b415d60ade18de32e43efc2914731e03d",
    "asset": "ETH",
    "funds": [
      {
        "type": "AVAILABLE",
        "balance": "0.199630313934810125",
        "delta": "0.199630313934810125"
      },
      {
        "type": "BLOCKCHAIN",
        "balance": "0.199630313934810125",
        "delta": "0.199630313934810125"
      },
      {
        "type": "RESERVED",
        "balance": "0.00",
        "delta": "0.00"
      }
    ]
  }
}

{
  "event": "layer1:digital:balance:updated",
  "timestamp": "2024-06-05T20:41:27.341091297Z",
  "data": {
    "reference": "First Eth Address",
    "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
    "asset": "ETH",
    "funds": [
      {
        "type": "AVAILABLE",
        "balance": "0.000058795984828875",
        "delta": "0.000058795984828875"
      },
      {
        "type": "BLOCKCHAIN",
        "balance": "0.000058795984828875",
        "delta": "-0.199941204015171125"
      },
      {
        "type": "RESERVED",
        "balance": "0.00",
        "delta": "-0.20"
      }
    ]
  }
}

The Consolidation Status Change Webhooks

These webhooks are sent out to inform about the current status of the consolidation of funds from one address you own, to another address in the same asset pool, this means there could be duplicates of the same type of webhook, but from different addresses so pay special attention to these in the webhook. There are Seven (or ten) update webhooks expected during the consolidation phase:

  1. CREATED
  2. FUNDS_RESERVED
  3. SIGNED
  4. DETECTED - two webhooks, one for each of the addresses
  5. UNCONFIRMED - two webhooks, one for each of the addresses
  6. CONFIRMED - two webhooks, one for each of the addresses
  7. SUCCESS

Status Change Webhook Examples

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:40:31.722661928Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b7d18a869f191944a09e5e784d7ca8f45a69",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.20",
    "status": "CREATED",
    "address": {
      "id": "d18a869f-1919-44a0-9e5e-784d7ca8f45a",
      "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
      "network": "ETHEREUM",
      "keyPairId": "44cf54df-93e9-4dd9-84c9-e96f0cf90f3e",
      "reference": "First Eth Address",
      "customerId": "customerOne",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.20",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:40:31.692479Z",
    "destinations": [
      {
        "amount": "0.20",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ]
  }
}

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:40:31.872516799Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b7d18a869f191944a09e5e784d7ca8f45a69",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.20",
    "status": "FUNDS_RESERVED",
    "address": {
      "id": "d18a869f-1919-44a0-9e5e-784d7ca8f45a",
      "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
      "network": "ETHEREUM",
      "keyPairId": "44cf54df-93e9-4dd9-84c9-e96f0cf90f3e",
      "reference": "First Eth Address",
      "customerId": "customerOne",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.20",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:40:31.849128Z",
    "destinations": [
      {
        "amount": "0.20",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ]
  }
}

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:40:32.408072441Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b7d18a869f191944a09e5e784d7ca8f45a69",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.20",
    "status": "SIGNED",
    "address": {
      "id": "d18a869f-1919-44a0-9e5e-784d7ca8f45a",
      "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
      "network": "ETHEREUM",
      "keyPairId": "44cf54df-93e9-4dd9-84c9-e96f0cf90f3e",
      "reference": "First Eth Address",
      "customerId": "customerOne",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.20",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:40:32.385590Z",
    "destinations": [
      {
        "amount": "0.20",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ]
  }
}

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:40:34.593627067Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b78e1fcdb58edc49b792891c41c5bcd8186f",
    "hash": "0xc12e1f147b72e697469e24a5caadac1f4cf938cb7d40187eef3612746eb6b53e",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.199630313934810125",
    "status": "DETECTED",
    "address": {
      "id": "8e1fcdb5-8edc-49b7-9289-1c41c5bcd818",
      "address": "0x96073c4b415d60ade18de32e43efc2914731e03d",
      "network": "ETHEREUM",
      "keyPairId": "fdc9f5a0-698c-4163-ab21-df85f343a2a4",
      "reference": "AssetPoolTwo",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.199630313934810125",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:40:34.531163Z",
    "destinations": [
      {
        "amount": "0.199630313934810125",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ]
  }
}

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:40:37.022040178Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b78e1fcdb58edc49b792891c41c5bcd8186f",
    "hash": "0xc12e1f147b72e697469e24a5caadac1f4cf938cb7d40187eef3612746eb6b53e",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.199630313934810125",
    "status": "UNCONFIRMED",
    "address": {
      "id": "8e1fcdb5-8edc-49b7-9289-1c41c5bcd818",
      "address": "0x96073c4b415d60ade18de32e43efc2914731e03d",
      "network": "ETHEREUM",
      "keyPairId": "fdc9f5a0-698c-4163-ab21-df85f343a2a4",
      "reference": "AssetPoolTwo",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.199941204015171125",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:40:36.987028Z",
    "destinations": [
      {
        "amount": "0.199630313934810125",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ],
    "networkDetail": {
      "fee": {
        "asset": "ETH",
        "amount": "0.000310890080361"
      },
      "block": {
        "number": 6046670,
        "timestamp": "2024-06-05T20:40:36Z"
      }
    }
  }
}

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:41:27.295882772Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b78e1fcdb58edc49b792891c41c5bcd8186f",
    "hash": "0xc12e1f147b72e697469e24a5caadac1f4cf938cb7d40187eef3612746eb6b53e",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.199630313934810125",
    "status": "CONFIRMED",
    "address": {
      "id": "8e1fcdb5-8edc-49b7-9289-1c41c5bcd818",
      "address": "0x96073c4b415d60ade18de32e43efc2914731e03d",
      "network": "ETHEREUM",
      "keyPairId": "fdc9f5a0-698c-4163-ab21-df85f343a2a4",
      "reference": "AssetPoolTwo",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.199941204015171125",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:41:27.268151Z",
    "destinations": [
      {
        "amount": "0.199630313934810125",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ],
    "networkDetail": {
      "fee": {
        "asset": "ETH",
        "amount": "0.000310890080361"
      },
      "block": {
        "number": 6046670,
        "timestamp": "2024-06-05T20:40:36Z"
      }
    }
  }
}

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:41:27.398050688Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b7d18a869f191944a09e5e784d7ca8f45a69",
    "hash": "0xc12e1f147b72e697469e24a5caadac1f4cf938cb7d40187eef3612746eb6b53e",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.199941204015171125",
    "status": "SUCCESS",
    "address": {
      "id": "d18a869f-1919-44a0-9e5e-784d7ca8f45a",
      "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
      "network": "ETHEREUM",
      "keyPairId": "44cf54df-93e9-4dd9-84c9-e96f0cf90f3e",
      "reference": "First Eth Address",
      "customerId": "customerOne",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.199941204015171125",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:41:27.375074Z",
    "destinations": [
      {
        "amount": "0.199630313934810125",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ],
    "networkDetail": {
      "fee": {
        "asset": "ETH",
        "amount": "0.000310890080361"
      },
      "block": {
        "number": 6046670,
        "timestamp": "2024-06-05T20:40:36Z"
      }
    }
  }
}

At the final point of getting the SUCCESS wehbook, the deposit has been successful received by the asset pool. This sets off an automatic consolidation round that will move the funds to a central master wallet that pools all the funds for future action, and will be covered in the next section.

Now that the central wallet address exists, the consolidation can be triggered, which will send out a series of consolidation webhooks, which shows the funds moving fro the despoist address , 0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9 , to the new central wallet under the destinations array , 0x96073c4b415d60ade18de32e43efc2914731e03d ,

{
  "event": "layer1:digital:consolidation:status-change",
  "timestamp": "2024-06-05T20:40:31.722661928Z",
  "data": {
    "id": "018fea21bff771e791d51a34af5c59b7d18a869f191944a09e5e784d7ca8f45a69",
    "type": "CONSOLIDATION",
    "asset": "ETH",
    "amount": "0.20",
    "status": "<STATUS>",
    "address": {
      "id": "d18a869f-1919-44a0-9e5e-784d7ca8f45a",
      "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
      "network": "ETHEREUM",
      "keyPairId": "44cf54df-93e9-4dd9-84c9-e96f0cf90f3e",
      "reference": "First Eth Address",
      "customerId": "customerOne",
      "assetPoolId": "2be1cc9c-a5af-47e2-9dba-b7b82317e600"
    },
    "sources": [
      {
        "amount": "0.20",
        "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9"
      }
    ],
    "createdAt": "2024-06-05T20:40:31.479Z",
    "reference": "consolidation-ETH-018fea20-a69e-7cc5-8066-f8d03362e797",
    "updatedAt": "2024-06-05T20:40:31.692479Z",
    "destinations": [
      {
        "amount": "0.20",
        "address": "0x96073c4b415d60ade18de32e43efc2914731e03d"
      }
    ]
  }
}

Furhter total webhooks will be sent out showing the funds moved from the source address to the destination address

{
  "event": "layer1:digital:balance:updated",
  "timestamp": "2024-06-05T20:41:27.341091297Z",
  "data": {
    "reference": "First Eth Address",
    "address": "0xc4b21fb39aaf5fc07d3cd4420bf3ee74a61642e9",
    "asset": "ETH",
    "funds": [
      {
        "type": "AVAILABLE",
        "balance": "0.000058795984828875",
        "delta": "0.000058795984828875"
      },
      {
        "type": "BLOCKCHAIN",
        "balance": "0.000058795984828875",
        "delta": "-0.199941204015171125"
      },
      {
        "type": "RESERVED",
        "balance": "0.00",
        "delta": "-0.20"
      }
    ]
  }
}


{
  "event": "layer1:digital:balance:updated",
  "timestamp": "2024-06-05T20:41:27.349393331Z",
  "data": {
    "reference": "AssetPoolTwo",
    "address": "0x96073c4b415d60ade18de32e43efc2914731e03d",
    "asset": "ETH",
    "funds": [
      {
        "type": "AVAILABLE",
        "balance": "0.199630313934810125",
        "delta": "0.199630313934810125"
      },
      {
        "type": "BLOCKCHAIN",
        "balance": "0.199630313934810125",
        "delta": "0.199630313934810125"
      },
      {
        "type": "RESERVED",
        "balance": "0.00",
        "delta": "0.00"
      }
    ]
  }
}

Updated 5 months ago