Skip to content

Clean up mpt_holders reference documentation + add Try It #3104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 8, 2025
Merged

Clean up mpt_holders reference documentation + add Try It #3104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion @theme/markdoc/components.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ export function Badge(props: {
}
}

type TryItServer = 's1' | 's2' | 'xrplcluster' | 'testnet' | 'devnet'
type TryItServer = 's1' | 's2' | 'xrplcluster' | 'testnet' | 'devnet' | 'testnet-clio' | 'devnet-clio'

export function TryIt(props: {
method: string,
Expand All @@ -164,6 +164,10 @@ export function TryIt(props: {
use_server = "?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F"
} else if (props.server == 'testnet') {
use_server = "?server=wss%3A%2F%2Fs.altnet.rippletest.net%3A51233%2F"
} else if (props.server == 'testnet-clio') {
use_server = "?server=wss%3A%2F%2Fclio.altnet.rippletest.net%3A51233%2F"
} else if (props.server == 'devnet-clio') {
use_server = "?server=wss%3A%2F%2Fclio.devnet.rippletest.net%3A51233%2F"
}
const to_path = `/resources/dev-tools/websocket-api-tool${use_server}#${props.method}`
return (
Expand Down
194 changes: 94 additions & 100 deletions docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
},
"mpt_amount": "200",
"mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13"
}
],
"validated": true
},
"status": "success",
"type": "response",
"warnings": [
{
"account": "rrnAZCqMahreZrKMcZU3t2DZ6yUndT4ubN",
"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": "1",
"mptoken_index": "D137F2E5A5767A06CB7A8F060ADE442A30CFF95028E1AF4B8767E3A56877205A"
}],
"validated": true
"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" /%}
17 changes: 17 additions & 0 deletions resources/dev-tools/components/websocket-api/data/command-list.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -409,6 +409,23 @@
}
]
},
{
"group": "MPT Methods",
"methods": [
{
"name": "mpt_holders",
"description": "Return all holders of an MPT and their balance (Clio only).",
"link": "/docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders",
"clio_only": true,
"body": {
"id": "example_mpt_holders",
"command": "mpt_holders",
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
"ledger_index": "validated"
}
}
]
},
{
"group": "NFT Methods",
"methods": [
Expand Down
2 changes: 1 addition & 1 deletion resources/dev-tools/components/websocket-api/data/connections.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@
"id": "connection-devnet-clio",
"ws_url": "wss://clio.devnet.rippletest.net:51233/",
"jsonrpc-url": "https://clio.devnet.rippletest.net:51234/",
"shortname": "devnet-clio",
"shortname": "Devnet-clio",
"longname": "clio.devnet.rippletest.net (Devnet Public Cluster with Clio)"
}
]