API Reference: dividendPayment

Executes an automated, snapshot-based dividend payment to all accounts holding a specific Totem at a specified historical block height.

---

Endpoint Details

• HTTP Method: POST
• Gateway Path: /nxt
• Content-Type: application/x-www-form-urlencoded
• API Tags: AE, CREATE_TRANSACTION
• Chain Specific: Yes

---

Request Parameters

Parameter	Type	Required	Description
requestType	String	Yes	Must be set to dividendPayment.
totem	long	Yes	Unique $64$-bit ID of the Totem distributing dividends.
chain	int	Yes	Sovereign BetaChain ID.
height	int	Yes	Historical block height snapshot used for balance calculation.
holdingType	String/int	Yes	Payment asset class (COIN = 0, TOTEM = 1, CURRENCY = 2).
holding	long	Conditional	Asset ID if holdingType is TOTEM or CURRENCY. Omitted if COIN.
amountMTAPerShare	long	Yes	Amount of payment currency per unit share ($MTA$/$QNT$).
secretPhrase	String	Yes	Passphrase of the account funding the dividend distribution.
feeNQT	long	Conditional	Transaction execution fee in base units ($NQT$).

---

Example Request

curl -X POST http://localhost:22024/nxt \
  -d "requestType=dividendPayment" \
  -d "chain=2" \
  -d "totem=9876543210123456789" \
  -d "height=500000" \
  -d "holdingType=CURRENCY" \
  -d "holding=5544332211" \
  -d "amountMTAPerShare=5000" \
  -d "secretPhrase=your_pqc_passphrase" \
  -d "feeNQT=100000000"

---

Successful Response

{
  "signatureHash": "d9e8f7a6...",
  "unsignedTransactionBytes": "0100...",
  "transactionJSON": {
    "sender": "1234567890123456789",
    "feeNQT": "100000000",
    "type": 2,
    "subtype": 6,
    "attachment": {
      "version.DividendPayment": 1,
      "totem": "9876543210123456789",
      "height": 500000,
      "holdingType": 2,
      "holding": "5544332211",
      "amountMTAPerShare": "5000"
    },
    "timestamp": 89234300
  },
  "broadcasted": true,
  "transaction": "65123049120394813"
}

---

Error Codes

Error Code	Cause / Description
TOTEM_NOT_ISSUED_YET	Specified historical snapshot height predates the Totem issuance block height.
NOT_ENOUGH_FUNDS	Sender account balance is insufficient to cover total gross distribution + fees.