Reconcile balances

Reconciliation compares a ledger with DALP's indexed token data. Run the check to confirm holders, trace movement history, and separate a pending transaction from a missed event or a ledger-only entry.

This how-to covers read-only checks. The requests below do not change balances or submit corrections. For a pending submission, check transaction status before reconciling.

Prerequisites

• Platform URL, such as https://your-platform.example.com.
• API key. See Getting started with the API.
• Token contract address for the asset you want to reconcile.
• Your internal balance records and transaction references for comparison.

Quickstart: query current holder balances

Start with the current indexed holders for one token:

curl -X GET "https://your-platform.example.com/api/token/0xTOKEN_ADDRESS/holders" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

The response groups holder balances under token.balances. value, available, and frozen are decimal token amounts derived from the token's decimals.

{
  "token": {
    "balances": [
      {
        "account": { "id": "0x1111111111111111111111111111111111111111" },
        "value": "1000.00",
        "available": "800.00",
        "frozen": "200.00",
        "isFrozen": false,
        "lastUpdatedAt": "2026-01-15T10:30:00.000Z"
      },
      {
        "account": { "id": "0x2222222222222222222222222222222222222222" },
        "value": "500.00",
        "available": "500.00",
        "frozen": "0.00",
        "isFrozen": false,
        "lastUpdatedAt": "2026-01-14T15:20:00.000Z"
      }
    ]
  },
  "totalCount": 2
}

To narrow the result to a single holder, include the wallet address as a query parameter. The single-holder endpoint is faster when you already know the wallet and need to check only one balance.

curl -X GET "https://your-platform.example.com/api/token/0xTOKEN_ADDRESS/holder?holderAddress=0xHOLDER_ADDRESS" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Query balance-affecting events

Token events record each on-chain state change with a block timestamp, transaction hash, and raw amount. Query the balance-affecting events (transfers, mints, and burns) to trace when a discrepancy first appeared:

curl -X GET "https://your-platform.example.com/api/token/0xTOKEN_ADDRESS/events?eventNames=TransferCompleted&eventNames=MintCompleted&eventNames=BurnCompleted" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Use limit and offset when you expect many events.

{
  "events": [
    {
      "id": "evt_01hzzzzzzzzzzzzzzzzzzzzzzz",
      "eventName": "TransferCompleted",
      "txIndex": "0",
      "blockNumber": "12345678",
      "blockTimestamp": "2026-01-15T10:30:00.000Z",
      "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "emitter": { "id": "0xTOKEN_ADDRESS" },
      "sender": { "id": "0xSENDER_ADDRESS" },
      "values": [
        { "id": "evt_01hzzzzzzzzzzzzzzzzzzzzzzz-account", "name": "account", "value": "0xACCOUNT_ADDRESS" },
        { "id": "evt_01hzzzzzzzzzzzzzzzzzzzzzzz-amount", "name": "amount", "value": "1000000000000000000" }
      ]
    }
  ]
}

Event amounts are indexed as raw on-chain integer values. Apply the token decimals before comparing the amount with a human-readable ledger value.

Compare with your ledger

For each holder in your ledger:

1. Match the holder wallet address to the account.id field from the holder-balance response.
2. Compare your ledger balance with value.
3. Compare transferable balance with available when your ledger separates frozen or restricted balances.
4. Use lastUpdatedAt and token events to narrow the period where the mismatch appeared.

For each ledger transaction:

1. Find the matching token event by transaction hash when you have it.
2. If you do not have the hash, filter by senderAddress and event type.
3. Confirm the event name and raw amount match the ledger entry after decimal conversion.
4. Treat an internal ledger entry with no matching event as a failed or still-pending submission until transaction tracking proves otherwise.

Investigate a mismatch

If your ledger stores the submitted transaction hash, filter by it to locate the on-chain record:

curl -X GET "https://your-platform.example.com/api/token/0xTOKEN_ADDRESS/events?transactionHashes=0xTX_HASH_1&transactionHashes=0xTX_HASH_2" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Filter by sender when you need events initiated by a specific wallet:

curl -X GET "https://your-platform.example.com/api/token/0xTOKEN_ADDRESS/events?eventNames=TransferCompleted&senderAddress=0xYOUR_WALLET" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Use senderAddress for transactions submitted by a wallet. Use the event payload and account fields to find events where the wallet participated but did not submit the transaction. Use either senderAddress or walletAddress on token event queries; the endpoint rejects requests that include both filters.

Endpoint reference

Event types for reconciliation

Response fields

Balance fields

Event fields

Troubleshooting

Related operations

• Track transaction status before reconciling a transaction that was just submitted.
• Handle API errors when a reconciliation query fails.
• Review the API reference for the full route catalogue.