Goldsky

Token distributions to holders and creditors

Talk to our team

What it is

Token distributions pay one asset out to many recipients at once, such as token holders at a record date, creditors in a claims process or employees, and are also called token payouts or creditor distributions.

Transfer agents, custodians and tokenization platforms run them, and each recipient has to be paid the right amount once, with records that show it.

A Goldsky Compose task snapshots who is owed and sends each payment through your custody provider, and a pipeline matches every delivery for your records, while the terms, the share rules and the signing policy stay with you.

How token distributions to holders and creditors work

The diagram follows one distribution from the approval of its terms to closing it out, and shows who does each step. Your setup may differ.

Approve the distributionAsset, amount and record date set

Load the payee listCreditors or employees from your records

ComposeSnapshot the holdersEach balance at the record block

Verification providerCheck identity and tax formsRecipients without both are held back

Set each payoutYour rules size each recipient’s share

Wallet or custody providerSign and sendTransfers signed under your approval policy

ComposeSend each paymentSubmitted onchain and confirmed

TurboSpot each deliveryTransfers out of the payout wallet

Payouts settleThe asset reaches each recipient’s wallet

Close the distributionDeliveries matched to recipients, gaps chased

TurboRecord the proofEach delivery lands in your warehouse

Goldsky
Your provider

How to run token distributions

A TypeScript task that you write and Goldsky hosts takes a distribution from record date to final payment: it snapshots who is owed, pays each recipient, waits for each payment to confirm and logs every step. A pipeline then matches each payment on the chain to its recipient for your records.

What you’ll need

Goldsky Compose
Goldsky Turbo
The funds to distribute, held in a payout wallet
A custody provider with an approval policy that can sign EIP-712 typed data and EIP-7702 authorizations, reached through a signing endpoint you host
Your claims register, for creditor distributions
A database or warehouse for the payment records

Declare the distribution terms
Every recipient’s share is worked out from the same few facts, so they have to be fixed and approved before anyone is paid.
Someone with authority approves the asset, the total amount and the record date (the cutoff that decides who is owed). If any of them changes after payments start, some recipients are paid on old terms and the totals stop adding up.
Snapshot who is owed at the record date
Handled by Goldsky Compose
Holdings change all the time, so you need a fixed list of who held what on the agreed day.
The list has to show each holder’s balance at the exact cutoff, rebuilt from every transfer up to it, or the wrong people are paid the wrong amounts. For creditors, the list comes from the claims register instead of token balances.
With Goldsky Compose, the payout task can start a one-time Turbo Pipelines job that rebuilds each holder’s balance at the record block, read the result, then delete the job, so nothing keeps running between distributions.
Start a Turbo job from a task (opens in a new tab)
Hold back anyone without identity and tax checks
Creditor distributions are usually paid only to people who have proved who they are and filed the tax form the payer needs.
Your verification provider checks each recipient’s identity, and the tax form, such as a US W-9 or W-8, is collected before any payment. A recipient who hasn’t finished both is held back to a later distribution rather than paid.
Calculate each recipient’s share
The total is split by rules your team owns, such as pro rata to holdings, and the shares have to add back up to the amount declared.
Rounding has to be settled in those rules: if every share is rounded down and the remainder is never assigned, money is left over, and if shares are rounded up, the payout runs short before the last recipient.
Approve and sign the payments
Moving money takes a signature from a key, and most teams keep their keys with a custody provider whose rules say who can approve what.
Your signing endpoint holds the limits and approvers set before the distribution starts: it reads the recipient and amount from each payment’s call data, checks them, then asks your custodian to sign. If the key sits in application settings with no rules around it, anyone who can change the app can move the funds.
Send each payment and wait for it to confirm
Handled by Goldsky Compose
A payment is done when the chain has accepted it and it can no longer be reversed, which can be some time after it was sent.
A payment can be dropped before it’s included, or undone when the chain rewrites its most recent blocks (a reorg). Each one has to be retried until it sticks, and a retry must never pay the same recipient twice.
Compose can send each payment through a webhook wallet, which posts a UserOperation (the transaction format smart-account wallets use) to a signing endpoint you host, plus a one-time EIP-7702 authorization the first time it sends on a chain, and submits the payment, gas-sponsored, once your server returns the signature. The task then waits for the confirmations you set, resends a payment if a reorg drops it, and doesn’t send again a payment that already went through if it restarts mid-run.
Handle confirmations and reorgs (opens in a new tab)
Settle each payment on the chain
The chain is the shared record both sides trust, so a payment counts once it’s recorded there.
Once a payment has enough blocks on top of it, the asset is in the recipient’s wallet and anyone can check the transfer. A payment that failed or was never included still shows as unpaid and has to be picked up.
Match every delivery to its recipient
Handled by Goldsky Turbo
Your payout list says who should have been paid and the chain says who was; checking one against the other tells you the distribution is complete.
Every transfer on the chain should match one line of the payout list by wallet and amount. A payment with no matching line, or a line with no payment, is a break someone has to explain before the distribution closes.
With Goldsky, you can hold the recipient list in a Turbo Pipelines dynamic table, which lives in a Postgres database, and have a pipeline match transfers from your payout wallet against it. Each match is written to your database or warehouse, and reorg corrections reach the same tables.
Filter transfers with dynamic tables (opens in a new tab)
Keep an audit trail of the distribution
Handled by Goldsky Compose
Auditors and recipients may ask later who was paid, how much and why, and the answer has to come from records.
The record ties each payment to the snapshot, the share calculation, the approval and the transaction on the chain. When those sit in different systems with no shared reference, rebuilding one recipient’s history means searching each system by hand.
Compose logs every call a task makes, including each API request and transaction. Joined with the pipeline’s records on the transaction hash, that gives you one history per recipient.
How Compose logs each call (opens in a new tab)
Close the distribution
Some payments fail or bounce, and someone has to decide what happens to them before the books close.
Unpaid recipients are followed up or paid again, unclaimed funds go back to the right account, and the total paid is checked against the amount declared. Left open, the unpaid balance sits in the payout wallet with no owner on your side.

What you control

Your team: Declare the distribution terms
Calculate each recipient’s share
Close the distribution
Your providers: Verification provider
Wallet or custody provider