Skip to main content
POST
Prepare a dividend distribution
Prepares unsigned transactions for distributing payment token dividends to holders of a specific token. Use POST /prepare-transactions with method=dividendDistribution.

Notes

  • Amounts are specified in whole units (e.g., 10 for 10 USDT)
  • The signer must have sufficient balance of the payment token
  • The signer must first approve the configured payment token to the STO contract. Retrieve the STO address from GET /get-tokenizer-info?tokenSymbol=... and use its tokenAddress as spenderAddress in the approve request.
  • Do not use escrowAddress as the approval spender for this operation. Wait for the payment-token approval to be confirmed on-chain before preparing the distribution.
  • Only the tokenizer can distribute dividends for their tokens

Which token, and which spender

The allowance is read as paymentToken.allowance(signerAddress, tokenAddress), where the payment token is resolved from the asset on-chain. Getting either half wrong produces the same error:
GET /get-token-info returns the asset’s configured payment token, not the security token’s own address. The address you need as spenderAddress is tokenAddress from GET /get-tokenizer-info. Approving the security token itself, or approving to escrowAddress, both leave the dividend allowance at zero.

Preflight errors

Both are returned as 400 before anything is prepared, so nothing was broadcast and no funds moved. Fix the allowance or the balance and prepare again.
There is no additional platform fee folded into this check: the allowance only has to cover the dividend amount you requested.
Once distributed, it can take a little while for a storefront’s claim action to become available to holders. See approve for the complete allowance workflow and field mapping.

Next step

Preparing does not touch the chain. The response gives you txId and an array of unsigned transactions — you still have to sign and submit them.
1

Sign every returned transaction

Sign each entry locally with the wallet that sends the transaction — signerAddress, or investorAddress for newInvest and claimTokens. It must be whitelisted by Brickken, and it needs native gas on the target chain.
2

Submit the signed payloads

POST them to /send-transactions as { txId, signedTransactions } and Brickken broadcasts for you.If you would rather broadcast yourself, prepare with executionMode: "client-broadcast" and confirm afterwards with { txId, txHash } instead.
3

Poll until it confirms

Call GET /get-transaction-status with the txId. A pending status means it is broadcast but not yet mined — do not resubmit.
Full walkthrough: Tokenize an asset and run an STO.

Authorizations

x-api-key
string
header
required

Body

application/json
method
enum<string>
default:dividendDistribution
required

Required. Operation to prepare. Must be dividendDistribution for this endpoint.

Available options:
dividendDistribution
Example:

"dividendDistribution"

chainId
string
required

Required. Blockchain network identifier. Hex format is recommended, for example Sepolia aa36a7.

Example:

"aa36a7"

signerAddress
string
required

Required. Wallet that funds and signs the distribution. It must hold at least amount of the configured payment token and have approved the STO tokenAddress for that amount. Retrieve that address with GET /get-tokenizer-info; escrowAddress is not the spender for this allowance.

Example:

"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

tokenSymbol
string
required

Required. Symbol of the token whose holders receive the dividend.

Example:

"EXMPL"

amount
string
required

Required. Payment-token amount to distribute.

Example:

"100"

paymentTokenAddress
string

Optional. Payment token contract address. When provided, it must match the payment token configured for the token.

Pattern: ^0x[a-fA-F0-9]{40}$
Example:

"0x5555555555555555555555555555555555555555"

Response

200 - application/json

Successful response

transactions
object[]
required

Array of unsigned transaction objects ready for signing

txId
string
required

Unique identifier for this transaction batch (required for /send-transactions). This is NOT a blockchain transaction hash.

Example:

"0x46adea7bdf49c576a760102e0d6bc9ecd650b3998588cd3d7f576a7973426aad"

info
object

Metadata about the operation