Reconcile a subscription

A subscription has three steps on Securitize’s side, each with its webhook and its endpoint:

Step	Webhook	Endpoint	Key
Your cash is recorded	`investor.deposit.processed`	`GET /deposits`	Deposit `id`, `uetr`
Tokens are minted to you	`investor.minting.completed`	The deposits’ `tokenIssuanceId`	`tokenIssuanceId`
The issuance is recorded on chain	`investor.transaction.processed`	`GET /transactions`	`tokenIssuanceId`, `txHash`

Every subscription leaves two cash movements for the same amount: the deposit when your cash arrives, and the liquidation when that cash is applied to the tokens. A subscription you fund in two wires is two deposits, their liquidations, and one issuance.

1. Match your cash to the deposits

When investor.deposit.processed arrives, match it to the wire you sent: by uetr when you paid by wire, otherwise by amount, currencyId and date. direction tells you which way the cash moved:

`direction`	Meaning
`deposit`	Your cash, received for a subscription
`liquidation`	Your cash applied to a token issuance, recorded when the tokens are issued
`withdraw`	Cash returned at your request
`refund`	Cash returned by Securitize

Match your wires to the deposit movements only. At this point the deposit has no tokenIssuanceId: tokens are not issued yet.

2. Match the deposits to the tokens

When tokens are issued, investor.minting.completed arrives with:

data.id, the tokenIssuanceId;
data.amount and decimals, the tokens issued;
data.depositMovements, the cash movements behind it: each deposit and the liquidation that applied it, for the same amount;
data.txHash, the mint on chain.

Mark each movement in depositMovements as issued with this tokenIssuanceId. From now on, GET /deposits/{depositId} returns the same tokenIssuanceId for each of them.

Count the cash once. A deposit and its liquidation are the same money seen twice, on arrival and on use: adding every movement of depositMovements doubles the cash of the subscription.

3. Match the tokens to the chain

investor.transaction.processed with type issuance and processType subscription carries the same tokenIssuanceId and the same txHash. It can arrive before the minting: when it does, create the issuance from it and fill in the deposits when the minting arrives. The subscription is reconciled when your cash, the deposits, the issuance and the transaction all agree:

Σ your wires         =  Σ deposit movements of that issuance          (cash, currency minor units)
Σ deposit movements   =  Σ liquidation movements of that issuance    (the cash was applied in full)
minting.amount       =  transaction.amount                        (tokens, token base units)
minting.txHash       =  transaction.txHash

Cash and tokens are in different units, joined by the fund’s price at issuance. See Amounts.

Reconcile from the endpoints

To reconcile without webhooks, or to check what the webhooks told you, read both lists of a token and join them on tokenIssuanceId:

async function readAll(path, tokenId) {
  const items = [];
  for (let offset = 0; ; offset += 100) {
    const page = await api(`${path}?tokenId=${tokenId}&limit=100&offset=${offset}`);
    items.push(...page.data);
    if (offset + page.meta.length >= page.meta.total) return items;
  }
}

const deposits = await readAll('/deposits', tokenId);
const transactions = await readAll('/transactions', tokenId);

const issuances = new Map(); // tokenIssuanceId -> { deposits, transaction }
for (const d of deposits) {
  if (!d.tokenIssuanceId) continue; // received, not issued yet
  const entry = issuances.get(d.tokenIssuanceId) ?? { deposits: [], transaction: null };
  entry.deposits.push(d);
  issuances.set(d.tokenIssuanceId, entry);
}
for (const t of transactions) {
  if (!t.tokenIssuanceId) continue; // not an issuance: a transfer or a redemption
  const entry = issuances.get(t.tokenIssuanceId) ?? { deposits: [], transaction: null };
  entry.transaction = t;
  issuances.set(t.tokenIssuanceId, entry);
}

What each state of an entry means:

Deposits	Transaction	Meaning
Some, with `tokenIssuanceId` `null`	None	Cash received, tokens not issued yet
Some	One	Reconciled
None	One, `processType` `reinvest`	A reinvested distribution: no cash was deposited
Some	None	Tokens issued and the transaction not recorded yet; check again later

The tokenIssuanceId key does not filter the lists: page through the token’s deposits and transactions and join on your side.

Reinvested distributions

A distribution you reinvest issues tokens without a deposit: investor.minting.completed with source reinvest and empty depositMovements, and a transaction with processType reinvest and its own tokenIssuanceId. The distribution’s cash value arrives as investor.payout.completed with paymentMethod reinvest; match it to the issuance by tokenId and time.

Get started

Guides

Concepts

Help

API reference

1. Match your cash to the deposits

2. Match the deposits to the tokens

3. Match the tokens to the chain

Reconcile from the endpoints

Reinvested distributions