mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-15 17:25:49 +00:00
Merge pull request #3104 from XRPLF/mpt-holders-doc-cleanup
Clean up mpt_holders reference documentation + add Try It
This commit is contained in:
Maria Shodunke
@@ -3,156 +3,150 @@ blurb: Get the holders for a given `MPTokenIssuanceID` and ledger sequence.
|
||||
labels:
|
||||
- Accounts
|
||||
- XRP
|
||||
- Multi Purpose Tokens, MPTs
|
||||
---
|
||||
|
||||
# mpt_holders
|
||||
|
||||
[[Source]](https://github.com/XRPLF/clio/blob/develop/src/rpc/handlers/MPTHolders.cpp "Source")
|
||||
|
||||
_(Requires the [MPTokensV1 amendment][] {% not-enabled /%})_
|
||||
|
||||
For a given `MPTokenIssuanceID` and ledger sequence, `mpt_holders` returns all holders of that MPT and their balance. This method likely returns very large data sets, so you should expect to implement paging via the `marker` field. This API is only available using Clio, not rippled.
|
||||
For a given `MPTokenIssuanceID` and ledger sequence, `mpt_holders` returns all holders of that [MPT](../../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md) and their balance. This method likely returns very large data sets, so you should expect to implement paging via the `marker` field. This API is only available using Clio, not `rippled`. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.3.0" %}New in: Clio v2.3.0{% /badge %}
|
||||
|
||||
## Request Format
|
||||
|
||||
*Websocket*
|
||||
{% tabs %}
|
||||
|
||||
{% tab label="WebSocket" %}
|
||||
```json
|
||||
{
|
||||
"command": "mpt_holders",
|
||||
"mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
|
||||
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
*JSON-RPC*
|
||||
|
||||
{% tab label="JSON-RPC" %}
|
||||
```json
|
||||
{
|
||||
"method": "mpt_holders",
|
||||
"params": [
|
||||
{
|
||||
"mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
|
||||
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
|
||||
"ledger_index": "validated"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
{% try-it method="mpt_holders" server="devnet-clio" /%}
|
||||
|
||||
The request contains the following parameters:
|
||||
|
||||
| Field | Type | Required? | Description |
|
||||
|:------------------|:---------------------|:----------|-------------|
|
||||
| `mpt_issuance_id` | string | Yes | The `MPTokenIssuance` to query. |
|
||||
| `ledger_index` | string or number (positive integer) | No | The ledger index of the max ledger to use, ora shortcut string to choose a ledger automatically. You must specify either ledger_index or ledger_hash. |
|
||||
| `ledger_hash` | string | No | A 32-byte hex string for the ledger version to use. You must specify either ledger_index or ledger_hash. |
|
||||
| `marker` | string | No | Used to continue your query where it left off in paginating. |
|
||||
| `limit` | number (positive integer) | No | Specify a limit to the number of MPTs returned. |
|
||||
| Field | Type | Required? | Description |
|
||||
|:------------------|:---------------------------|:----------|-------------|
|
||||
| `mpt_issuance_id` | String | Yes | The `MPTokenIssuance` to query. |
|
||||
| `ledger_index` | [Ledger Index][] | No | The [Ledger Index][] of the max ledger to use, or a shortcut string to choose a ledger automatically. You must specify either `ledger_index` or `ledger_hash`. See [Specifying Ledgers][].|
|
||||
| `ledger_hash` | String | No | A 32-byte hex string for the ledger version to use. You must specify either `ledger_index` or ledger_hash. See [Specifying Ledgers][]. |
|
||||
| `marker` | [Marker][] | No | Used to continue your query where it left off in paginating. |
|
||||
| `limit` | Number (positive integer) | No | Specify a limit to the number of MPTs returned. |
|
||||
|
||||
## Response Format
|
||||
|
||||
{% tabs %}
|
||||
{% tab label="WebSocket" %}
|
||||
```json
|
||||
{
|
||||
"mpt_issuance_id": "000004C463C52827307480341125DA0577DEFC38405B0E3E",
|
||||
"limit":50,
|
||||
"ledger_index": 2,
|
||||
"mptokens": [{
|
||||
"account": "rEiNkzogdHEzUxPfsri5XSMqtXUixf2Yx",
|
||||
"result": {
|
||||
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
|
||||
"limit": 50,
|
||||
"ledger_index": 2414929,
|
||||
"mptokens": [
|
||||
{
|
||||
"account": "rfyWeQpYM3vCXRHA9cMLs2ZEdZv1F1jzm9",
|
||||
"flags": 0,
|
||||
"mpt_amount": "20",
|
||||
"mptoken_index": "36D91DEE5EFE4A93119A8B84C944A528F2B444329F3846E49FE921040DE17E65"
|
||||
},
|
||||
{
|
||||
"account": "rrnAZCqMahreZrKMcZU3t2DZ6yUndT4ubN",
|
||||
"flags": 0,
|
||||
"mpt_amount": "1",
|
||||
"mptoken_index": "D137F2E5A5767A06CB7A8F060ADE442A30CFF95028E1AF4B8767E3A56877205A"
|
||||
}],
|
||||
"mpt_amount": "200",
|
||||
"mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13"
|
||||
}
|
||||
],
|
||||
"validated": true
|
||||
},
|
||||
"status": "success",
|
||||
"type": "response",
|
||||
"warnings": [
|
||||
{
|
||||
"id": 2001,
|
||||
"message": "This is a clio server. clio only serves validated data. If you want to talk to rippled, include 'ledger_index':'current' in your request"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% tab label="JSON-RPC" %}
|
||||
```json
|
||||
200 OK
|
||||
|
||||
{
|
||||
"result": {
|
||||
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
|
||||
"limit": 50,
|
||||
"ledger_index": 2415033,
|
||||
"mptokens": [
|
||||
{
|
||||
"account": "rfyWeQpYM3vCXRHA9cMLs2ZEdZv1F1jzm9",
|
||||
"flags": 0,
|
||||
"mpt_amount": "200",
|
||||
"mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13"
|
||||
}
|
||||
],
|
||||
"validated": true,
|
||||
"status": "success"
|
||||
},
|
||||
"warnings": [
|
||||
{
|
||||
"id": 2001,
|
||||
"message": "This is a clio server. clio only serves validated data. If you want to talk to rippled, include 'ledger_index':'current' in your request"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
{% /tab %}
|
||||
|
||||
{% /tabs %}
|
||||
|
||||
### Response Fields
|
||||
|
||||
The response follows the [standard format][], with the result containing the following fields:
|
||||
|
||||
| Field | Type | Description |
|
||||
|:-----------------------|:--------|:------------------------------------------|
|
||||
| `mpt_issuance_id` | string | The `MPTokenIssuance` queried |
|
||||
| `mptokens` | array | An array of mptokens. Includes all relevant fields in the underlying MPToken object. |
|
||||
| `marker` | string | Used to continue querying where we left off when paginating. Omitted if there are no more entries after this result. |
|
||||
| `limit` | number | The limit, as specfied in the request
|
||||
| `ledger_index` | number | The index of the ledger used. |
|
||||
| Field | Type | Description |
|
||||
|:-----------------------|:-----------------|:------------------------------------------|
|
||||
| `mpt_issuance_id` | String | The `MPTokenIssuance` queried. |
|
||||
| `mptokens` | Array | An array of [MPTokens](#mptoken). Includes all relevant fields in the underlying `MPToken` object. |
|
||||
| `marker` | [Marker][] | Used to continue querying where we left off when paginating. Omitted if there are no more entries after this result. |
|
||||
| `limit` | Number | The limit, as specified in the request. |
|
||||
| `ledger_index` | [Ledger Index][] | The index of the ledger used. |
|
||||
| `validated` | Boolean | If `true`, the ledger has been validated by the consensus process and is immutable. Otherwise, the contents of the ledger are not final and may change. In Clio, this is _always_ true as Clio stores and returns validated ledger data. |
|
||||
|
||||
An `mptoken` object has the following parameters:
|
||||
#### MPToken
|
||||
|
||||
| Field | Type | Description |
|
||||
|:-----------------------|:--------|:------------------------------------------|
|
||||
| `account` | string | The account address of the holder who owns the `MPToken`. |
|
||||
| `flags` | number | The flags assigned to the`MPToken` object. |
|
||||
| `mpt_amount` | string | Base 10-encoded amount of the holder's balance. |
|
||||
| `mptoken_index` | string | Key of the `MPToken` object. |
|
||||
An `MPToken` object has the following parameters:
|
||||
|
||||
##### Example
|
||||
Example of a `tx` response:
|
||||
| Field | Type | Description |
|
||||
|:-----------------------|:------------------|:------------------------------------------|
|
||||
| `account` | String | The account address of the holder who owns the `MPToken`. |
|
||||
| `flags` | Number | The flags assigned to the`MPToken` object. |
|
||||
| `mpt_amount` | [String Number][] | Specifies a positive amount of tokens currently held by the owner. |
|
||||
| `mptoken_index` | String | Key of the `MPToken` object. |
|
||||
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"Account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
|
||||
"AssetScale": 2,
|
||||
"Fee": "10",
|
||||
"Flags": 64,
|
||||
"Sequence": 303,
|
||||
"SigningPubKey": "ED39955DEA2D083C6CBE459951A0A84DB337925389ACA057645EE6E6BA99D4B2AE",
|
||||
"TransactionType": "MPTokenIssuanceCreate",
|
||||
"TxnSignature": "80D7B7409980BE9854F7217BB8E836C8A2A191E766F24B5EF2EA7609E1420AABE6A1FDB3038468679081A45563B4D0B49C08F4F70F64E41B578F288A208E4206",
|
||||
"ctid": "C000013100000000",
|
||||
"date": 760643692,
|
||||
"hash": "E563D7942E3E4A79AD73EC12E9E4C44B7C9950DF7BF5FDB75FAD0F5CE0554DB3",
|
||||
"inLedger": 305,
|
||||
"ledger_index": 305,
|
||||
"meta": {
|
||||
"AffectedNodes": [...],
|
||||
"TransactionIndex": 0,
|
||||
"TransactionResult": "tesSUCCESS",
|
||||
"mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE"
|
||||
},
|
||||
"status": "success",
|
||||
"validated": true
|
||||
}
|
||||
}
|
||||
```
|
||||
## Possible Errors
|
||||
|
||||
##### Object
|
||||
An `mpt_issuance_id` field is provided in JSON MPTokenIssuance objects (not available for binary). The following APIs are impacted: `ledger_data` and `account_objects`.
|
||||
|
||||
##### Example
|
||||
Example of an `account_objects` response:
|
||||
|
||||
```json
|
||||
{
|
||||
"result": {
|
||||
"account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
|
||||
"account_objects": [
|
||||
{
|
||||
"AssetScale": 2,
|
||||
"Flags": 64,
|
||||
"Issuer": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
|
||||
"LedgerEntryType": "MPTokenIssuance",
|
||||
"OutstandingAmount": "100",
|
||||
"OwnerNode": "0",
|
||||
"PreviousTxnID": "BDC5ECA6B115C74BF4DA83E36325A2F55DF9E2C968A5CC15EB4D009D87D5C7CA",
|
||||
"PreviousTxnLgrSeq": 308,
|
||||
"Sequence": 303,
|
||||
"index": "75EC6F2939ED6C5798A5F369A0221BC4F6DDC50F8614ECF72E3B976351057A63",
|
||||
"mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE"
|
||||
}
|
||||
],
|
||||
"ledger_current_index": 309,
|
||||
"status": "success",
|
||||
"validated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
- Any of the [universal error types][].
|
||||
- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
|
||||
|
||||
{% raw-partial file="/docs/_snippets/common-links.md" /%}
|
||||
|
||||
Reference in New Issue
Block a user