Reclaim a holder's MPT balance back to the issuer.
Requires the issuance to have been created with canClawback, the SDK's default in token.issue. The flag is fixed at issuance and cannot be added later.
token.clawback(
params: TokenClawbackParams,
options?: TokenWriteOptions,
): Promise<SubmissionResult<{ holder: string; amount: string }>>| Parameter | Type | Required | Description |
|---|---|---|---|
holder | string | Yes | The holder's r-address to claw the balance back from. |
amount | Amount | Yes | The MPT amount to claw back; its asset must be an MPT (build it with mpt()). |
The Amount type pairs a value with the asset it denominates:
interface Amount {
asset: Asset // what is being moved
value: string // the quantity, as a decimal string in display units (e.g., '10.5')
}Build the asset field with one of the asset constructors:
| Constructor | Description |
|---|---|
XRP_ASSET | XRP |
iou(currency, issuer) | IOUs: currency is a 3-character code or 40-character hex; issuer is the issuer's r-address. |
mpt(mptIssuanceId, scale?) | MPTs: scale is the decimal places between the display value and on-ledger base units (default 0). |
options is an optional second argument that sets the source account and overrides the fee.
| Option | Type | Required | Description |
|---|---|---|---|
from | AccountSelector | No | The account to act as — an r-address string, or an object { address } or { signer, account? }. Defaults to the primary signer's primary account. (For IOU operations, this is the issuer.) |
fee | FeeIntent | No | Fee override — a priority tier and/or a maxFeeDrops cap. |
idempotencyKey | string | No | A prior submission's idempotencyKey, to retry to the same intent instead of creating a duplicate. Auto-generated when omitted. |
Resolves to a SubmissionResult<{ holder: string; amount: string }>.
Every simpleXRPL write resolves to a SubmissionResult<T> — a union tagged by source, with the backend's raw response preserved verbatim. Its common fields are:
| Field | Type | Description |
|---|---|---|
intent | T | The operation-specific output — see the operation's own return fields. |
source | 'xrpld' | 'custody' | 'palisade' | Which backend produced the result; discriminates response. |
response | TxResponse | custody record | Palisade record | The backend's raw response, preserved verbatim. |
txHash | string (optional) | The XRPL transaction hash, once the transaction is on-ledger. |
intentId | string (optional) | The custodian intent id, when the path produced one. Hold onto this to resume via client.intent. |
idempotencyKey | string (optional) | The UUIDv7 this submission carried. Pass it back as a later call's idempotencyKey to retry to the same intent rather than creating a duplicate. |
For Token.clawback, the intent echoes:
| Field | Type | Description |
|---|---|---|
holder | string | The holder's r-address clawed back from. |
amount | string | The amount clawed back, as a decimal string. |
Builds and submits a single Clawback transaction. Throws an IntentValidationError if amount's asset is not an MPT. Use iou.clawback for issued currencies.
await client.token.clawback({
holder: 'rHolder...',
amount: { asset: mpt('005C...'), value: '100' },
})