Skip to main content

Settlement and Split

Now that Mercatto knows the headphones arrived, it opens the box. Ishtaran takes its own small Platform Fee off the top, then splits what's left exactly the way the order specified back in Creating an order: 90% to Bob, 10% to Mercatto.

Gross: 200.00− Ishtaran Platform Fee (0.9%)1.80Distributable: 198.20Bob — 90%178.38Mercatto — 10%19.82
Real numbers from a real run — Ishtaran's Fee is never hardcoded in this example; it's read from the Settlement result itself.

Code​

examples/marketplace-mercatto/release-order.ts
const executed = await mercatto.settlements.executeSettlement(transactionId);
const settlement = await completeSelfCustodySettlement(mercatto, environmentId, executed.settlementId, executionSigner);
const summary = await mercatto.settlements.getSummary(transactionId);

Result​

{
  "status": "COMPLETED",
  "signingRequestId": "…sr…",
  "grossAmount": "200.000000000000000000",
  "platformFeeAmount": "1.800000000000000000",
  "distributableAmount": "198.200000000000000000",
  "feePercentageApplied": "0.900000000000000000",
  "splitAllocations": [
    { "accountId": "…bob…", "amount": "178.380000000000000000", "status": "EXECUTED" },
    { "accountId": "…mercatto…", "amount": "19.820000000000000000", "status": "EXECUTED" }
  ]
}

What happened under the hood​

executeSettlement alone does not move money and does not post Ledger Entries — under SelfCustody (DEC-037, the only real custody model today), it builds a real SigningRequest: one execution leg per beneficiary (Bob, Mercatto's own commission) plus a leg for the Platform Fee itself, each addressed using the ExecutionDestination registered back in Seller onboarding — sourced from whichever address actually holds Alice's confirmed deposit. executeSettlement returns immediately with the Settlement in Executing and signingRequestId populated; nothing is final yet.

completeSelfCustodySettlement (examples/marketplace-mercatto/self-custody-settlement.ts) is what actually finishes the job: it fetches the SigningRequest, signs every leg locally with Mercatto's own execution wallet (registered in Seller onboarding; the private key never leaves this process), submits each signature, and — once the platform's all-signatures gate broadcasts every leg — waits for each one to confirm (Sandbox: simulated, sandbox.simulateBroadcastConfirmation; a real network in Production). Only once every leg confirms does Ishtaran post the Ledger Entries and move the Settlement to Completed. "Settled" never means "Ledger updated" under SelfCustody — it means the real transfer confirmed. A Settlement with nothing to execute on-chain (every beneficiary retained, Fee zero) skips signing entirely: signingRequestId is simply null, and completeSelfCustodySettlement resolves right away.

The Fee percentage isn't hardcoded anywhere in this example: there's no public route to read the Pricing Policy in advance (Known Limitations §F.3), so Mercatto reads it back from the Settlement result itself, the same way any integrator has to today.

Broadcasting those legs costs real network resources (TRON Energy/Bandwidth) — someone has to pay for that, separately from the Platform Fee. Right after onboarding Bob and Alice (examples/marketplace-mercatto/register-network-cost-payer-account.ts), Mercatto registers its own revenue Account as the NetworkCostPayerAccount for this AssetNetwork — a real business decision (network cost comes out of Mercatto's own commission), not a technical afterthought. Without it, this very call would fail with a 422 before ever building a SigningRequest: under SelfCustody, executeSettlement resolves a NetworkCostPayerAccount and reserves the real, quoted network cost (via the same Network Execution Engine Withdrawals uses — see Withdrawal) before it moves a single beneficiary's money. That reserved cost never shows up in grossAmount/platformFeeAmount/splitAllocations above — it's a separate Ledger reservation against Mercatto's own commission Account, settled once every leg confirms.

A beneficiary's Account isn't always ready to receive. If Bob's Account were frozen at this exact moment, his allocation would be RETAINED instead of EXECUTED — no execution leg is built for a retained allocation, and the rest of the Settlement still completes normally. See Failure scenarios for that exact case, worked through with real numbers.

Settlement doesn't have to happen all at once — see Partial Settlement.