ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-21 12:15:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Migrate content syntax via script

Browse Source 
The changes in this commit were auto-generated by running

tool/migrate.sh

Following this commit, the Dactyl build no longer works but the Redocly
build (mostly) should.
This commit is contained in:
mDuo13
2024-01-31 16:09:41 -08:00
parent 96121303b2
commit 554a3732d4
898 changed files with 19879 additions and 18631 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
content/references/http-websocket-apis/public-api-methods/account-methods/account_channels.md
View File

@@ -8,17 +8,16 @@ labels:
# account_channels
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/AccountChannels.cpp "Source")
_(Added by the [PayChan amendment][]. [New in: rippled 0.33.0][])_
_(Added by the [PayChan amendment][]. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.33.0" %}New in: rippled 0.33.0{% /badge %})_
The `account_channels` method returns information about an account's Payment Channels. This includes only channels where the specified account is the channel's source, not the destination. (A channel's "source" and "owner" are the same.) All information retrieved is relative to a particular version of the ledger.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -28,9 +27,9 @@ An example of the request format:
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_channels",
@@ -41,17 +40,16 @@ An example of the request format:
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```bash
#Syntax: account_channels <account> [<destination_account>] [<ledger>]
rippled account_channels rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn ra5nK24KXen9AHvsdFTKHSANinZseWnPcX validated
```
{% /tab %}
[Try it! >](websocket-api-tool.html#account_channels)
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -68,10 +66,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -97,9 +94,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -125,9 +122,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
200 OK
@@ -153,18 +150,19 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
| Field | Type | Description |
|:---------------|:-------------------------|:---------------------------------|
| `account` | String | The address of the source/owner of the payment channels. This corresponds to the `account` field of the request. |
| `channels` | Array of Channel Objects | Payment channels owned by this `account`. [Updated in: rippled 1.5.0][] |
| `ledger_hash` | String | _(May be omitted)_ The identifying [Hash][] of the ledger version used to generate this response. [New in: rippled 0.90.0][] |
| `ledger_index` | Number | The [Ledger Index][] of the ledger version used to generate this response. [New in: rippled 0.90.0][] |
| `validated` | Boolean | _(May be omitted)_ If `true`, the information in this response comes from a validated ledger version. Otherwise, the information is subject to change. [New in: rippled 0.90.0][] |
| `channels` | Array of Channel Objects | Payment channels owned by this `account`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}Updated in: rippled 1.5.0{% /badge %} |
| `ledger_hash` | String | _(May be omitted)_ The identifying [Hash][] of the ledger version used to generate this response. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.90.0" %}New in: rippled 0.90.0{% /badge %} |
| `ledger_index` | Number | The [Ledger Index][] of the ledger version used to generate this response. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.90.0" %}New in: rippled 0.90.0{% /badge %} |
| `validated` | Boolean | _(May be omitted)_ If `true`, the information in this response comes from a validated ledger version. Otherwise, the information is subject to change. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.90.0" %}New in: rippled 0.90.0{% /badge %} |
| `limit` | Number | _(May be omitted)_ The limit to how many channel objects were actually returned by this request. |
| `marker` | [Marker][] | _(May be omitted)_ Server-defined value for pagination. Pass this to the next call to resume getting results where this call left off. Omitted when there are no additional pages after this one. |
@@ -175,15 +173,15 @@ Each Channel Object has the following fields:
| `account` | String | The owner of the channel, as an [Address][]. |
| `amount` | String | The total amount of [XRP, in drops][] allocated to this channel. |
| `balance` | String | The total amount of [XRP, in drops][], paid out from this channel, as of the ledger version used. (You can calculate the amount of XRP left in the channel by subtracting `balance` from `amount`.) |
| `channel_id` | String | A unique ID for this channel, as a 64-character hexadecimal string. This is also the [ID of the channel object](paychannel.html#paychannel-id-format) in the ledger's state data. |
| `channel_id` | String | A unique ID for this channel, as a 64-character hexadecimal string. This is also the [ID of the channel object](../../../protocol/ledger-data/ledger-entry-types/paychannel.md#paychannel-id-format) in the ledger's state data. |
| `destination_account` | String | The destination account of the channel, as an [Address][]. Only this account can receive the XRP in the channel while it is open. |
| `settle_delay` | Unsigned Integer | The number of seconds the payment channel must stay open after the owner of the channel requests to close it. |
| `public_key` | String | _(May be omitted)_ The public key for the payment channel in the XRP Ledger's [base58][] format. Signed claims against this channel must be redeemed with the matching key pair. |
| `public_key_hex` | String | _(May be omitted)_ The public key for the payment channel in hexadecimal format, if one was specified at channel creation. Signed claims against this channel must be redeemed with the matching key pair. |
| `expiration` | Unsigned Integer | _(May be omitted)_ Time, in [seconds since the Ripple Epoch][], when this channel is set to expire. This expiration date is mutable. If this is before the close time of the most recent validated ledger, the channel is expired. |
| `cancel_after` | Unsigned Integer | _(May be omitted)_ Time, in [seconds since the Ripple Epoch][], of this channel's immutable expiration, if one was specified at channel creation. If this is before the close time of the most recent validated ledger, the channel is expired. |
| `source_tag` | Unsigned Integer | _(May be omitted)_ A 32-bit unsigned integer to use as a [source tag](source-and-destination-tags.html) for payments through this payment channel, if one was specified at channel creation. This indicates the payment channel's originator or other purpose at the source account. Conventionally, if you bounce payments from this channel, you should specify this value in the `DestinationTag` of the return payment. |
| `destination_tag` | Unsigned Integer | _(May be omitted)_ A 32-bit unsigned integer to use as a [destination tag](source-and-destination-tags.html) for payments through this channel, if one was specified at channel creation. This indicates the payment channel's beneficiary or other purpose at the destination account. |
| `source_tag` | Unsigned Integer | _(May be omitted)_ A 32-bit unsigned integer to use as a [source tag](../../../../concepts/transactions/source-and-destination-tags.md) for payments through this payment channel, if one was specified at channel creation. This indicates the payment channel's originator or other purpose at the source account. Conventionally, if you bounce payments from this channel, you should specify this value in the `DestinationTag` of the return payment. |
| `destination_tag` | Unsigned Integer | _(May be omitted)_ A 32-bit unsigned integer to use as a [destination tag](../../../../concepts/transactions/source-and-destination-tags.md) for payments through this channel, if one was specified at channel creation. This indicates the payment channel's beneficiary or other purpose at the destination account. |
## Possible Errors
@@ -192,6 +190,4 @@ Each Channel Object has the following fields:
* `actNotFound` - The address specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

42
content/references/http-websocket-apis/public-api-methods/account-methods/account_currencies.md
View File

@@ -13,10 +13,9 @@ The `account_currencies` command retrieves a list of currencies that an account
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"command": "account_currencies",
@@ -24,9 +23,9 @@ An example of the request format:
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_currencies",
@@ -39,23 +38,24 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: account_currencies account [ledger_index|ledger_hash]
rippled account_currencies rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn validated
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#account_currencies)
[Try it! >](/resources/dev-tools/websocket-api-tool#account_currencies)
The request includes the following parameters:
| `Field` | Type | Required? | Description |
|:---------------|:---------------------|:----------|-------------|
| `account` | String - [Address][] | Yes | Look up currencies this account can send or receive. [Updated in: rippled 1.11.0][] |
| `account` | String - [Address][] | Yes | Look up currencies this account can send or receive. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}Updated in: rippled 1.11.0{% /badge %} |
| `ledger_hash` | String | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | Number or String | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
@@ -65,10 +65,9 @@ The following fields are deprecated and should not be provided: `account_index`,
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"result": {
@@ -101,9 +100,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
{
@@ -136,9 +135,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -151,8 +150,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -164,7 +164,7 @@ The response follows the [standard format][], with a successful result containin
| `send_currencies` | Array of Strings | Array of [Currency Code][]s for currencies that this account can send. |
| `validated` | Boolean | If `true`, this data comes from a validated ledger. |
**Note:** The currencies that an account can send or receive are defined based on a check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method _doesn't_ check whether the trust line is [frozen](freezes.html) or authorized.
**Note:** The currencies that an account can send or receive are defined based on a check of its trust lines. If an account has a trust line for a currency and enough room to increase its balance, it can receive that currency. If the trust line's balance can go down, the account can send that currency. This method _doesn't_ check whether the trust line is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) or authorized.
## Possible Errors
@@ -173,6 +173,4 @@ The response follows the [standard format][], with a successful result containin
* `actNotFound` - The address specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

84
content/references/http-websocket-apis/public-api-methods/account-methods/account_info.md
View File

@@ -15,10 +15,9 @@ The `account_info` command retrieves information about an account, its activity,
An example of an account_info request:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -28,9 +27,9 @@ An example of an account_info request:
"queue": true
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_info",
@@ -43,27 +42,28 @@ An example of an account_info request:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: account_info account [ledger_index|ledger_hash]
rippled account_info rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn validated
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#account_info)
[Try it! >](/resources/dev-tools/websocket-api-tool#account_info)
The request contains the following parameters:
| `Field` | Type | Required? | Description |
|:---------------|:---------------------|:----------|-------------|
| `account` | String - [Address][] | Yes | The account to look up. [Updated in: rippled 1.11.0][] |
| `account` | String - [Address][] | Yes | The account to look up. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}Updated in: rippled 1.11.0{% /badge %} |
| `ledger_hash` | String | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | Number or String | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `queue` | Boolean | No | If `true`, return stats about [queued transactions](transaction-queue.html) sent by this account. Can only be used when querying for the data from the current open ledger. Not available from servers in [Reporting Mode][]. |
| `signer_lists` | Boolean | No | [API v1][]: If `true`, return any [SignerList objects](signerlist.html) associated with this account.<br>[API v2][]: Identical to v1, but also returns an `invalidParams` error if you provide a non-boolean value. |
| `queue` | Boolean | No | If `true`, return stats about [queued transactions](../../../../concepts/transactions/transaction-queue.md) sent by this account. Can only be used when querying for the data from the current open ledger. Not available from servers in [Reporting Mode][]. |
| `signer_lists` | Boolean | No | [API v1][]: If `true`, return any [SignerList objects](../../../protocol/ledger-data/ledger-entry-types/signerlist.md) associated with this account.<br>[API v2][]: Identical to v1, but also returns an `invalidParams` error if you provide a non-boolean value. |
The following fields are deprecated and should not be provided: `ident`, `ledger`, `strict`.
@@ -71,10 +71,9 @@ The following fields are deprecated and should not be provided: `ident`, `ledger
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 5,
@@ -122,9 +121,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -170,9 +169,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -195,45 +194,46 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with the result containing the requested account, its data, and a ledger to which it applies, as the following fields:
| `Field` | Type | Description |
|:-----------------------|:--------|:------------------------------------------|
| `account_data` | Object | The [AccountRoot ledger object](accountroot.html) with this account's information, as stored in the ledger. |
| `account_flags` | Object | The account's flag statuses (see below), based on the `Flags` field of the account. [New in: rippled 1.11.0][] |
| `signer_lists` | Array | [API v1][]: _(Omitted unless the request specified `signer_lists` and at least one SignerList is associated with the account.)_ Array of [SignerList ledger objects](signerlist.html) associated with this account for [Multi-Signing](multi-signing.html). Since an account can own at most one SignerList, this array must have exactly one member if it is present. The field is nested under `account_data`.<br>[API v2][]: Identical to API v1, but the field is returned in the root response instead. [Clio](https://github.com/XRPLF/clio) implements the API v2 behavior in all cases. |
| `account_data` | Object | The [AccountRoot ledger object](../../../protocol/ledger-data/ledger-entry-types/accountroot.md) with this account's information, as stored in the ledger. |
| `account_flags` | Object | The account's flag statuses (see below), based on the `Flags` field of the account. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %} |
| `signer_lists` | Array | [API v1][]: _(Omitted unless the request specified `signer_lists` and at least one SignerList is associated with the account.)_ Array of [SignerList ledger objects](../../../protocol/ledger-data/ledger-entry-types/signerlist.md) associated with this account for [Multi-Signing](../../../../concepts/accounts/multi-signing.md). Since an account can own at most one SignerList, this array must have exactly one member if it is present. The field is nested under `account_data`.<br>[API v2][]: Identical to API v1, but the field is returned in the root response instead. [Clio](https://github.com/XRPLF/clio) implements the API v2 behavior in all cases. |
| `ledger_current_index` | Integer | _(Omitted if `ledger_index` is provided instead)_ The [ledger index][] of the current in-progress ledger, which was used when retrieving this information. |
| `ledger_index` | Integer | _(Omitted if `ledger_current_index` is provided instead)_ The [ledger index][] of the ledger version used when retrieving this information. The information does not contain any changes from ledger versions newer than this one. |
| `queue_data` | Object | _(Omitted unless `queue` specified as `true` and querying the current open ledger.)_ Information about [queued transactions](transaction-cost.html#queued-transactions) sent by this account. This information describes the state of the local `rippled` server, which may be different from other servers in the [peer-to-peer XRP Ledger network](peer-protocol.html). Some fields may be omitted because the values are calculated "lazily" by the queuing mechanism. |
| `validated` | Boolean | True if this data is from a validated ledger version; if omitted or set to false, this data is not final. [New in: rippled 0.26.0][] |
| `queue_data` | Object | _(Omitted unless `queue` specified as `true` and querying the current open ledger.)_ Information about [queued transactions](../../../../concepts/transactions/transaction-cost.md#queued-transactions) sent by this account. This information describes the state of the local `rippled` server, which may be different from other servers in the [peer-to-peer XRP Ledger network](../../../../concepts/networks-and-servers/peer-protocol.md). Some fields may be omitted because the values are calculated "lazily" by the queuing mechanism. |
| `validated` | Boolean | True if this data is from a validated ledger version; if omitted or set to false, this data is not final. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.26.0" %}New in: rippled 0.26.0{% /badge %} |
The `account_flags` field contains the following nested fields:
| `Field` | Type | Description |
|:-----------------------|:--------|:------------------------------------------|
| `defaultRipple` | Boolean | If `true`, the account allows [rippling](rippling.html) on its trust lines by default. |
| `depositAuth` | Boolean | If `true`, the account is using [Deposit Authorization](depositauth.html) and does not accept any payments from unknown parties. |
| `disableMasterKey` | Boolean | If `true`, the account's [master key pair](cryptographic-keys.html) is disabled. |
| `disallowIncomingCheck` | Boolean | If `true`, the account does not allow others to send [Checks](checks.html) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `disallowIncomingNFTokenOffer` | Boolean | If `true`, the account does not allow others to make [NFT buy or sell offers](non-fungible-token-transfers.html) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `disallowIncomingPayChan` | Boolean | If `true`, the account does not allow others to make [Payment Channels](payment-channels.html) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `disallowIncomingTrustline` | Boolean | If `true`, the account does not allow others to make [trust lines](trust-lines-and-issuing.html) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `defaultRipple` | Boolean | If `true`, the account allows [rippling](../../../../concepts/tokens/fungible-tokens/rippling.md) on its trust lines by default. |
| `depositAuth` | Boolean | If `true`, the account is using [Deposit Authorization](../../../../concepts/accounts/depositauth.md) and does not accept any payments from unknown parties. |
| `disableMasterKey` | Boolean | If `true`, the account's [master key pair](../../../../concepts/accounts/cryptographic-keys.md) is disabled. |
| `disallowIncomingCheck` | Boolean | If `true`, the account does not allow others to send [Checks](../../../../concepts/payment-types/checks.md) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `disallowIncomingNFTokenOffer` | Boolean | If `true`, the account does not allow others to make [NFT buy or sell offers](../../../../concepts/tokens/nfts/trading.md) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `disallowIncomingPayChan` | Boolean | If `true`, the account does not allow others to make [Payment Channels](../../../../concepts/payment-types/payment-channels.md) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `disallowIncomingTrustline` | Boolean | If `true`, the account does not allow others to make [trust lines](../../../../concepts/tokens/fungible-tokens/index.md) to it. _(Requires the [DisallowIncoming amendment][])_ |
| `disallowIncomingXRP` | Boolean | If `true`, the account does not want to receive XRP from others. (This is advisory, and not enforced at a protocol level.) |
| `globalFreeze` | Boolean | If `true`, all tokens issued by the account are currently frozen. |
| `noFreeze` | Boolean | If `true`, the account has permanently given up the abilities to freeze individual trust lines or end a global freeze. See [No Freeze](freezes.html#no-freeze) for details. |
| `passwordSpent` | Boolean | If `false`, the account can send a special [key reset transaction](transaction-cost.html#key-reset-transaction) with a transaction cost of 0. The protocol turns this flag on and off automatically; it is not controlled by a user-facing setting. |
| `requireAuthorization` | Boolean | If `true`, the account is using [Authorized Trust Lines](authorized-trust-lines.html) to limit who can hold the tokens it issues. |
| `requireDestinationTag` | Boolean | If `true`, the account [requires a destination tag](require-destination-tags.html) on all payments it receives. |
| `noFreeze` | Boolean | If `true`, the account has permanently given up the abilities to freeze individual trust lines or end a global freeze. See [No Freeze](../../../../concepts/tokens/fungible-tokens/freezes.md#no-freeze) for details. |
| `passwordSpent` | Boolean | If `false`, the account can send a special [key reset transaction](../../../../concepts/transactions/transaction-cost.md#key-reset-transaction) with a transaction cost of 0. The protocol turns this flag on and off automatically; it is not controlled by a user-facing setting. |
| `requireAuthorization` | Boolean | If `true`, the account is using [Authorized Trust Lines](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md) to limit who can hold the tokens it issues. |
| `requireDestinationTag` | Boolean | If `true`, the account [requires a destination tag](../../../../tutorials/manage-account-settings/require-destination-tags.md) on all payments it receives. |
The `queue_data` field, if present, contains the following nested fields:
| `Field` | Type | Description |
|:------------------------|:--------|:-----------------------------------------|
| `txn_count` | Integer | Number of queued transactions from this address. |
| `auth_change_queued` | Boolean | (May be omitted) Whether a transaction in the queue changes this address's [ways of authorizing transactions](transactions.html#authorizing-transactions). If `true`, this address can queue no further transactions until that transaction has been executed or dropped from the queue. |
| `auth_change_queued` | Boolean | (May be omitted) Whether a transaction in the queue changes this address's [ways of authorizing transactions](../../../../concepts/transactions/index.md#authorizing-transactions). If `true`, this address can queue no further transactions until that transaction has been executed or dropped from the queue. |
| `lowest_sequence` | Integer | (May be omitted) The lowest [Sequence Number][] among transactions queued by this address. |
| `highest_sequence` | Integer | (May be omitted) The highest [Sequence Number][] among transactions queued by this address. |
| `max_spend_drops_total` | String | (May be omitted) Integer amount of [drops of XRP][] that could be debited from this address if every transaction in the queue consumes the maximum amount of XRP possible. |
@@ -243,8 +243,8 @@ Each object in the `transactions` array of `queue_data`, if present, may contain
| `Field` | Type | Description |
|:------------------|:--------|:-----------------------------------------------|
| `auth_change` | Boolean | Whether this transaction changes this address's [ways of authorizing transactions](transactions.html#authorizing-transactions). |
| `fee` | String | The [Transaction Cost](transaction-cost.html) of this transaction, in [drops of XRP][]. |
| `auth_change` | Boolean | Whether this transaction changes this address's [ways of authorizing transactions](../../../../concepts/transactions/index.md#authorizing-transactions). |
| `fee` | String | The [Transaction Cost](../../../../concepts/transactions/transaction-cost.md) of this transaction, in [drops of XRP][]. |
| `fee_level` | String | The transaction cost of this transaction, relative to the minimum cost for this type of transaction, in [fee levels][]. |
| `max_spend_drops` | String | The maximum amount of [XRP, in drops][], this transaction could send or destroy. |
| `seq` | Integer | The [Sequence Number][] of this transaction. |
@@ -256,6 +256,6 @@ Each object in the `transactions` array of `queue_data`, if present, may contain
* `actNotFound` - The address specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
[fee levels]: transaction-cost.html#fee-levels
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
[fee levels]: ../../../../concepts/transactions/transaction-cost.md#fee-levels
{% raw-partial file="/_snippets/common-links.md" /%}

49
content/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md
View File

@@ -14,10 +14,9 @@ The `account_lines` method returns information about an account's trust lines, w
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -25,9 +24,9 @@ An example of the request format:
"account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_lines",
@@ -38,17 +37,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: account_lines <account> [<peer>] [<ledger_index>|<ledger_hash>]
rippled account_lines r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#account_lines)
[Try it! >](/resources/dev-tools/websocket-api-tool#account_lines)
The request accepts the following parameters: /Users/peterchen/xrpl-dev-portal/content/references/http-websocket-apis/public-api-methods/account-methods/account_lines.md
@@ -67,10 +67,9 @@ The following parameters are deprecated and may be removed without further notic
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -113,9 +112,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -158,8 +157,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -404,8 +404,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the address of the account and an array of trust line objects. Specifically, the result object contains the following fields:
@@ -429,12 +430,12 @@ Each trust line object has some combination of the following fields:
| `limit_peer` | String | The maximum amount of currency that the counterparty account is willing to owe the perspective account |
| `quality_in` | Unsigned Integer | Rate at which the account values incoming balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio. |
| `quality_out` | Unsigned Integer | Rate at which the account values outgoing balances on this trust line, as a ratio of this value per 1 billion units. (For example, a value of 500 million represents a 0.5:1 ratio.) As a special case, 0 is treated as a 1:1 ratio. |
| `no_ripple` | Boolean | _(May be omitted)_ If `true`, this account has enabled the [No Ripple flag](rippling.html) for this trust line. If present and `false`, this account has disabled the No Ripple flag, but, because the account also has the Default Ripple flag disabled, that is not considered [the default state](ripplestate.html#contributing-to-the-owner-reserve). If omitted, the account has the No Ripple flag disabled for this trust line and Default Ripple enabled. [Updated in: rippled 1.7.0][] |
| `no_ripple_peer` | Boolean | _(May be omitted)_ If `true`, the peer account has enabled the [No Ripple flag](rippling.html) for this trust line. If present and `false`, this account has disabled the No Ripple flag, but, because the account also has the Default Ripple flag disabled, that is not considered [the default state](ripplestate.html#contributing-to-the-owner-reserve). If omitted, the account has the No Ripple flag disabled for this trust line and Default Ripple enabled. [Updated in: rippled 1.7.0][] |
| `authorized` | Boolean | _(May be omitted)_ If `true`, this account has [authorized this trust line](authorized-trust-lines.html). The default is `false`. |
| `peer_authorized`| Boolean | _(May be omitted)_ If `true`, the peer account has [authorized this trust line](authorized-trust-lines.html). The default is `false`. |
| `freeze` | Boolean | _(May be omitted)_ If `true`, this account has [frozen](freezes.html) this trust line. The default is `false`. |
| `freeze_peer` | Boolean | _(May be omitted)_ If `true`, the peer account has [frozen](freezes.html) this trust line. The default is `false`. |
| `no_ripple` | Boolean | _(May be omitted)_ If `true`, this account has enabled the [No Ripple flag](../../../../concepts/tokens/fungible-tokens/rippling.md) for this trust line. If present and `false`, this account has disabled the No Ripple flag, but, because the account also has the Default Ripple flag disabled, that is not considered [the default state](../../../protocol/ledger-data/ledger-entry-types/ripplestate.md#contributing-to-the-owner-reserve). If omitted, the account has the No Ripple flag disabled for this trust line and Default Ripple enabled. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.7.0" %}Updated in: rippled 1.7.0{% /badge %} |
| `no_ripple_peer` | Boolean | _(May be omitted)_ If `true`, the peer account has enabled the [No Ripple flag](../../../../concepts/tokens/fungible-tokens/rippling.md) for this trust line. If present and `false`, this account has disabled the No Ripple flag, but, because the account also has the Default Ripple flag disabled, that is not considered [the default state](../../../protocol/ledger-data/ledger-entry-types/ripplestate.md#contributing-to-the-owner-reserve). If omitted, the account has the No Ripple flag disabled for this trust line and Default Ripple enabled. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.7.0" %}Updated in: rippled 1.7.0{% /badge %} |
| `authorized` | Boolean | _(May be omitted)_ If `true`, this account has [authorized this trust line](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md). The default is `false`. |
| `peer_authorized`| Boolean | _(May be omitted)_ If `true`, the peer account has [authorized this trust line](../../../../concepts/tokens/fungible-tokens/authorized-trust-lines.md). The default is `false`. |
| `freeze` | Boolean | _(May be omitted)_ If `true`, this account has [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) this trust line. The default is `false`. |
| `freeze_peer` | Boolean | _(May be omitted)_ If `true`, the peer account has [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md) this trust line. The default is `false`. |
## Possible Errors
@@ -444,6 +445,4 @@ Each trust line object has some combination of the following fields:
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `actMalformed` - If the `marker` field provided is not acceptable.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

36
content/references/http-websocket-apis/public-api-methods/account-methods/account_nfts.md
View File

@@ -15,12 +15,11 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Request Format
An example of the request format:
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"command": "account_nfts",
@@ -28,9 +27,9 @@ An example of the request format:
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_nfts",
@@ -40,10 +39,11 @@ An example of the request format:
}]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#account_nfts)
[Try it! >](/resources/dev-tools/websocket-api-tool#account_nfts)
The request includes the following parameters:
@@ -59,10 +59,9 @@ The request includes the following parameters:
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"result": {
@@ -93,9 +92,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -125,8 +124,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -145,10 +145,10 @@ Each object in the `account_nfts` array represents one [NFToken][] and has the f
| `Field` | Type | Description |
|:---------------|:---------------------|:-------------------------------------|
| `Flags` | Number | A bit-map of boolean flags enabled for this NFToken. See [NFToken Flags](nftoken.html#nftoken-flags) for possible values. |
| `Flags` | Number | A bit-map of boolean flags enabled for this NFToken. See [NFToken Flags](../../../protocol/data-types/nftoken.md#nftoken-flags) for possible values. |
| `Issuer` | String - [Address][] | The account that issued this NFToken. |
| `NFTokenID` | String | The unique identifier of this NFToken, in hexadecimal. |
| `NFTokenTaxon` | Number | The unscrambled version of this token's [taxon](nftoken.html#nftokentaxon). Several tokens with the same taxon might represent instances of a limited series. |
| `NFTokenTaxon` | Number | The unscrambled version of this token's [taxon](../../../protocol/data-types/nftoken.md#nftokentaxon). Several tokens with the same taxon might represent instances of a limited series. |
| `URI` | String | The URI data associated with this NFToken, in hexadecimal. |
| `nft_serial` | Number | The token sequence number of this NFToken, which is unique for its issuer. |
@@ -159,6 +159,4 @@ Each object in the `account_nfts` array represents one [NFToken][] and has the f
* `actNotFound` - The [Address][] specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

61
content/references/http-websocket-apis/public-api-methods/account-methods/account_objects.md
View File

@@ -13,25 +13,24 @@ The `account_objects` command returns the raw [ledger format][] for all ledger e
The types of objects that may appear in the `account_objects` response include:
- [Offer entries](offer.html) for orders that are currently live, unfunded, or expired but not yet removed. (See [Lifecycle of an Offer](offers.html#lifecycle-of-an-offer) for more information.)
- [RippleState entries](ripplestate.html) for trust lines where this account's side is not in the default state.
- The account's [SignerList](signerlist.html), if the account has [multi-signing](multi-signing.html) enabled.
- [Escrow entries](escrow.html) for held payments that have not yet been executed or canceled.
- [PayChannel entries](paychannel.html) for open payment channels.
- [Check entries](check.html) for pending Checks.
- [DepositPreauth entries](depositpreauth-object.html) for deposit preauthorizations.
- [Ticket entries](tickets.html) for Tickets.
- [NFTokenOffer entries](nftokenoffer.html) for offers to buy or sell an NFT.
- [NFTokenPage entries](nftokenpage.html) for collections of NFTs. [New in: rippled 1.11.0][]
- [Offer entries](../../../protocol/ledger-data/ledger-entry-types/offer.md) for orders that are currently live, unfunded, or expired but not yet removed. (See [Lifecycle of an Offer](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer) for more information.)
- [RippleState entries](../../../protocol/ledger-data/ledger-entry-types/ripplestate.md) for trust lines where this account's side is not in the default state.
- The account's [SignerList](../../../protocol/ledger-data/ledger-entry-types/signerlist.md), if the account has [multi-signing](../../../../concepts/accounts/multi-signing.md) enabled.
- [Escrow entries](../../../../concepts/payment-types/escrow.md) for held payments that have not yet been executed or canceled.
- [PayChannel entries](../../../protocol/ledger-data/ledger-entry-types/paychannel.md) for open payment channels.
- [Check entries](../../../protocol/ledger-data/ledger-entry-types/check.md) for pending Checks.
- [DepositPreauth entries](../../../protocol/ledger-data/ledger-entry-types/depositpreauth.md) for deposit preauthorizations.
- [Ticket entries](../../../../concepts/accounts/tickets.md) for Tickets.
- [NFTokenOffer entries](../../../protocol/ledger-data/ledger-entry-types/nftokenoffer.md) for offers to buy or sell an NFT.
- [NFTokenPage entries](../../../protocol/ledger-data/ledger-entry-types/nftokenpage.md) for collections of NFTs. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.11.0" %}New in: rippled 1.11.0{% /badge %}
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 8,
@@ -43,9 +42,9 @@ An example of the request format:
"limit": 10
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_objects",
@@ -60,23 +59,23 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: account_objects <account> [<ledger>]
rippled account_objects r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
| `Field` | Type | Required? | Description |
|:-------------------------|:-----------------|:----------|-------------|
| `account` | String | Yes | A unique identifier for the account, most commonly the account's [Address][]. |
| `deletion_blockers_only` | Boolean | No | If `true`, the response only includes objects that would block this account from [being deleted](deleting-accounts.html). The default is `false`. [New in: rippled 1.4.0][] |
| `deletion_blockers_only` | Boolean | No | If `true`, the response only includes objects that would block this account from [being deleted](../../../../concepts/accounts/deleting-accounts.md). The default is `false`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %} |
| `ledger_hash` | [Hash][] | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `limit` | Number | No | The maximum number of objects to include in the results. Must be within the inclusive range `10` to `400` on non-admin connections. The default is `200`. |
@@ -89,10 +88,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 8,
@@ -350,9 +348,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
{
@@ -609,9 +607,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -1201,8 +1199,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -1224,8 +1223,4 @@ The response follows the [standard format][], with a successful result containin
* `actNotFound` - The [Address][] specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

46
content/references/http-websocket-apis/public-api-methods/account-methods/account_offers.md
View File

@@ -8,16 +8,15 @@ labels:
# account_offers
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/AccountOffers.cpp "Source")
The `account_offers` method retrieves a list of [offers](offers.html) made by a given [account](accounts.html) that are outstanding as of a particular [ledger version](ledgers.html).
The `account_offers` method retrieves a list of [offers](../../../../concepts/tokens/decentralized-exchange/offers.md) made by a given [account](../../../../concepts/accounts/accounts.md) that are outstanding as of a particular [ledger version](../../../../concepts/ledgers/index.md).
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 9,
@@ -25,9 +24,9 @@ An example of the request format:
"account": "rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_offers",
@@ -38,17 +37,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: account_offers account [ledger_index]
rippled account_offers rpP2JgiMyTF5jR5hLG3xHCPi1knBb1v9cM current
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#account_offers)
[Try it! >](/resources/dev-tools/websocket-api-tool#account_offers)
A request can include the following parameters:
@@ -66,10 +66,9 @@ The following parameters are deprecated should not be provided: `ledger`, `stric
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 9,
@@ -107,9 +106,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -157,9 +156,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -183,8 +182,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -203,11 +203,11 @@ Each offer object contains the following fields:
| `Field` | Type | Description |
|:-------------|:-----------------|:-------------------------------------------|
| `flags` | Unsigned integer | Options set for this offer entry as bit-flags. |
| `seq` | Unsigned integer | Sequence number of the transaction that created this entry. (Transaction [sequence numbers](basic-data-types.html#account-sequence) are relative to accounts.) |
| `seq` | Unsigned integer | Sequence number of the transaction that created this entry. (Transaction [sequence numbers](../../../protocol/data-types/basic-data-types.md#account-sequence) are relative to accounts.) |
| `taker_gets` | String or Object | The amount the account accepting the offer receives, as a String representing an amount in XRP, or a currency specification object. (See [Specifying Currency Amounts][Currency Amount]) |
| `taker_pays` | String or Object | The amount the account accepting the offer provides, as a String representing an amount in XRP, or a currency specification object. (See [Specifying Currency Amounts][Currency Amount]) |
| `quality` | String | The exchange rate of the offer, as the ratio of the original `taker_pays` divided by the original `taker_gets`. When executing offers, the offer with the most favorable (lowest) quality is consumed first; offers with the same quality are executed from oldest to newest. [New in: rippled 0.29.0][] |
| `expiration` | Unsigned integer | (May be omitted) A time after which this offer is considered unfunded, as the number of [seconds since the Ripple Epoch][]. See also: [Offer Expiration](offers.html#offer-expiration). [New in: rippled 0.30.1][] |
| `quality` | String | The exchange rate of the offer, as the ratio of the original `taker_pays` divided by the original `taker_gets`. When executing offers, the offer with the most favorable (lowest) quality is consumed first; offers with the same quality are executed from oldest to newest. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.29.0" %}New in: rippled 0.29.0{% /badge %} |
| `expiration` | Unsigned integer | (May be omitted) A time after which this offer is considered unfunded, as the number of [seconds since the Ripple Epoch][]. See also: [Offer Expiration](../../../../concepts/tokens/decentralized-exchange/offers.md#offer-expiration). {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.30.1" %}New in: rippled 0.30.1{% /badge %} |
## Possible Errors
@@ -217,6 +217,4 @@ Each offer object contains the following fields:
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `actMalformed` - The `marker` field provided is incorrect.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

42
content/references/http-websocket-apis/public-api-methods/account-methods/account_tx.md
View File

@@ -15,10 +15,9 @@ The `account_tx` method retrieves a list of validated transactions that involve
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -31,9 +30,9 @@ An example of the request format:
"forward": false
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "account_tx",
@@ -49,25 +48,26 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
# Syntax: account_tx account [ledger_index_min [ledger_index_max]] [limit] [offset] [binary] [count] [descending]
# For binary/count/descending, use the parameter name for true and omit for false.
rippled -- account_tx rLNaPoKeeBjZe2qs6x52yVPZpZ8td4dc6w -1 -1 2 0 binary descending
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#account_tx)
[Try it! >](/resources/dev-tools/websocket-api-tool#account_tx)
The request includes the following parameters:
| `Field` | Type | Description |
|:-------------------|:-------------------------------------------|:-----------|
| `account` | String | A unique identifier for the account, most commonly the account's address. |
| `tx_type` | String | _(Optional)_ **Clio Only** Return only transactions of a specific type, such as "Clawback", "AccountSet", "AccountDelete", et al. Case-insensitive. Supports any transaction type except `AMM*` (See [Transaction Types](transaction-types.html).) [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE") |
| `tx_type` | String | _(Optional)_ **Clio Only** Return only transactions of a specific type, such as "Clawback", "AccountSet", "AccountDelete", et al. Case-insensitive. Supports any transaction type except `AMM*` (See [Transaction Types](../../../protocol/transactions/types/index.md).) {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %} |
| `ledger_index_min` | Integer | [API v1][]: _(Optional)_ Use to specify the earliest ledger to include transactions from. A value of `-1` instructs the server to use the earliest validated ledger version available.<br>[API v2][]: Identical to v1, but also returns a `lgrIdxMalformed` error if a value is specified beyond the range of ledgers the server has. |
| `ledger_index_max` | Integer | [API v1][]: _(Optional)_ Use to specify the most recent ledger to include transactions from. A value of `-1` instructs the server to use the most recent validated ledger version available.<br>[API v2][]: Identical to v1, but also returns a `lgrIdxMalformed` error if a value is specified beyond the range of ledgers the server has. |
| `ledger_hash` | String | _(Optional)_ Use to look for transactions from a single ledger only. (See [Specifying Ledgers][].) |
@@ -91,10 +91,9 @@ In the time between requests, `"ledger_index_min": -1` and `"ledger_index_max":
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -242,9 +241,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
{
@@ -392,9 +391,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -425,8 +424,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -458,8 +458,6 @@ Each transaction object includes the following fields, depending on whether it w
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `actMalformed` - The [Address][] specified in the `account` field of the request is not formatted properly.
* `lgrIdxMalformed` - The ledger specified by the `ledger_index_min` or `ledger_index_max` does not exist, or if it does exist but the server does not have it.
* `lgrIdxsInvalid` - Either the request specifies a `ledger_index_max` that is before the `ledger_index_min`, or the server does not have a validated ledger range because it is [not synced with the network](server-doesnt-sync.html).
* `lgrIdxsInvalid` - Either the request specifies a `ledger_index_max` that is before the `ledger_index_min`, or the server does not have a validated ledger range because it is [not synced with the network](../../../../infrastructure/troubleshooting/server-doesnt-sync.md).
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

44
content/references/http-websocket-apis/public-api-methods/account-methods/gateway_balances.md
View File

@@ -9,19 +9,18 @@ labels:
# gateway_balances
[[Source]](https://github.com/XRPLF/rippled/blob/9111ad1a9dc37d49d085aa317712625e635197c0/src/ripple/rpc/handlers/GatewayBalances.cpp "Source")
The `gateway_balances` command calculates the total balances issued by a given account, optionally excluding amounts held by [operational addresses](account-types.html). [New in: rippled 0.28.2][]
The `gateway_balances` command calculates the total balances issued by a given account, optionally excluding amounts held by [operational addresses](../../../../concepts/accounts/account-types.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.28.2" %}New in: rippled 0.28.2{% /badge %}
**Caution:** Some public servers disable this API method because it can require a large amount of processing.
## Request Format
An example of the request format:
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_gateway_balances_1",
@@ -32,9 +31,9 @@ An example of the request format:
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "gateway_balances",
@@ -51,21 +50,23 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json gateway_balances ' {"account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", "hotwallet": ["rKm4uWpg9tfwbVSeATv4KxDe6mpE9yPkgJ", "ra7JkEzrgeKHdzKgo4EUUVBnxggY4z37kt"],"ledger_index": "validated","strict": true} '
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
| `Field` | Type | Description |
|:---------------|:---------------------------|:-------------------------------|
| `account` | String | The [Address][] to check. This should be the [issuing address](account-types.html) |
| `account` | String | The [Address][] to check. This should be the [issuing address](../../../../concepts/accounts/account-types.md) |
| `strict` | Boolean | _(Optional)_ If true, only accept an address or public key for the account parameter. Defaults to false. |
| `hotwallet` | String or Array | _(Optional)_ An [operational address](account-types.html) to exclude from the balances issued, or an array of such addresses. |
| `hotwallet` | String or Array | _(Optional)_ An [operational address](../../../../concepts/accounts/account-types.md) to exclude from the balances issued, or an array of such addresses. |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger version to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
@@ -73,10 +74,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 3,
@@ -142,9 +142,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
{
@@ -209,8 +209,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -276,8 +277,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -286,7 +288,7 @@ The response follows the [standard format][], with a successful result containin
| `account` | String - [Address][] | The address of the account that issued the balances. |
| `obligations` | Object | (Omitted if empty) Total amounts issued to addresses not excluded, as a map of currencies to the total value issued. |
| `balances` | Object | _(Omitted if empty)_ Amounts issued to the `hotwallet` addresses from the request. The keys are addresses and the values are arrays of currency amounts they hold. |
| `assets` | Object | _(Omitted if empty)_ Total amounts held that are issued by others. In the recommended configuration, the [issuing address](account-types.html) should have none. |
| `assets` | Object | _(Omitted if empty)_ Total amounts held that are issued by others. In the recommended configuration, the [issuing address](../../../../concepts/accounts/account-types.md) should have none. |
| `ledger_hash` | String - [Hash][] | _(May be omitted)_ The identifying hash of the ledger version that was used to generate this response. |
| `ledger_index` | Number - [Ledger Index][] | _(May be omitted)_ The ledger index of the ledger version that was used to generate this response. |
| `ledger_current_index` | Number - [Ledger Index][] | _(Omitted if `ledger_current_index` is provided)_ The [ledger index][] of the current in-progress ledger version, which was used to retrieve this information. |
@@ -299,6 +301,4 @@ The response follows the [standard format][], with a successful result containin
* `actNotFound` - The [Address][] specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/account-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: account-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Account Methods
An account in the XRP Ledger represents a holder of XRP and a sender of transactions. Use these methods to work with account info.
An account in the XRP Ledger represents a holder of XRP and a sender of transactions. Use these methods to work with account info.
{% child-pages /%}

36
content/references/http-websocket-apis/public-api-methods/account-methods/noripple_check.md
View File

@@ -8,18 +8,17 @@ labels:
# noripple_check
[[Source]](https://github.com/XRPLF/rippled/blob/9111ad1a9dc37d49d085aa317712625e635197c0/src/ripple/rpc/handlers/NoRippleCheck.cpp "Source")
The `noripple_check` command provides a quick way to check the status of [the Default Ripple field for an account and the No Ripple flag of its trust lines](rippling.html), compared with the recommended settings.
The `noripple_check` command provides a quick way to check the status of [the Default Ripple field for an account and the No Ripple flag of its trust lines](../../../../concepts/tokens/fungible-tokens/rippling.md), compared with the recommended settings.
## Request Format
An example of the request format:
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 0,
@@ -31,9 +30,9 @@ An example of the request format:
"transactions": true
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "noripple_check",
@@ -48,8 +47,9 @@ An example of the request format:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -58,7 +58,7 @@ The request includes the following parameters:
|:---------------|:---------------------------|:-------------------------------|
| `account` | String | A unique identifier for the account, most commonly the account's address. |
| `role` | String | Whether the address refers to a `gateway` or `user`. Recommendations depend on the role of the account. Issuers must have Default Ripple enabled and must disable No Ripple on all trust lines. Users should have Default Ripple disabled, and should enable No Ripple on all trust lines. |
| `transactions` | Boolean | [API v1][]: _(Optional)_ If `true`, include an array of suggested [transactions](transaction-formats.html), as JSON objects, that you can sign and submit to fix the problems. The default is `false`.<br>[API v2][]: Identical to v1, but also returns an `invalidParams` error if you use a non-boolean value. |
| `transactions` | Boolean | [API v1][]: _(Optional)_ If `true`, include an array of suggested [transactions](../../../protocol/transactions/index.md), as JSON objects, that you can sign and submit to fix the problems. The default is `false`.<br>[API v2][]: Identical to v1, but also returns an `invalidParams` error if you use a non-boolean value. |
| `limit` | Unsigned Integer | _(Optional)_ The maximum number of trust line problems to include in the results. Defaults to 300. |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
@@ -67,10 +67,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 0,
@@ -120,9 +119,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -172,8 +171,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -181,7 +181,7 @@ The response follows the [standard format][], with a successful result containin
|:-----------------------|:-------|:-------------------------------------------|
| `ledger_current_index` | Number | The [ledger index][] of the ledger used to calculate these results. |
| `problems` | Array | Array of strings with human-readable descriptions of the problems. This includes up to one entry if the account's Default Ripple setting is not as recommended, plus up to `limit` entries for trust lines whose No Ripple setting is not as recommended. |
| `transactions` | Array | (May be omitted) If the request specified `transactions` as `true`, this is an array of JSON objects, each of which is the JSON form of a [transaction](transaction-formats.html) that should fix one of the described problems. The length of this array is the same as the `problems` array, and each entry is intended to fix the problem described at the same index into that array. |
| `transactions` | Array | (May be omitted) If the request specified `transactions` as `true`, this is an array of JSON objects, each of which is the JSON form of a [transaction](../../../protocol/transactions/index.md) that should fix one of the described problems. The length of this array is the same as the `problems` array, and each entry is intended to fix the problem described at the same index into that array. |
## Possible Errors
@@ -190,6 +190,4 @@ The response follows the [standard format][], with a successful result containin
* `actNotFound` - The [Address][] specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

77
content/references/http-websocket-apis/public-api-methods/clio-methods/ledger-clio.md
View File

@@ -8,28 +8,24 @@ labels:
# ledger
[[Source]](https://github.com/XRPLF/clio/blob/master/src/rpc/handlers/Ledger.cpp "Source")
The `ledger` command retrieves information about the public [ledger](ledgers.html). [New in: Clio v1.0.0](https://github.com/XRPLF/clio/releases/tag/1.0.0 "BADGE_BLUE")
The `ledger` command retrieves information about the public [ledger](../../../../concepts/ledgers/index.md). {% badge href="https://github.com/XRPLF/clio/releases/tag/1.0.0" %}New in: Clio v1.0.0{% /badge %}
Note that the Clio server returns validated ledger data by default.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
{% tabs %}
*WebSocket*
{% tab label="WebSocket" %}
{% code-snippet file="/_api-examples/ledger-clio/wsrpc-request.json" language="json" /%}
{% /tab %}
```json
{% include '_api-examples/ledger-clio/wsrpc-request.json' %}
```
{% tab label="JSON-RPC" %}
{% code-snippet file="/_api-examples/ledger-clio/jsonrpc-request.json" language="json" /%}
{% /tab %}
*JSON-RPC*
```json
{% include '_api-examples/ledger-clio/jsonrpc-request.json' %}
```
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
<!-- [Try it! >](websocket-api-tool.html#ledger) -->
@@ -47,35 +43,31 @@ The request can contain the following parameters:
The `ledger` field is deprecated and may be removed without further notice.
> **Note:** The `ledger` command in Clio does not support the following fields that are supported by [ledger command in rippled](ledger.html):
>
> * `accounts`
> * `full`
> * `queue`
>
> Clio will **always** forward the request to `rippled` when any of the above fields is set to `true`.
{% admonition type="info" name="Note" %}
The `ledger` command in Clio does not support the following fields that are supported by [ledger command in rippled](../ledger-methods/ledger.md):
* `accounts`
* `full`
* `queue`
Clio will **always** forward the request to `rippled` when any of the above fields is set to `true`.
{% /admonition %}
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
{% tabs %}
*WebSocket*
{% tab label="WebSocket" %}
{% code-snippet file="/_api-examples/ledger-clio/wsrpc-response.json" language="json" /%}
{% /tab %}
```json
{% include '_api-examples/ledger-clio/wsrpc-response.json' %}
```
{% tab label="JSON-RPC" %}
{% code-snippet file="/_api-examples/ledger-clio/jsonrpc-response.json" language="json" prefix="200 OK\n\n" /%}
{% /tab %}
*JSON-RPC*
```json
200 OK
{% include '_api-examples/ledger-clio/jsonrpc-response.json' %}
```
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing information about the ledger, including the following fields:
@@ -83,8 +75,8 @@ The response follows the [standard format][], with a successful result containin
|:-------------------------------|:--------|:----------------------------------|
| `ledger` | Object | The complete header data of this ledger. |
| `ledger.account_hash` | String | Hash of all account state information in this ledger, as hex |
| `ledger.accountState` | Array | (Omitted unless requested) All the [account-state information](ledger-data-formats.html) in this ledger. |
| `ledger.close_flags` | Integer | A bit-map of [flags relating to the closing of this ledger](ledger-header.html#close-flags). |
| `ledger.accountState` | Array | (Omitted unless requested) All the [account-state information](../../../protocol/ledger-data/index.md) in this ledger. |
| `ledger.close_flags` | Integer | A bit-map of [flags relating to the closing of this ledger](../../../protocol/ledger-data/ledger-header.md#close-flags). |
| `ledger.close_time` | Integer | The time this ledger was closed, in [seconds since the Ripple Epoch][]. |
| `ledger.close_time_human` | String | The time this ledger was closed, in human-readable format. Always uses the UTC time zone. |
| `ledger.close_time_resolution` | Integer | Ledger close times are rounded to within this many seconds. |
@@ -101,11 +93,11 @@ The response follows the [standard format][], with a successful result containin
| `validated` | Boolean | _(May be omitted)_ If `true`, this is a validated ledger version. If omitted or set to `false`, this ledger's data is not final. |
| `diff` | Object | _(Omitted unless requested with the `diff` parameter)_ Object containing an array of hashes that were added, modified, or deleted as part of applying transactions for the ledger. |
If the request specified `"owner_funds": true` and expanded transactions, the response has a field `owner_funds` in the `metaData` object of each [OfferCreate transaction][]. The purpose of this field is to make it easier to track the [funding status of offers](offers.html#lifecycle-of-an-offer) with each new validated ledger. This field is defined slightly differently than the version of this field in [Order Book subscription streams](subscribe.html#order-book-streams):
If the request specified `"owner_funds": true` and expanded transactions, the response has a field `owner_funds` in the `metaData` object of each [OfferCreate transaction][]. The purpose of this field is to make it easier to track the [funding status of offers](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer) with each new validated ledger. This field is defined slightly differently than the version of this field in [Order Book subscription streams](../subscription-methods/subscribe.md#order-book-streams):
| `Field` | Value | Description |
|:--------------|:-------|:----------------------------------------------------|
| `owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is [frozen](freezes.html). |
| `owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
If the request specified `"diff": true`, the response has an object `diff`. The fields of this object are as follows:
@@ -117,9 +109,7 @@ If the request specified `"diff": true`, the response has an object `diff`. The
### Response When `diff` is `true`
````json
{% include '_api-examples/ledger-clio/jsonrpc-diff-response.json' %}
````
`{% code-snippet file="/_api-examples/ledger-clio/jsonrpc-diff-response.json" language="json" /%}`
## Possible Errors
@@ -127,7 +117,4 @@ If the request specified `"diff": true`, the response has an object `diff`. The
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

47
content/references/http-websocket-apis/public-api-methods/clio-methods/nft_history.md
View File

@@ -9,17 +9,16 @@ labels:
[[Source]](https://github.com/XRPLF/clio/blob/4a5cb962b6971872d150777881801ce27ae9ed1a/src/rpc/handlers/NFTHistory.cpp "Source")
The `nft_history` command asks the Clio server for past transaction metadata for the [NFT](non-fungible-tokens.html) being queried. [New in: Clio v1.1.0](https://github.com/XRPLF/clio/releases/tag/1.1.0 "BADGE_BLUE")
The `nft_history` command asks the Clio server for past transaction metadata for the [NFT](../../../../concepts/tokens/nfts/index.md) being queried. {% badge href="https://github.com/XRPLF/clio/releases/tag/1.1.0" %}New in: Clio v1.1.0{% /badge %}
**Note** `nft_history` returns only _successful_ transactions associated with the NFT.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -27,9 +26,9 @@ An example of the request format:
"nft_id": "00080000B4F4AFC5FBCBD76873F18006173D2193467D3EE70000099B00000000"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "nft_history",
@@ -40,8 +39,9 @@ An example of the request format:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
<!-- To DO: Add an example command to the assets/js/apitool-methods-ws.js file. The WebSocket Tool requires access to a publicly available Clio server.
[Try it! >](websocket-api-tool.html#nft_history)-->
@@ -66,10 +66,9 @@ The request contains the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 0,
@@ -152,9 +151,9 @@ An example of a successful response:
]
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -235,15 +234,15 @@ An example of a successful response:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
With the `binary` parameter set to _true_, you receive a compact response that uses hex strings. It's not human readable, but much more concise.
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 0,
@@ -271,9 +270,9 @@ With the `binary` parameter set to _true_, you receive a compact response that u
]
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -300,7 +299,9 @@ With the `binary` parameter set to _true_, you receive a compact response that u
}
```
<!-- MULTICODE_BLOCK_END -->
{% /tab %}
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -326,7 +327,7 @@ Each transaction object includes the following fields, depending on whether it w
| `tx_blob` | String | (Binary mode only) Unique hashed String representing the transaction. |
| `validated` | Boolean | Whether or not the transaction is included in a validated ledger. Any transaction not yet in a validated ledger is subject to change. |
For definitions of the fields returned in the `tx` object, see [Transaction Metadata](transaction-metadata.html).
For definitions of the fields returned in the `tx` object, see [Transaction Metadata](../../../protocol/transactions/metadata.md).
## Possible Errors
@@ -334,8 +335,6 @@ For definitions of the fields returned in the `tx` object, see [Transaction Meta
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `actMalformed` - The [Address][] specified in the `account` field of the request is not formatted properly.
* `lgrIdxMalformed` - The ledger specified by the `ledger_index_min` or `ledger_index_max` does not exist, or if it does exist but the server does not have it.
* `lgrIdxsInvalid` - Either the request specifies a `ledger_index_max` that is before the `ledger_index_min`, or the server does not have a validated ledger range because it is [not synced with the network](server-doesnt-sync.html).
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
* `lgrIdxsInvalid` - Either the request specifies a `ledger_index_max` that is before the `ledger_index_min`, or the server does not have a validated ledger range because it is [not synced with the network](../../../../infrastructure/troubleshooting/server-doesnt-sync.md).
{% raw-partial file="/_snippets/common-links.md" /%}

33
content/references/http-websocket-apis/public-api-methods/clio-methods/nft_info.md
View File

@@ -8,15 +8,14 @@ labels:
# nft_info
[[Source]](https://github.com/XRPLF/clio/blob/4a5cb962b6971872d150777881801ce27ae9ed1a/src/rpc/handlers/NFTInfo.cpp "Source")
The `nft_info` command asks the Clio server for information about the [NFT](non-fungible-tokens.html) being queried. [New in: Clio v1.1.0](https://github.com/XRPLF/clio/releases/tag/1.1.0 "BADGE_BLUE")
The `nft_info` command asks the Clio server for information about the [NFT](../../../../concepts/tokens/nfts/index.md) being queried. {% badge href="https://github.com/XRPLF/clio/releases/tag/1.1.0" %}New in: Clio v1.1.0{% /badge %}
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -24,9 +23,9 @@ An example of the request format:
"nft_id": "00080000B4F4AFC5FBCBD76873F18006173D2193467D3EE70000099B00000000"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "nft_info",
@@ -37,8 +36,9 @@ An example of the request format:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
<!-- To DO: Add an example command to the assets/js/apitool-methods-ws.js file. The WebSocket Tool requires access to a publicly available Clio server.
[Try it! >](websocket-api-tool.html#nft_info)-->
@@ -57,10 +57,9 @@ If you do not specify a ledger version, Clio uses the latest validated ledger.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -90,9 +89,9 @@ An example of a successful response:
]
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -121,8 +120,9 @@ An example of a successful response:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing an `nft_info` response object with some arrangement of the following fields:
@@ -133,7 +133,7 @@ The response follows the [standard format][], with a successful result containin
| `owner` | String | The account ID of this NFT's owner at this ledger index. |
| `is_burned` | Boolean | Returns `true` if the NFT is burned at this ledger, or `false` otherwise. |
| `flags ` | Integer | The flag set of this NFT. |
| `transfer_fee` | Integer | The transfer fee of this NFT. See [NFTokenMint Fields](nftokenmint.html#nftokenmint-fields) for more information on transfer fees. |
| `transfer_fee` | Integer | The transfer fee of this NFT. See [NFTokenMint Fields](../../../protocol/transactions/types/nftokenmint.md#nftokenmint-fields) for more information on transfer fees. |
| `issuer` | String | The account ID which denotes the issuer of this NFT. |
| `nft_taxon` | Integer | The NFT’s taxon. |
| `nft_sequence` | Integer | The NFT’s sequence number. |
@@ -144,7 +144,4 @@ The response follows the [standard format][], with a successful result containin
* Any of the [universal error types][].
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

56
content/references/http-websocket-apis/public-api-methods/clio-methods/server_info-clio.md
View File

@@ -8,25 +8,24 @@ labels:
# server_info
[[Source]](https://github.com/XRPLF/clio/blob/master/src/rpc/handlers/ServerInfo.cpp "Source")
The `server_info` command asks the [Clio server](the-clio-server.html) for a human-readable version of various information about the Clio server being queried. For `rippled` servers, see [`server_info` (`rippled`)](server_info.html) instead. [New in: Clio v1.0.0](https://github.com/XRPLF/clio/releases/tag/1.0.0 "BADGE_BLUE")
The `server_info` command asks the [Clio server](../../../../concepts/networks-and-servers/the-clio-server.md) for a human-readable version of various information about the Clio server being queried. For `rippled` servers, see [`server_info` (`rippled`)](../server-info-methods/server_info.md) instead. {% badge href="https://github.com/XRPLF/clio/releases/tag/1.0.0" %}New in: Clio v1.0.0{% /badge %}
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
"command": "server_info"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "server_info",
@@ -35,8 +34,9 @@ An example of the request format:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
<!-- [Try it! >](websocket-api-tool.html#server_info) -->
@@ -48,10 +48,9 @@ When a client connects to the Clio server over `localhost`, the response include
An example of a successful response when client connects over `localhost`:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -261,9 +260,9 @@ An example of a successful response when client connects over `localhost`:
]
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -474,15 +473,15 @@ An example of a successful response when client connects over `localhost`:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
An example of a successful response when client does not connect over `localhost`:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -518,9 +517,9 @@ An example of a successful response when client does not connect over `localhost
]
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -557,8 +556,9 @@ An example of a successful response when client does not connect over `localhost
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing an `info` object as its only field.
@@ -583,15 +583,15 @@ The `info` object may have some arrangement of the following fields:
| `subscriptions.account` | | |
| `subscriptions.accounts_proposed` | | |
| `subscriptions.books` | | |
| `time` | String | The current time in UTC, according to the server's clock. [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE") |
| `uptime` | Number | Number of consecutive seconds that the server has been operational. [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE") |
| `amendment_blocked` | Boolean | _(May be omitted)_ Whether the Clio server is [Amendment Blocked](amendments.html#amendment-blocked-clio-servers) [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE") |
| `load_factor` | Number | The load-scaled open ledger transaction cost the server is currently enforcing, as a multiplier on the base transaction cost. For example, at `1000` load factor and a reference transaction cost of 10 drops of XRP, the load-scaled transaction cost is 10,000 drops (0.01 XRP). The load factor is determined by the highest of the [individual server's load factor](transaction-cost.html#local-load-cost), the cluster's load factor, the [open ledger cost](transaction-cost.html#open-ledger-cost) and the overall network's load factor. |
| `time` | String | The current time in UTC, according to the server's clock. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %} |
| `uptime` | Number | Number of consecutive seconds that the server has been operational. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %} |
| `amendment_blocked` | Boolean | _(May be omitted)_ Whether the Clio server is [Amendment Blocked](../../../../concepts/networks-and-servers/amendments.md#amendment-blocked-clio-servers) {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %} |
| `load_factor` | Number | The load-scaled open ledger transaction cost the server is currently enforcing, as a multiplier on the base transaction cost. For example, at `1000` load factor and a reference transaction cost of 10 drops of XRP, the load-scaled transaction cost is 10,000 drops (0.01 XRP). The load factor is determined by the highest of the [individual server's load factor](../../../../concepts/transactions/transaction-cost.md#local-load-cost), the cluster's load factor, the [open ledger cost](../../../../concepts/transactions/transaction-cost.md#open-ledger-cost) and the overall network's load factor. |
| `clio_version` | String | The version number of the running Clio server. |
| `libxrpl_version` | String | The version number of the `libxrpl` library this Clio server was built against. [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE") |
| `libxrpl_version` | String | The version number of the `libxrpl` library this Clio server was built against. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %} |
| `validation_quorum` | Number | _(May be omitted)_ Minimum number of trusted validations required to validate a ledger version. Some circumstances may cause the server to require more validations. This value is obtained from `rippled`. This field may be omitted from the response if the Clio server is unable to connect to `rippled` for some reason. |
| `rippled_version` | String | _(May be omitted)_ The version number of the running `rippled` server that the Clio server is connected to. This field may be omitted from the response if the Clio server is unable to connect to `rippled` for some reason. |
| `network_id` | String | _(May be omitted)_ The network ID of the network that the `rippled` this Clio server is connected to is operating on. This field may be omitted from the response if the Clio server is unable to connect to `rippled` for some reason. [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE") |
| `network_id` | String | _(May be omitted)_ The network ID of the network that the `rippled` this Clio server is connected to is operating on. This field may be omitted from the response if the Clio server is unable to connect to `rippled` for some reason. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %} |
| `validated_ledger` | Object | _(May be omitted)_ Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes `closed_ledger` instead. |
| `validated_ledger.age` | Number | The time since the ledger was closed, in seconds. |
| `validated_ledger.base_fee_xrp` | Number | Base fee, in XRP. This may be represented in scientific notation such as `1e-05` for 0.00001. |
@@ -623,8 +623,4 @@ The `info` object may have some arrangement of the following fields:
* Any of the [universal error types][].
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/clio-server/index.md
View File

@@ -1,8 +1,12 @@
---
html: clio-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Clio Server
Use these methods to retrieve information using Clio server APIs.
Use these methods to retrieve information using Clio server APIs.
{% child-pages /%}

110
content/references/http-websocket-apis/public-api-methods/index.md
View File

@@ -9,107 +9,107 @@ labels:
---
# Public API Methods
Communicate directly with an [XRP Ledger server](xrpl-servers.html) using the public API methods. Public methods are not necessarily meant for the general public, but they are used by any client attached to the server. Think of public methods as being for members or customers of the organization running the server.
Communicate directly with an [XRP Ledger server](../../../concepts/networks-and-servers/index.md) using the public API methods. Public methods are not necessarily meant for the general public, but they are used by any client attached to the server. Think of public methods as being for members or customers of the organization running the server.
## [Account Methods](account-methods.html)
## [Account Methods](account-methods/index.md)
An account in the XRP Ledger represents a holder of XRP and a sender of transactions. Use these methods to work with account info.
* **[`account_channels`](account_channels.html)** - Get a list of payment channels where the account is the source of the channel.
* **[`account_currencies`](account_currencies.html)** - Get a list of currencies an account can send or receive.
* **[`account_info`](account_info.html)** - Get basic data about an account.
* **[`account_lines`](account_lines.html)** - Get info about an account's trust lines.
* **[`account_nfts`](account_nfts.html)** - Get a list of non-fungible tokens owned by an account.
* **[`account_objects`](account_objects.html)** - Get all ledger objects owned by an account.
* **[`account_offers`](account_offers.html)** - Get info about an account's currency exchange offers.
* **[`account_tx`](account_tx.html)** - Get info about an account's transactions.
* **[`gateway_balances`](gateway_balances.html)** - Calculate total amounts issued by an account.
* **[`noripple_check`](noripple_check.html)** - Get recommended changes to an account's Default Ripple and No Ripple settings.
* **[`account_channels`](account-methods/account_channels.md)** - Get a list of payment channels where the account is the source of the channel.
* **[`account_currencies`](account-methods/account_currencies.md)** - Get a list of currencies an account can send or receive.
* **[`account_info`](account-methods/account_info.md)** - Get basic data about an account.
* **[`account_lines`](account-methods/account_lines.md)** - Get info about an account's trust lines.
* **[`account_nfts`](account-methods/account_nfts.md)** - Get a list of non-fungible tokens owned by an account.
* **[`account_objects`](account-methods/account_objects.md)** - Get all ledger objects owned by an account.
* **[`account_offers`](account-methods/account_offers.md)** - Get info about an account's currency exchange offers.
* **[`account_tx`](account-methods/account_tx.md)** - Get info about an account's transactions.
* **[`gateway_balances`](account-methods/gateway_balances.md)** - Calculate total amounts issued by an account.
* **[`noripple_check`](account-methods/noripple_check.md)** - Get recommended changes to an account's Default Ripple and No Ripple settings.
## [Ledger Methods](ledger-methods.html)
## [Ledger Methods](ledger-methods/index.md)
A ledger version contains a header, a transaction tree, and a state tree, which contain account settings, trust lines, balances, transactions, and other data. Use these methods to retrieve ledger info.
* **[`ledger`](ledger.html)** - Get info about a ledger version.
* **[`ledger_closed`](ledger_closed.html)** - Get the latest closed ledger version.
* **[`ledger_current`](ledger_current.html)** - Get the current working ledger version.
* **[`ledger_data`](ledger_data.html)** - Get the raw contents of a ledger version.
* **[`ledger_entry`](ledger_entry.html)** - Get one element from a ledger version.
* **[`ledger`](ledger-methods/ledger.md)** - Get info about a ledger version.
* **[`ledger_closed`](ledger-methods/ledger_closed.md)** - Get the latest closed ledger version.
* **[`ledger_current`](ledger-methods/ledger_current.md)** - Get the current working ledger version.
* **[`ledger_data`](ledger-methods/ledger_data.md)** - Get the raw contents of a ledger version.
* **[`ledger_entry`](ledger-methods/ledger_entry.md)** - Get one element from a ledger version.
## [Transaction Methods](transaction-methods.html)
## [Transaction Methods](transaction-methods/index.md)
Transactions are the only thing that can modify the shared state of the XRP Ledger. All business on the XRP Ledger takes the form of transactions. Use these methods to work with transactions.
* **[`submit`](submit.html)** - Send a transaction to the network.
* **[`submit_multisigned`](submit_multisigned.html)** - Send a multi-signed transaction to the network.
* **[`transaction_entry`](transaction_entry.html)** - Retrieve info about a transaction from a particular ledger version.
* **[`tx`](tx.html)** - Retrieve info about a transaction from all the ledgers on hand.
* **[`tx_history`](tx_history.html)** - Retrieve info about all recent transactions.
* **[`submit`](transaction-methods/submit.md)** - Send a transaction to the network.
* **[`submit_multisigned`](transaction-methods/submit_multisigned.md)** - Send a multi-signed transaction to the network.
* **[`transaction_entry`](transaction-methods/transaction_entry.md)** - Retrieve info about a transaction from a particular ledger version.
* **[`tx`](transaction-methods/tx.md)** - Retrieve info about a transaction from all the ledgers on hand.
* **[`tx_history`](transaction-methods/tx_history.md)** - Retrieve info about all recent transactions.
By default, the following methods are [admin-only](admin-api-methods.html). They can be used as public methods if the server admin has [enabled public signing](enable-public-signing.html).
By default, the following methods are [admin-only](../admin-api-methods/index.md). They can be used as public methods if the server admin has [enabled public signing](../../../infrastructure/configuration/enable-public-signing.md).
* **[`sign`](sign.html)** - Cryptographically sign a transaction.
* **[`sign_for`](sign_for.html)** - Contribute to a multi-signature.
* **[`sign`](../admin-api-methods/signing-methods/sign.md)** - Cryptographically sign a transaction.
* **[`sign_for`](../admin-api-methods/signing-methods/sign_for.md)** - Contribute to a multi-signature.
## [Path and Order Book Methods](path-and-order-book-methods.html)
## [Path and Order Book Methods](path-and-order-book-methods/index.md)
Paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Use these methods to work with paths and other books.
* **[`amm_info`](amm_info.html)** :not_enabled: - Get info about an Automated Market Maker (AMM).
* **[`book_offers`](book_offers.html)** - Get info about offers to exchange two currencies.
* **[`deposit_authorized`](deposit_authorized.html)** - Look up whether one account is authorized to send payments directly to another. <!-- STYLE_OVERRIDE: is authorized to -->
* **[`nft_buy_offers`](nft_buy_offers.html)** - Retrieve a list of buy offers for a specified NFToken object.
* **[`nft_sell_offers`](nft_sell_offers.html)** - Retrieve a list of sell offers for a specified NFToken object.
* **[`path_find`](path_find.html)** - Find a path for a payment between two accounts and receive updates.
* **[`ripple_path_find`](ripple_path_find.html)** - Find a path for payment between two accounts, once.
* **[`amm_info`](path-and-order-book-methods/amm_info.md)** {% not-enabled /%} - Get info about an Automated Market Maker (AMM).
* **[`book_offers`](path-and-order-book-methods/book_offers.md)** - Get info about offers to exchange two currencies.
* **[`deposit_authorized`](path-and-order-book-methods/deposit_authorized.md)** - Look up whether one account is authorized to send payments directly to another. <!-- STYLE_OVERRIDE: is authorized to -->
* **[`nft_buy_offers`](path-and-order-book-methods/nft_buy_offers.md)** - Retrieve a list of buy offers for a specified NFToken object.
* **[`nft_sell_offers`](path-and-order-book-methods/nft_sell_offers.md)** - Retrieve a list of sell offers for a specified NFToken object.
* **[`path_find`](path-and-order-book-methods/path_find.md)** - Find a path for a payment between two accounts and receive updates.
* **[`ripple_path_find`](path-and-order-book-methods/ripple_path_find.md)** - Find a path for payment between two accounts, once.
## [Payment Channel Methods](payment-channel-methods.html)
## [Payment Channel Methods](payment-channel-methods/index.md)
Payment channels are a tool for facilitating repeated, unidirectional payments, or temporary credit between two parties. Use these methods to work with payment channels.
* **[`channel_authorize`](channel_authorize.html)** - Sign a claim for money from a payment channel.
* **[`channel_verify`](channel_verify.html)** - Check a payment channel claim's signature.
* **[`channel_authorize`](payment-channel-methods/channel_authorize.md)** - Sign a claim for money from a payment channel.
* **[`channel_verify`](payment-channel-methods/channel_verify.md)** - Check a payment channel claim's signature.
## [Subscription Methods](subscription-methods.html)
## [Subscription Methods](subscription-methods/index.md)
Use these methods to enable the server to push updates to your client when various events happen, so that you can know and react right away. _WebSocket API only._
* **[`subscribe`](subscribe.html)** - Listen for updates about a particular subject.
* **[`unsubscribe`](unsubscribe.html)** - Stop listening for updates about a particular subject.
* **[`subscribe`](subscription-methods/subscribe.md)** - Listen for updates about a particular subject.
* **[`unsubscribe`](subscription-methods/unsubscribe.md)** - Stop listening for updates about a particular subject.
## [Server Info Methods](server-info-methods.html)
## [Server Info Methods](server-info-methods/index.md)
Use these methods to retrieve information about the current state of the `rippled` server.
* **[`fee`](fee.html)** - Get information about transaction cost.
* **[`server_info`](server_info.html)** - Retrieve status of the server in human-readable format.
* **[`server_state`](server_state.html)** - Retrieve status of the server in machine-readable format.
- **[`manifest`](manifest.html)** - Retrieve the latest ephemeral public key information about a known validator.
* **[`fee`](server-info-methods/fee.md)** - Get information about transaction cost.
* **[`server_info`](server-info-methods/server_info.md)** - Retrieve status of the server in human-readable format.
* **[`server_state`](server-info-methods/server_state.md)** - Retrieve status of the server in machine-readable format.
- **[`manifest`](server-info-methods/manifest.md)** - Retrieve the latest ephemeral public key information about a known validator.
## [Clio Methods](clio-methods.html)
## [Clio Methods](clio-server/index.md)
Use these methods to retrieve information using Clio server APIs.
* **[`server_info`](server_info-clio.html)** - Retrieve status of the Clio server.
* **[`ledger`](ledger-clio.html)** - Get info about a ledger version using Clio server's `ledger` API.
* **[`nft_info`](nft_info.html)** - Retrieve information about the specified NFT using Clio server's `nft_info` API.
* **[`server_info`](clio-methods/server_info-clio.md)** - Retrieve status of the Clio server.
* **[`ledger`](clio-methods/ledger-clio.md)** - Get info about a ledger version using Clio server's `ledger` API.
* **[`nft_info`](clio-methods/nft_info.md)** - Retrieve information about the specified NFT using Clio server's `nft_info` API.
## [Utility Methods](utility-methods.html)
## [Utility Methods](utility-methods/index.md)
Use these methods to perform convenient tasks, such as ping and random number generation.
* **[`json`](json.html)** - Use as a proxy to running other commands. Accepts the parameters for the command as a JSON value. _Commandline only._
* **[`ping`](ping.html)** - Confirm connectivity with the server.
* **[`random`](random.html)** - Generate a random number.
* **[`json`](utility-methods/json.md)** - Use as a proxy to running other commands. Accepts the parameters for the command as a JSON value. _Commandline only._
* **[`ping`](utility-methods/ping.md)** - Confirm connectivity with the server.
* **[`random`](utility-methods/random.md)** - Generate a random number.
## Deprecated Methods
The `owner_info` command is deprecated. Use [`account_objects`](account_objects.html) instead.
The `owner_info` command is deprecated. Use [`account_objects`](account-methods/account_objects.md) instead.

8
content/references/http-websocket-apis/public-api-methods/ledger-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: ledger-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Ledger Methods
A ledger version contains a header, a transaction tree, and a state tree, which contain account settings, trustlines, balances, transactions, and other data. Use these methods to retrieve ledger info.
A ledger version contains a header, a transaction tree, and a state tree, which contain account settings, trustlines, balances, transactions, and other data. Use these methods to retrieve ledger info.
{% child-pages /%}

83
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger.md
View File

@@ -8,15 +8,14 @@ labels:
# ledger
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/LedgerHandler.cpp "Source")
Retrieve information about the public [ledger](ledgers.html).
Retrieve information about the public [ledger](../../../../concepts/ledgers/index.md).
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_ledger_req",
@@ -27,9 +26,9 @@ An example of the request format:
"owner_funds": false
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger",
@@ -43,19 +42,20 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: ledger ledger_index|ledger_hash [full|tx]
# "full" is equivalent to "full": true
# "tx" is equivalent to "transactions": true
rippled ledger validated
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger)
The request can contain the following parameters:
@@ -67,7 +67,7 @@ The request can contain the following parameters:
| `expand` | Boolean | No | Provide full JSON-formatted information for transaction/account information instead of only hashes. The default is `false`. Ignored unless you request transactions, accounts, or both. |
| `owner_funds` | Boolean | No | If `true`, include `owner_funds` field in the metadata of OfferCreate transactions in the response. The default is `false`. Ignored unless transactions are included and `expand` is true. |
| `binary` | Boolean | No | If `true`, and `transactions` and `expand` are both also `true`, return transaction information in binary format (hexadecimal string) instead of JSON format. |
| `queue` | Boolean | No | If `true`, and the command is requesting the `current` ledger, includes an array of [queued transactions](transaction-cost.html#queued-transactions) in the results. |
| `queue` | Boolean | No | If `true`, and the command is requesting the `current` ledger, includes an array of [queued transactions](../../../../concepts/transactions/transaction-cost.md#queued-transactions) in the results. |
The `ledger` field is deprecated and may be removed without further notice. The `full`, `accounts`, and `type` fields (admin-only) are also deprecated; the Clio server does not implement these parameters.
@@ -76,40 +76,29 @@ The `ledger` field is deprecated and may be removed without further notice. The
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
{% tabs %}
*WebSocket*
{% tab label="WebSocket" %}
{% code-snippet file="/_api-examples/ledger/ws-response.json" language="json" /%}
{% /tab %}
```json
{% include '_api-examples/ledger/ws-response.json' %}
```
{% tab label="JSON-RPC" %}
{% code-snippet file="/_api-examples/ledger/jsonrpc-response.json" language="json" prefix="200 OK\n\n" /%}
{% /tab %}
*JSON-RPC*
{% tab label="Commandline" %}
{% code-snippet file="/_api-examples/ledger/jsonrpc-response.json" language="json" prefix="Loading: \"/etc/opt/ripple/rippled.cfg\"\n2023-Nov-01 21:38:14.638871262 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005\n\n" /%}
{% /tab %}
```json
200 OK
{% include '_api-examples/ledger/jsonrpc-response.json' %}
```
*Commandline*
```json
Loading: "/etc/opt/ripple/rippled.cfg"
2023-Nov-01 21:38:14.638871262 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005
{% include '_api-examples/ledger/jsonrpc-response.json' %}
```
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing information about the ledger, including the following fields:
| `Field` | Type | Description |
|:-------------------------------|:--------|:----------------------------------|
| `ledger` | Object | The complete [ledger header data](ledger-header.html) of this ledger, with some additional fields added for convenience. |
| `ledger.account_hash` | String | [Hash](basic-data-types.html#hashes) of all account state information in this ledger, as hexadecimal. |
| `ledger.close_flags` | Number | A bit-map of [flags relating to the closing of this ledger](ledger-header.html#close-flags). |
| `ledger` | Object | The complete [ledger header data](../../../protocol/ledger-data/ledger-header.md) of this ledger, with some additional fields added for convenience. |
| `ledger.account_hash` | String | [Hash](../../../protocol/data-types/basic-data-types.md#hashes) of all account state information in this ledger, as hexadecimal. |
| `ledger.close_flags` | Number | A bit-map of [flags relating to the closing of this ledger](../../../protocol/ledger-data/ledger-header.md#close-flags). |
| `ledger.close_time` | Number | The time this ledger was closed, in [seconds since the Ripple Epoch][]. |
| `ledger.close_time_human` | String | The time this ledger was closed, in human-readable format. Always uses the UTC time zone. |
| `ledger.close_time_resolution` | Number | Ledger close times are rounded to within this many seconds. |
@@ -119,7 +108,7 @@ The response follows the [standard format][], with a successful result containin
| `ledger.parent_close_time` | Number | The time at which the previous ledger was closed. |
| `ledger.parent_hash` | String | The unique identifying hash of the ledger that came immediately before this one, as hexadecimal. |
| `ledger.total_coins` | String | Total number of XRP drops in the network, as a quoted integer. (This decreases as transaction costs destroy XRP.) |
| `ledger.transaction_hash` | String | [Hash](basic-data-types.html#hashes) of the transaction information included in this ledger. |
| `ledger.transaction_hash` | String | [Hash](../../../protocol/data-types/basic-data-types.md#hashes) of the transaction information included in this ledger. |
| `ledger.transactions` | Array | _(Omitted unless requested)_ Transactions applied in this ledger version. By default, members are the transactions' identifying [Hash][] strings. If the request specified `expand` as true, members are full representations of the transactions instead, in either JSON or binary depending on whether the request specified `binary` as true. |
| `ledger_hash` | String | The unique identifying hash of the entire ledger, as hexadecimal. |
| `ledger_index` | Number | The [Ledger Index][] of this ledger. |
@@ -128,27 +117,27 @@ The response follows the [standard format][], with a successful result containin
The `ledger.accountState` field (omitted unless requested with `"full": true` or `"accounts": true`) is deprecated.
The following deprecated fields have been removed: `accepted`, `hash` (use `ledger_hash` instead), `seqNum` (use `ledger_index` instead), `totalCoins` (use `total_coins` instead). [Updated in: rippled 1.12.0][]
The following deprecated fields have been removed: `accepted`, `hash` (use `ledger_hash` instead), `seqNum` (use `ledger_index` instead), `totalCoins` (use `total_coins` instead). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.12.0" %}Updated in: rippled 1.12.0{% /badge %}
Each member of the `queue_data` array represents one transaction in the queue. Some fields of this object may be omitted because they have not yet been calculated. The fields of this object are as follows:
| Field | Value | Description |
|:--------------------|:-----------------|:------------------------------------|
| `account` | String | The [Address][] of the sender for this queued transaction. |
| `tx` | String or Object | By default, this is a String containing the [identifying hash](basic-data-types.html#hashes) of the transaction. If transactions are expanded in binary format, this is an object whose only field is `tx_blob`, containing the binary form of the transaction as a decimal string. If transactions are expanded in JSON format, this is an object containing the [transaction object](transaction-formats.html) including the transaction's identifying hash in the `hash` field. |
| `tx` | String or Object | By default, this is a String containing the [identifying hash](../../../protocol/data-types/basic-data-types.md#hashes) of the transaction. If transactions are expanded in binary format, this is an object whose only field is `tx_blob`, containing the binary form of the transaction as a decimal string. If transactions are expanded in JSON format, this is an object containing the [transaction object](../../../protocol/transactions/index.md) including the transaction's identifying hash in the `hash` field. |
| `retries_remaining` | Number | How many times this transaction can be retried before being dropped. |
| `preflight_result` | String | The tentative result from preliminary transaction checking. This is always `tesSUCCESS`. |
| `last_result` | String | _(May be omitted)_ If this transaction was left in the queue after getting a [retriable (`ter`) result](ter-codes.html), this is the exact `ter` result code it got. |
| `auth_change` | Boolean | _(May be omitted)_ Whether this transaction changes this address's [ways of authorizing transactions](transactions.html#authorizing-transactions). |
| `fee` | String | _(May be omitted)_ The [Transaction Cost](transaction-cost.html) of this transaction, in [drops of XRP][]. |
| `last_result` | String | _(May be omitted)_ If this transaction was left in the queue after getting a [retriable (`ter`) result](../../../protocol/transactions/transaction-results/ter-codes.md), this is the exact `ter` result code it got. |
| `auth_change` | Boolean | _(May be omitted)_ Whether this transaction changes this address's [ways of authorizing transactions](../../../../concepts/transactions/index.md#authorizing-transactions). |
| `fee` | String | _(May be omitted)_ The [Transaction Cost](../../../../concepts/transactions/transaction-cost.md) of this transaction, in [drops of XRP][]. |
| `fee_level` | String | _(May be omitted)_ The transaction cost of this transaction, relative to the minimum cost for this type of transaction, in [fee levels][]. |
| `max_spend_drops` | String | _(May be omitted)_ The maximum amount of [XRP, in drops][], this transaction could potentially send or destroy. |
If the request specified `"owner_funds": true` and expanded transactions, the response has a field `owner_funds` in the `metaData` object of each [OfferCreate transaction][]. The purpose of this field is to make it easier to track the [funding status of offers](offers.html#lifecycle-of-an-offer) with each new validated ledger. This field is defined slightly differently than the version of this field in [Order Book subscription streams](subscribe.html#order-book-streams):
If the request specified `"owner_funds": true` and expanded transactions, the response has a field `owner_funds` in the `metaData` object of each [OfferCreate transaction][]. The purpose of this field is to make it easier to track the [funding status of offers](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer) with each new validated ledger. This field is defined slightly differently than the version of this field in [Order Book subscription streams](../subscription-methods/subscribe.md#order-book-streams):
| `Field` | Value | Description |
|:--------------|:-------|:----------------------------------------------------|
| `owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is [frozen](freezes.html). |
| `owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after the execution of all transactions in this ledger. This does not check whether the currency amount is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
## Possible Errors
@@ -157,8 +146,4 @@ If the request specified `"owner_funds": true` and expanded transactions, the re
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `noPermission` - If you specified `full` or `accounts` as true, but are not connected to the server as an admin (usually, admin requires connecting on localhost).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

38
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_closed.md
View File

@@ -13,19 +13,18 @@ The `ledger_closed` method returns the unique identifiers of the most recently c
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
"command": "ledger_closed"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_closed",
@@ -34,27 +33,27 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: ledger_closed
rippled ledger_closed
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_closed)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_closed)
This method accepts no parameters.
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -66,9 +65,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -80,9 +79,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -92,8 +91,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -106,6 +106,4 @@ The response follows the [standard format][], with a successful result containin
* Any of the [universal error types][].
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

40
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_current.md
View File

@@ -8,25 +8,24 @@ labels:
# ledger_current
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/LedgerCurrent.cpp "Source")
The `ledger_current` method returns the unique identifiers of the current in-progress [ledger](ledgers.html). This command is mostly useful for testing, because the ledger returned is still in flux.
The `ledger_current` method returns the unique identifiers of the current in-progress [ledger](../../../../concepts/ledgers/index.md). This command is mostly useful for testing, because the ledger returned is still in flux.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
"command": "ledger_current"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_current",
@@ -35,17 +34,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: ledger_current
rippled ledger_current
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_current)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_current)
The request contains no parameters.
@@ -53,10 +53,9 @@ The request contains no parameters.
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -67,9 +66,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -80,9 +79,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -91,8 +90,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following field:
@@ -106,6 +106,4 @@ A `ledger_hash` field is not provided, because the hash of the current ledger is
* Any of the [universal error types][].
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

40
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_data.md
View File

@@ -14,12 +14,11 @@ The `ledger_data` method retrieves contents of the specified ledger. You can ite
## Request Format
An example of the request format:
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -29,9 +28,9 @@ An example of the request format:
"binary": true
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_data",
@@ -44,8 +43,9 @@ An example of the request format:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
A request can include the following fields:
@@ -57,7 +57,7 @@ A request can include the following fields:
| `binary` | Boolean | No | If `true`, return ledger entries as hexadecimal strings instead of JSON. The default is `false`. |
| `limit` | Number | No | Limit the number of ledger entries to retrieve. The server may return fewer than this number of entries. Cannot be more than 2048 (when requesting binary) or 256 (when requesting JSON). Positive values outside this range are replaced with the closest valid option. The default is the maximum. |
| `marker` | [Marker][] | No | Value from a previous paginated response. Resume retrieving data where that response left off. |
| `type` | String | No | Filter results to a specific type of ledger entry. {% include '_snippets/lowercase-types.md' %} |
| `type` | String | No | Filter results to a specific type of ledger entry. {% partial file="/_snippets/lowercase-types.md" /%} |
The `ledger` field is deprecated and may be removed without further notice.
@@ -65,10 +65,9 @@ The `ledger` field is deprecated and may be removed without further notice.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket (binary:true)*
{% tabs %}
{% tab label="WebSocket (binary:true)" %}
```json
{
"id": 2,
@@ -103,9 +102,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*WebSocket (binary:false)*
{% tab label="WebSocket (binary:false)" %}
```json
{
"id": 2,
@@ -202,9 +201,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC (binary:true)*
{% tab label="JSON-RPC (binary:true)" %}
```json
200 OK
@@ -239,8 +238,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -258,8 +258,8 @@ The format of each object in the `state` array depends on whether `binary` was s
| `Field` | Type | Description |
|:--------------------|:----------|:-------------------------------------------|
| `data` | String | _(Only included if `"binary":true`)_ Hex representation of the requested data |
| `LedgerEntryType` | String | _(Only included if `"binary":false`)_ String indicating what type of ledger object this object represents. See [ledger object types](ledger-object-types.html) for the full list. |
| (Additional fields) | (Various) | _(Only included if `"binary":false`)_ Additional fields describing this object, depending on which [ledger object type](ledger-object-types.html) it is. |
| `LedgerEntryType` | String | _(Only included if `"binary":false`)_ String indicating what type of ledger object this object represents. See [ledger object types](../../../protocol/ledger-data/ledger-entry-types/index.md) for the full list. |
| (Additional fields) | (Various) | _(Only included if `"binary":false`)_ Additional fields describing this object, depending on which [ledger object type](../../../protocol/ledger-data/ledger-entry-types/index.md) it is. |
| `index` | String | Unique identifier for this ledger entry, as hex. |
## Possible Errors
@@ -268,6 +268,4 @@ The format of each object in the `state` array depends on whether `binary` was s
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

311
content/references/http-websocket-apis/public-api-methods/ledger-methods/ledger_entry.md
View File

@@ -13,15 +13,15 @@ The `ledger_entry` method returns a single ledger entry from the XRP Ledger in i
## Request Format
This method can retrieve several different types of data. You can select which type of item to retrieve by passing the appropriate parameters, comprised of the general and type-specific fields listed below, and following the standard [request formatting](request-formatting.html). (For example, a WebSocket request always has the `command` field and optionally an `id` field, and a JSON-RPC request uses the `method` and `params` fields.)
This method can retrieve several different types of data. You can select which type of item to retrieve by passing the appropriate parameters, comprised of the general and type-specific fields listed below, and following the standard [request formatting](../../api-conventions/request-formatting.md). (For example, a WebSocket request always has the `command` field and optionally an `id` field, and a JSON-RPC request uses the `method` and `params` fields.)
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
### General Fields
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `binary` | Boolean | _(Optional)_ If `true`, return the requested ledger entry's contents as a hex string in the XRP Ledger's [binary format](serialization.html). Otherwise, return data in JSON format. The default is `false`. [Updated in: rippled 1.2.0][] |
| `binary` | Boolean | _(Optional)_ If `true`, return the requested ledger entry's contents as a hex string in the XRP Ledger's [binary format](../../../protocol/binary-format.md). Otherwise, return data in JSON format. The default is `false`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.2.0" %}Updated in: rippled 1.2.0{% /badge %} |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string (e.g. "validated" or "closed" or "current") to choose a ledger automatically. (See [Specifying Ledgers][]) |
@@ -31,7 +31,7 @@ In addition to the general fields above, you must specify *exactly 1* of the fol
- [`index`](#get-ledger-object-by-id)
- [`account_root`](#get-accountroot-object)
- [`amm`](#get-amm-object) :not_enabled:
- [`amm`](#get-amm-object) {% not-enabled /%}
- [`directory`](#get-directorynode-object)
- [`offer`](#get-offer-object)
- [`ripple_state`](#get-ripplestate-object)
@@ -51,12 +51,11 @@ Retrieve any type of ledger object by its unique ID.
| Field | Type | Description |
|:--------|:-------|:----------------------------------------------------------|
| `index` | String | The [ledger entry ID](ledger-object-ids.html) of a single entry to retrieve from the ledger, as a 64-character (256-bit) hexadecimal string. |
| `index` | String | The [ledger entry ID](../../../protocol/ledger-data/common-fields.md) of a single entry to retrieve from the ledger, as a 64-character (256-bit) hexadecimal string. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"command": "ledger_entry",
@@ -64,9 +63,9 @@ Retrieve any type of ledger object by its unique ID.
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -78,38 +77,40 @@ Retrieve any type of ledger object by its unique ID.
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "index": "7DB0788C020F02780A673DC74757F23823FA3014C1866E72CC4CD8B226CD6EF4", "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-by-object-id)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-by-object-id)
> **Tip:** You can use this type of request to get any singleton ledger entry, if it exists in the ledger data, because its ID is always the same. For example:
>
> - [`Amendments`](amendments-object.html) - `7DB0788C020F02780A673DC74757F23823FA3014C1866E72CC4CD8B226CD6EF4`
> - [`FeeSettings`](feesettings.html) - `4BC50C9B0D8515D3EAAE1E74B29A95804346C491EE1A95BF25E4AAB854A6A651`
> - [Recent History `LedgerHashes`](ledgerhashes.html) - `B4979A36CDC7F3D3D5C31A4EAE2AC7D7209DDA877588B9AFC66799692AB0D66B`
> - [`NegativeUNL`](negativeunl.html) - `2E8A59AA9D3B5B186B0B9E0F62E6C02587CA74A4D778938E957B6357D364B244`
{% admonition type="success" name="Tip" %}
You can use this type of request to get any singleton ledger entry, if it exists in the ledger data, because its ID is always the same. For example:
- [`Amendments`](../../../protocol/ledger-data/ledger-entry-types/amendments.md) - `7DB0788C020F02780A673DC74757F23823FA3014C1866E72CC4CD8B226CD6EF4`
- [`FeeSettings`](../../../protocol/ledger-data/ledger-entry-types/feesettings.md) - `4BC50C9B0D8515D3EAAE1E74B29A95804346C491EE1A95BF25E4AAB854A6A651`
- [Recent History `LedgerHashes`](../../../protocol/ledger-data/ledger-entry-types/ledgerhashes.md) - `B4979A36CDC7F3D3D5C31A4EAE2AC7D7209DDA877588B9AFC66799692AB0D66B`
- [`NegativeUNL`](../../../protocol/ledger-data/ledger-entry-types/negativeunl.md) - `2E8A59AA9D3B5B186B0B9E0F62E6C02587CA74A4D778938E957B6357D364B244`
{% /admonition %}
### Get AccountRoot Object
Retrieve an [AccountRoot entry](accountroot.html) by its address. This is roughly equivalent to the [account_info method][].
Retrieve an [AccountRoot entry](../../../protocol/ledger-data/ledger-entry-types/accountroot.md) by its address. This is roughly equivalent to the [account_info method][].
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `account_root` | String - [Address][] | The classic address of the [AccountRoot entry](accountroot.html) to retrieve. |
| `account_root` | String - [Address][] | The classic address of the [AccountRoot entry](../../../protocol/ledger-data/ledger-entry-types/accountroot.md) to retrieve. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_accountroot",
@@ -118,9 +119,9 @@ Retrieve an [AccountRoot entry](accountroot.html) by its address. This is roughl
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -132,35 +133,35 @@ Retrieve an [AccountRoot entry](accountroot.html) by its address. This is roughl
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "account_root": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-accountroot)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-accountroot)
### Get AMM Object
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
Retrieve an Automated Market-Maker (AMM) object from the ledger. This is similar to [amm_info method][], but the `ledger_entry` version returns only the ledger entry as stored.
| Field | Type | Description |
|:-------------|:-----------------|:----------------------|
| `amm` | Object or String | The [AMM](amm.html) to retrieve. If you specify a string, it must be the [object ID](ledger-object-ids.html) of the AMM, as hexadecimal. If you specify an object, it must contain `asset` and `asset2` sub-fields. |
| `amm.asset` | Object | One of the two assets in this AMM's pool, as a [currency object without an amount](currency-formats.html#specifying-without-amounts). |
| `amm.asset2` | Object | The other of the two assets in this AMM's pool, as a [currency object without an amount](currency-formats.html#specifying-without-amounts). |
| `amm` | Object or String | The [AMM](../../../protocol/ledger-data/ledger-entry-types/amm.md) to retrieve. If you specify a string, it must be the [object ID](../../../protocol/ledger-data/common-fields.md) of the AMM, as hexadecimal. If you specify an object, it must contain `asset` and `asset2` sub-fields. |
| `amm.asset` | Object | One of the two assets in this AMM's pool, as a [currency object without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). |
| `amm.asset2` | Object | The other of the two assets in this AMM's pool, as a [currency object without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 3,
@@ -177,9 +178,9 @@ Retrieve an Automated Market-Maker (AMM) object from the ledger. This is similar
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -199,34 +200,34 @@ Retrieve an Automated Market-Maker (AMM) object from the ledger. This is similar
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "amm": { "asset": { "currency": "XRP" }, "asset2": { "currency" : "TST", "issuer" : "rP9jPyP5kyvFRb6ZiRghAGw5u8SGAmU4bd" } }, "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html?server=wss%3A%2F%2Famm.devnet.rippletest.net%3A51233%2F#ledger_entry-amm)
[Try it! >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Famm.devnet.rippletest.net%3A51233%2F#ledger_entry-amm)
### Get DirectoryNode Object
Retrieve a [DirectoryNode](directorynode.html), which contains a list of other ledger objects. Can be provided as string (object ID of the Directory) or as an object.
Retrieve a [DirectoryNode](../../../protocol/ledger-data/ledger-entry-types/directorynode.md), which contains a list of other ledger objects. Can be provided as string (object ID of the Directory) or as an object.
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `directory` | Object or String | The [DirectoryNode](directorynode.html) to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the directory, as hexadecimal. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
| `directory.sub_index` | Unsigned Integer | _(Optional)_ If provided, jumps to a later "page" of the [DirectoryNode](directorynode.html). |
| `directory` | Object or String | The [DirectoryNode](../../../protocol/ledger-data/ledger-entry-types/directorynode.md) to retrieve. If a string, must be the [object ID](../../../protocol/ledger-data/common-fields.md) of the directory, as hexadecimal. If an object, requires either `dir_root` or `owner` as a sub-field, plus optionally a `sub_index` sub-field. |
| `directory.sub_index` | Unsigned Integer | _(Optional)_ If provided, jumps to a later "page" of the [DirectoryNode](../../../protocol/ledger-data/ledger-entry-types/directorynode.md). |
| `directory.dir_root` | String | _(Optional)_ Unique index identifying the directory to retrieve, as a hex string. |
| `directory.owner` | String | _(Optional)_ Unique address of the account associated with this directory. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 3,
@@ -238,9 +239,9 @@ Retrieve a [DirectoryNode](directorynode.html), which contains a list of other l
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -255,33 +256,33 @@ Retrieve a [DirectoryNode](directorynode.html), which contains a list of other l
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "directory": { "owner": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "sub_index": 0 }, "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-directorynode)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-directorynode)
### Get Offer Object
Retrieve an [Offer entry](offer.html), which defines an offer to exchange currency. Can be provided as string (unique index of the Offer) or as an object.
Retrieve an [Offer entry](../../../protocol/ledger-data/ledger-entry-types/offer.md), which defines an offer to exchange currency. Can be provided as string (unique index of the Offer) or as an object.
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `offer` | Object or String | If a string, interpret as [ledger entry ID](ledger-object-ids.html) of the Offer to retrieve. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
| `offer` | Object or String | If a string, interpret as [ledger entry ID](../../../protocol/ledger-data/common-fields.md) of the Offer to retrieve. If an object, requires the sub-fields `account` and `seq` to uniquely identify the offer. |
| `offer.account` | String - [Address][] | _(Required if `offer` is specified as an object)_ The account that placed the offer. |
| `offer.seq` | Unsigned Integer | _(Required if `offer` is specified as an object)_ The [Sequence Number][] of the transaction that created the Offer entry. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_offer",
@@ -293,9 +294,9 @@ Retrieve an [Offer entry](offer.html), which defines an offer to exchange curren
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -310,16 +311,17 @@ Retrieve an [Offer entry](offer.html), which defines an offer to exchange curren
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "offer": { "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "seq": 359}, "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-offer)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-offer)
@@ -333,10 +335,9 @@ Retrieve a [RippleState entry][], which tracks a (non-XRP) currency balance betw
| `ripple_state.accounts` | Array | _(Required if `ripple_state` is specified)_ 2-length array of account [Address][]es, defining the two accounts linked by this RippleState entry. |
| `ripple_state.currency` | String | _(Required if `ripple_state` is specified)_ [Currency Code][] of the RippleState entry to retrieve. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_ripplestate",
@@ -351,9 +352,9 @@ Retrieve a [RippleState entry][], which tracks a (non-XRP) currency balance betw
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -369,31 +370,31 @@ Retrieve a [RippleState entry][], which tracks a (non-XRP) currency balance betw
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "ripple_state": { "accounts": ["rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "rsA2LpzuawewSBQXkiju3YQTMzW13pAAdW"], "currency": "USD"}, "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-ripplestate)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-ripplestate)
### Get Check Object
Retrieve a [Check entry](check.html), which is a potential payment that can be cashed by its recipient. [New in: rippled 1.0.0][]
Retrieve a [Check entry](../../../protocol/ledger-data/ledger-entry-types/check.md), which is a potential payment that can be cashed by its recipient. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.0.0" %}New in: rippled 1.0.0{% /badge %}
| Field | Type | Description |
|:--------|:-------|:----------------------------------------------------------|
| `check` | String | The [object ID](ledger-object-ids.html) of a [Check entry](check.html) to retrieve. |
| `check` | String | The [object ID](../../../protocol/ledger-data/common-fields.md) of a [Check entry](../../../protocol/ledger-data/ledger-entry-types/check.md) to retrieve. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_check",
@@ -402,9 +403,9 @@ Retrieve a [Check entry](check.html), which is a potential payment that can be c
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -414,33 +415,33 @@ Retrieve a [Check entry](check.html), which is a potential payment that can be c
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "check": "C4A46CCD8F096E994C4B0DEAB6CE98E722FC17D7944C28B95127C2659C47CBEB", "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-check)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-check)
### Get Escrow Object
Retrieve an [Escrow entry](escrow-object.html), which holds XRP until a specific time or condition is met. Can be provided as string (object ID of the Escrow) or as an object. [New in: rippled 1.0.0][]
Retrieve an [Escrow entry](../../../protocol/ledger-data/ledger-entry-types/escrow.md), which holds XRP until a specific time or condition is met. Can be provided as string (object ID of the Escrow) or as an object. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.0.0" %}New in: rippled 1.0.0{% /badge %}
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `escrow` | Object or String | The Escrow to retrieve. If a string, must be the [object ID](ledger-object-ids.html) of the Escrow, as hexadecimal. If an object, requires `owner` and `seq` sub-fields. |
| `escrow` | Object or String | The Escrow to retrieve. If a string, must be the [object ID](../../../protocol/ledger-data/common-fields.md) of the Escrow, as hexadecimal. If an object, requires `owner` and `seq` sub-fields. |
| `escrow.owner` | String - [Address][] | _(Required if `escrow` is specified as an object)_ The owner (sender) of the Escrow object. |
| `escrow.seq` | Unsigned Integer | _(Required if `escrow` is specified as an object)_ The [Sequence Number][] of the transaction that created the Escrow object. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_escrow",
@@ -452,9 +453,9 @@ Retrieve an [Escrow entry](escrow-object.html), which holds XRP until a specific
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -467,31 +468,31 @@ Retrieve an [Escrow entry](escrow-object.html), which holds XRP until a specific
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "escrow": { "owner": "rL4fPHi2FWGwRGRQSH7gBcxkuo2b9NTjKK", "seq": 126 }, "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-escrow)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-escrow)
### Get PayChannel Object
Retrieve a [PayChannel entry](paychannel.html), which holds XRP for asynchronous payments. [New in: rippled 1.0.0][]
Retrieve a [PayChannel entry](../../../protocol/ledger-data/ledger-entry-types/paychannel.md), which holds XRP for asynchronous payments. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.0.0" %}New in: rippled 1.0.0{% /badge %}
| Field | Type | Description |
|:------------------|:-------|:------------------------------------------------|
| `payment_channel` | String | The [object ID](ledger-object-ids.html) of the PayChannel to retrieve. |
| `payment_channel` | String | The [object ID](../../../protocol/ledger-data/common-fields.md) of the PayChannel to retrieve. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_paychannel",
@@ -500,9 +501,9 @@ Retrieve a [PayChannel entry](paychannel.html), which holds XRP for asynchronous
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -512,32 +513,32 @@ Retrieve a [PayChannel entry](paychannel.html), which holds XRP for asynchronous
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "payment_channel": "C7F634794B79DB40E87179A9D1BF05D05797AE7E92DF8E93FD6656E8C4BE3AE7", "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-paychannel)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-paychannel)
### Get DepositPreauth Object
Retrieve a [DepositPreauth entry](depositpreauth-object.html), which tracks preauthorization for payments to accounts requiring [Deposit Authorization](depositauth.html). [New in: rippled 1.1.0][]
Retrieve a [DepositPreauth entry](../../../protocol/ledger-data/ledger-entry-types/depositpreauth.md), which tracks preauthorization for payments to accounts requiring [Deposit Authorization](../../../../concepts/accounts/depositauth.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.1.0" %}New in: rippled 1.1.0{% /badge %}
| Field | Type | Description |
|:-----------------------------|:---------------------|:-----------------------|
| `deposit_preauth` | Object or String | Specify the DepositPreauth to retrieve. If a string, must be the [ledger entry ID](ledger-object-ids.html) of the DepositPreauth entry, as hexadecimal. If an object, requires `owner` and `authorized` sub-fields. |
| `deposit_preauth` | Object or String | Specify the DepositPreauth to retrieve. If a string, must be the [ledger entry ID](../../../protocol/ledger-data/common-fields.md) of the DepositPreauth entry, as hexadecimal. If an object, requires `owner` and `authorized` sub-fields. |
| `deposit_preauth.owner` | String - [Address][] | _(Required if `deposit_preauth` is specified as an object)_ The account that provided the preauthorization. |
| `deposit_preauth.authorized` | String - [Address][] | _(Required if `deposit_preauth` is specified as an object)_ The account that received the preauthorization. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_deposit_preauth",
@@ -549,9 +550,9 @@ Retrieve a [DepositPreauth entry](depositpreauth-object.html), which tracks prea
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -564,32 +565,32 @@ Retrieve a [DepositPreauth entry](depositpreauth-object.html), which tracks prea
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "deposit_preauth": { "owner": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "authorized": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX" }, "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-depositpreauth)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-depositpreauth)
### Get Ticket Object
Retrieve a [Ticket entry](ticket.html), which represents a [sequence number][] set aside for future use. _(Added by the [TicketBatch amendment][])_
Retrieve a [Ticket entry](../../../protocol/ledger-data/ledger-entry-types/ticket.md), which represents a [sequence number][] set aside for future use. _(Added by the [TicketBatch amendment][])_
| Field | Type | Description |
|:--------------------|:---------------------|:----------------------|
| `ticket` | Object or String | The Ticket to retrieve. If a string, must be the [ledger entry ID](ledger-object-ids.html) of the Ticket, as hexadecimal. If an object, the `account` and `ticket_seq` sub-fields are required to uniquely specify the Ticket entry. |
| `ticket` | Object or String | The Ticket to retrieve. If a string, must be the [ledger entry ID](../../../protocol/ledger-data/common-fields.md) of the Ticket, as hexadecimal. If an object, the `account` and `ticket_seq` sub-fields are required to uniquely specify the Ticket entry. |
| `ticket.account` | String - [Address][] | _(Required if `ticket` is specified as an object)_ The owner of the Ticket. |
| `ticket.ticket_seq` | Number | _(Required if `ticket` is specified as an object)_ The Ticket Sequence number of the Ticket to retrieve. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_ticket",
@@ -601,9 +602,9 @@ Retrieve a [Ticket entry](ticket.html), which represents a [sequence number][] s
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -616,16 +617,17 @@ Retrieve a [Ticket entry](ticket.html), which represents a [sequence number][] s
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "ticket": { "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "ticket_seq: 389 }, "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-ticket)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-ticket)
### Get NFT Page
@@ -634,12 +636,11 @@ Return an NFT Page in its raw ledger format.
| Field | Type | Description |
|:------------------------|:---------------------------|:----------------------|
| `nft_page` | String | The [ledger entry ID](ledger-object-ids.html) of an [NFT Page](nftokenpage.html) to retrieve. |
| `nft_page` | String | The [ledger entry ID](../../../protocol/ledger-data/common-fields.md) of an [NFT Page](../../../protocol/ledger-data/ledger-entry-types/nftokenpage.md) to retrieve. |
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_nft_page",
@@ -648,9 +649,9 @@ Return an NFT Page in its raw ledger format.
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ledger_entry",
@@ -660,16 +661,17 @@ Return an NFT Page in its raw ledger format.
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
rippled json ledger_entry '{ "nft_page": "255DD86DDF59D778081A06D02701E9B2C9F4F01DFFFFFFFFFFFFFFFFFFFFFFFF", "ledger_index": "validated" }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ledger_entry-nft-page)
[Try it! >](/resources/dev-tools/websocket-api-tool#ledger_entry-nft-page)
## Response Format
@@ -677,17 +679,16 @@ The response follows the [standard format][], with a successful result containin
| Field | Type | Description |
|:---------------|:-----------------|:-----------------------------------------|
| `index` | String | The unique ID of this [ledger entry](ledger-object-types.html). |
| `index` | String | The unique ID of this [ledger entry](../../../protocol/ledger-data/ledger-entry-types/index.md). |
| `ledger_index` | Unsigned Integer | The [ledger index][] of the ledger that was used when retrieving this data. |
| `node` | Object | _(Omitted if `"binary": true` specified.)_ Object containing the data of this ledger entry, according to the [ledger format][]. |
| `node_binary` | String | _(Omitted unless `"binary":true` specified)_ The [binary representation](serialization.html) of the ledger object, as hexadecimal. |
| `node_binary` | String | _(Omitted unless `"binary":true` specified)_ The [binary representation](../../../protocol/binary-format.md) of the ledger object, as hexadecimal. |
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "example_get_accountroot",
@@ -718,9 +719,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -751,9 +752,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result": {
@@ -782,8 +783,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
## Possible Errors
@@ -799,9 +801,4 @@ An example of a successful response:
* `malformedRequest` - The request provided an invalid combination of fields, or provided the wrong type for one or more fields.
* `unknownOption` - The fields provided in the request did not match any of the expected request formats.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

47
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/amm_info.md
View File

@@ -11,24 +11,23 @@ labels:
# amm_info
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/AMMInfo.cpp "Source")
The `{{currentpage.name}}` method gets information about an Automated Market Maker (AMM) instance.
The {% code-page-name /%} method gets information about an Automated Market Maker (AMM) instance.
_(Requires the [AMM amendment][] :not_enabled:)_
_(Requires the [AMM amendment][] {% not-enabled /%})_
### Request Format
An example of the request format:
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"command": "{{currentpage.name}}",
"command": "{% $frontmatter.seo.title %}",
"asset": {
"currency": "XRP"
},
@@ -38,12 +37,12 @@ An example of the request format:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "{{currentpage.name}}",
"method": "{% $frontmatter.seo.title %}",
"params": [{
"asset": {
"currency": "XRP"
@@ -55,10 +54,11 @@ An example of the request format:
}]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html?server=wss%3A%2F%2Famm.devnet.rippletest.net%3A51233%2F#amm_info)
[Try it! >](/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Famm.devnet.rippletest.net%3A51233%2F#amm_info)
The request includes the following parameters:
@@ -75,10 +75,9 @@ You must specify _either_ `amm_account` or both `asset` and `asset2`.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"result": {
@@ -131,9 +130,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -187,8 +186,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -210,8 +210,8 @@ The `amm` field is an object describing the current status of an Automated Marke
| `account` | String | The [Address][] of the AMM Account. |
| `amount` | [Currency Amount][] | The total amount of one asset in the AMM's pool. (Note: This could be `asset` _or_ `asset2` from the request.) |
| `amount2` | [Currency Amount][] | The total amount of the other asset in the AMM's pool. (Note: This could be `asset` _or_ `asset2` from the request.) |
| `asset_frozen` | Boolean | _(Omitted for XRP)_ If `true`, the `amount` currency is currently [frozen](freezes.html). |
| `asset2_frozen` | Boolean | _(Omitted for XRP)_ If `true`, the `amount2` currency is currently [frozen](freezes.html). |
| `asset_frozen` | Boolean | _(Omitted for XRP)_ If `true`, the `amount` currency is currently [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `asset2_frozen` | Boolean | _(Omitted for XRP)_ If `true`, the `amount2` currency is currently [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
| `auction_slot` | Object | _(May be omitted)_ An [Auction Slot Object](#auction-slot-object) describing the current auction slot holder, if there is one. |
| `lp_token` | [Currency Amount][] | The total amount of this AMM's LP Tokens outstanding. If the request specified a liquidity provider in the `account` field, instead, this is the amount of this AMM's LP Tokens held by that liquidity provider. |
| `trading_fee` | Number | The AMM's current trading fee, in units of 1/100,000; a value of 1 is equivalent to a 0.001% fee. |
@@ -252,11 +252,8 @@ Each entry in the `vote_slots` array represents one liquidity provider's vote to
## See Also
- [AMM object](amm.html) - The canonical storage format of the AMM object
- [AMM object](../../../protocol/ledger-data/ledger-entry-types/amm.md) - The canonical storage format of the AMM object
- [AMMBid][] - More info on the auction slot and bidding mechanism
- [AMMVote][] - More info on the trading fee voting mechanism
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

48
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/book_offers.md
View File

@@ -9,15 +9,14 @@ labels:
# book_offers
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/BookOffers.cpp "Source")
The `book_offers` method retrieves a list of [Offers](offers.html) between two currencies, also known as an _order book_. The response omits [unfunded Offers](offers.html#lifecycle-of-an-offer) and reports how much of each remaining Offer's total is currently funded.
The `book_offers` method retrieves a list of [Offers](../../../../concepts/tokens/decentralized-exchange/offers.md) between two currencies, also known as an _order book_. The response omits [unfunded Offers](../../../../concepts/tokens/decentralized-exchange/offers.md#lifecycle-of-an-offer) and reports how much of each remaining Offer's total is currently funded.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 4,
@@ -33,9 +32,9 @@ An example of the request format:
"limit": 10
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "book_offers",
@@ -54,24 +53,25 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: book_offers taker_pays taker_gets [taker [ledger [limit] ] ]
rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#book_offers)
[Try it! >](/resources/dev-tools/websocket-api-tool#book_offers)
The request includes the following parameters:
| `Field` | Type | Required? | Description |
|:---------------|:-----------------|:----------|-------------|
| `taker_gets` | Object | Yes | The asset the account taking the Offer would receive, as a [currency without an amount](currency-formats.html#specifying-without-amounts). |
| `taker_pays` | Object | Yes | The asset the account taking the Offer would pay, as a [currency without an amount](currency-formats.html#specifying-without-amounts). |
| `taker_gets` | Object | Yes | The asset the account taking the Offer would receive, as a [currency without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). |
| `taker_pays` | Object | Yes | The asset the account taking the Offer would pay, as a [currency without an amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). |
| `ledger_hash` | [Hash][] | No | A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | [Ledger Index][] | No | The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
| `limit` | Number | No | The maximum number of Offers to return. The response may include fewer results. |
@@ -82,10 +82,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 11,
@@ -144,9 +143,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -159,9 +158,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -231,8 +230,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -241,7 +241,7 @@ The response follows the [standard format][], with a successful result containin
| `ledger_current_index` | [Ledger Index][] | _(Omitted if `ledger_current_index` is provided)_ The [ledger index][] of the current in-progress ledger version, which was used to retrieve this information. |
| `ledger_index` | [Ledger Index][] | _(Omitted if `ledger_current_index` provided)_ The ledger index of the ledger version that was used when retrieving this data, as requested. |
| `ledger_hash` | [Hash][] | _(May be omitted)_ The identifying hash of the ledger version that was used when retrieving this data, as requested. |
| `offers` | Array | Array of offer objects, each of which has the fields of an [Offer object](offer.html) |
| `offers` | Array | Array of offer objects, each of which has the fields of an [Offer object](../../../protocol/ledger-data/ledger-entry-types/offer.md) |
In addition to the standard Offer fields, the following fields may be included in members of the `offers` array:
@@ -263,8 +263,4 @@ In addition to the standard Offer fields, the following fields may be included i
* `dstIsrMalformed` - The `issuer` field of the `taker_gets` field in the request is not valid.
* `badMarket` - The desired order book does not exist; for example, offers to exchange a currency for itself.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

42
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/deposit_authorized.md
View File

@@ -9,15 +9,14 @@ labels:
# deposit_authorized
[[Source]](https://github.com/XRPLF/rippled/blob/817d2339b8632cb2f97d3edd6f7af33aa7631744/src/ripple/rpc/handlers/DepositAuthorized.cpp "Source")
The `deposit_authorized` command indicates whether one account is authorized to send payments directly to another. See [Deposit Authorization](depositauth.html) for information on how to require authorization to deliver money to your account. <!-- STYLE_OVERRIDE: is authorized to -->
The `deposit_authorized` command indicates whether one account is authorized to send payments directly to another. See [Deposit Authorization](../../../../concepts/accounts/depositauth.md) for information on how to require authorization to deliver money to your account. <!-- STYLE_OVERRIDE: is authorized to -->
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -27,9 +26,9 @@ An example of the request format:
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "deposit_authorized",
@@ -42,15 +41,16 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```bash
#Syntax: deposit_authorized <source_account> <destination_account> [<ledger>]
rippled deposit_authorized rEhxGqkqPPSxQ3P25J66ft5TwpzV14k2de rsUiUMpnrgxQp24dJYZDhmV4bE3aBtQyt8 validated
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -66,10 +66,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -85,9 +84,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -101,9 +100,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
Loading: "/etc/rippled.cfg"
2018-Jul-30 20:07:38.771658157 HTTPClient:NFO Connecting to 127.0.0.1:5005
@@ -120,14 +119,15 @@ Loading: "/etc/rippled.cfg"
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:-----------------------|:--------------------------|:------------------------|
| `deposit_authorized` | Boolean | Whether the specified source account is authorized to send payments directly to the destination account. If `true`, either the destination account does not require [Deposit Authorization](depositauth.html) or the source account is preauthorized. |
| `deposit_authorized` | Boolean | Whether the specified source account is authorized to send payments directly to the destination account. If `true`, either the destination account does not require [Deposit Authorization](../../../../concepts/accounts/depositauth.md) or the source account is preauthorized. |
| `destination_account` | String - [Address][] | The destination account specified in the request. |
| `ledger_hash` | String | _(May be omitted)_ The identifying hash of the ledger that was used to generate this response. |
| `ledger_index` | Number - [Ledger Index][] | _(May be omitted)_ The ledger index of the ledger version that was used to generate this response. |
@@ -135,7 +135,7 @@ The response follows the [standard format][], with a successful result containin
| `source_account` | String - [Address][] | The source account specified in the request. |
| `validated` | Boolean | _(May be omitted)_ If `true`, the information comes from a validated ledger version. |
**Note:** A `deposit_authorized` status of `true` does not guarantee that a payment can be sent from the specified source to the specified destination. For example, the destination account may not have a [trust line](trust-lines-and-issuing.html) for the specified currency, or there may not be enough liquidity to deliver a payment.
**Note:** A `deposit_authorized` status of `true` does not guarantee that a payment can be sent from the specified source to the specified destination. For example, the destination account may not have a [trust line](../../../../concepts/tokens/fungible-tokens/index.md) for the specified currency, or there may not be enough liquidity to deliver a payment.
## Possible Errors
@@ -146,6 +146,4 @@ The response follows the [standard format][], with a successful result containin
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `srcActNotFound` - The `source_account` field of the request does not correspond to an account in the ledger.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: path-and-order-book-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Path and Order Book Methods
Paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Use these methods to work with paths and other books.
Paths define a way for payments to flow through intermediary steps on their way from sender to receiver. Paths enable cross-currency payments by connecting sender and receiver through order books. Use these methods to work with paths and other books.
{% child-pages /%}

36
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/nft_buy_offers.md
View File

@@ -15,12 +15,11 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Request Format
An example of the request format:
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"command": "nft_buy_offers",
@@ -28,9 +27,9 @@ An example of the request format:
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "nft_buy_offers",
@@ -40,10 +39,11 @@ An example of the request format:
}]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#nft_buy_offers)
[Try it! >](/resources/dev-tools/websocket-api-tool#nft_buy_offers)
The request includes the following parameters:
@@ -59,10 +59,9 @@ The request includes the following parameters:
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"result": {
@@ -80,9 +79,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -99,8 +98,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -118,8 +118,8 @@ Each member of the `offers` array represents one [NFTokenOffer object][] to buy
| `Field` | Type | Description |
|:------------------|:-----------------|:--------------------------------------|
| `amount` | String or Object | The amount offered to buy the NFT for, as a String representing an amount in drops of XRP, or an object representing an amount of a fungible token. (See [Specifying Currency Amounts][Currency Amount]) |
| `flags` | Number | A set of bit-flags for this offer. See [NFTokenOffer flags](nftokenoffer.html#nftokenoffer-flags) for possible values. |
| `nft_offer_index` | String | The [ledger object ID](ledger-object-ids.html) of this offer. |
| `flags` | Number | A set of bit-flags for this offer. See [NFTokenOffer flags](../../../protocol/ledger-data/ledger-entry-types/nftokenoffer.md#nftokenoffer-flags) for possible values. |
| `nft_offer_index` | String | The [ledger object ID](../../../protocol/ledger-data/common-fields.md) of this offer. |
| `owner` | String | The account that placed this offer. |
## Possible Errors
@@ -129,6 +129,4 @@ Each member of the `offers` array represents one [NFTokenOffer object][] to buy
* `actNotFound` - The [Address][] specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

36
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/nft_sell_offers.md
View File

@@ -15,12 +15,11 @@ _(Added by the [NonFungibleTokensV1_1 amendment][].)_
## Request Format
An example of the request format:
{% include '_snippets/no-cli-syntax.md' %}
{% partial file="/_snippets/no-cli-syntax.md" /%}
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"command": "nft_sell_offers",
@@ -28,9 +27,9 @@ An example of the request format:
"ledger_index": "validated"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "nft_sell_offers",
@@ -41,10 +40,11 @@ An example of the request format:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#nft_sell_offers)
[Try it! >](/resources/dev-tools/websocket-api-tool#nft_sell_offers)
The request includes the following parameters:
@@ -59,10 +59,9 @@ The request includes the following parameters:
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"result": {
@@ -80,9 +79,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -99,8 +98,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -119,8 +119,8 @@ Each member of the `offers` array represents one [NFTokenOffer object][] to buy
| `Field` | Type | Description |
|:------------------|:-----------------|:--------------------------------------|
| `amount` | String or Object | The amount offered to sell the NFT for, as a String representing an amount in drops of XRP, or an object representing an amount of a fungible token. (See [Specifying Currency Amounts][Currency Amount]) |
| `flags` | Number | A set of bit-flags for this offer. See [NFTokenOffer flags](nftokenoffer.html#nftokenoffer-flags) for possible values. |
| `nft_offer_index` | String | The [ledger object ID](ledger-object-ids.html) of this offer. |
| `flags` | Number | A set of bit-flags for this offer. See [NFTokenOffer flags](../../../protocol/ledger-data/ledger-entry-types/nftokenoffer.md#nftokenoffer-flags) for possible values. |
| `nft_offer_index` | String | The [ledger object ID](../../../protocol/ledger-data/common-fields.md) of this offer. |
| `owner` | String | The account that placed this offer. |
## Possible Errors
@@ -130,6 +130,4 @@ Each member of the `offers` array represents one [NFTokenOffer object][] to buy
* `actNotFound` - The [Address][] specified in the `account` field of the request does not correspond to an account in the ledger.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

64
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/path_find.md
View File

@@ -9,7 +9,7 @@ labels:
# path_find
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp "Source")
*WebSocket API only!* The `path_find` method searches for a [path](paths.html) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see the [ripple_path_find method][]. For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
*WebSocket API only!* The `path_find` method searches for a [path](../../../../concepts/tokens/fungible-tokens/paths.md) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see the [ripple_path_find method][]. For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the `subcommand` parameter:
@@ -29,10 +29,9 @@ A client can only have one pathfinding request open at a time. If another pathfi
### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 8,
@@ -47,10 +46,11 @@ An example of the request format:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#path_find)
[Try it! >](/resources/dev-tools/websocket-api-tool#path_find)
The request includes the following parameters:
@@ -59,9 +59,9 @@ The request includes the following parameters:
| `subcommand` | String | Use `"create"` to send the create sub-command |
| `source_account` | String | Unique address of the account to find a path from. (In other words, the account that would be sending a payment.) |
| `destination_account` | String | Unique address of the account to find a path to. (In other words, the account that would receive a payment.) |
| `destination_amount` | String or Object | [Currency Amount][] that the destination account would receive in a transaction. **Special case:** [New in: rippled 0.30.0][] You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
| `send_max` | String or Object | _(Optional)_ [Currency Amount][] that would be spent in the transaction. Not compatible with `source_currencies`. [New in: rippled 0.30.0][] |
| `paths` | Array | _(Optional)_ Array of arrays of objects, representing [payment paths](paths.html) to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path. |
| `destination_amount` | String or Object | [Currency Amount][] that the destination account would receive in a transaction. **Special case:** {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.30.0" %}New in: rippled 0.30.0{% /badge %} You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
| `send_max` | String or Object | _(Optional)_ [Currency Amount][] that would be spent in the transaction. Not compatible with `source_currencies`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.30.0" %}New in: rippled 0.30.0{% /badge %} |
| `paths` | Array | _(Optional)_ Array of arrays of objects, representing [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path. |
The server also recognizes the following fields, but the results of using them are not guaranteed: `source_currencies`, `bridges`. These fields should be considered reserved for future use.
@@ -69,10 +69,9 @@ The server also recognizes the following fields, but the results of using them a
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -438,24 +437,25 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The initial response follows the [standard format](response-formatting.html), with a successful result containing the following fields:
The initial response follows the [standard format](../../api-conventions/response-formatting.md), with a successful result containing the following fields:
| Field | Type | Description |
|:----------------------|:-----------------|:----------------------------------|
| `alternatives` | Array | Array of objects with suggested [paths](paths.html) to take, as described below. If empty, then no paths were found connecting the source and destination accounts. |
| `alternatives` | Array | Array of objects with suggested [paths](../../../../concepts/tokens/fungible-tokens/paths.md) to take, as described below. If empty, then no paths were found connecting the source and destination accounts. |
| `destination_account` | String | Unique address of the account that would receive a transaction. |
| `destination_amount` | String or Object | [Currency Amount][] that the destination would receive in a transaction. |
| `source_account` | String | Unique address that would send a transaction. |
| `full_reply` | Boolean | If `false`, this is the result of an incomplete search. A later reply may have a better path. If `true`, then this is the best path found. (It is still theoretically possible that a better path could exist, but `rippled` won't find it.) Until you close the pathfinding request, `rippled` continues to send updates each time a new ledger closes. [New in: rippled 0.29.0][] |
| `full_reply` | Boolean | If `false`, this is the result of an incomplete search. A later reply may have a better path. If `true`, then this is the best path found. (It is still theoretically possible that a better path could exist, but `rippled` won't find it.) Until you close the pathfinding request, `rippled` continues to send updates each time a new ledger closes. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.29.0" %}New in: rippled 0.29.0{% /badge %} |
Each element in the `alternatives` array is an object that represents a path from one possible source currency (held by the initiating account) to the destination account and currency. This object has the following fields:
| Field | Type | Description |
|:---------------------|:-----------------|:---------------------------------------|
| `paths_computed` | Array | Array of arrays of objects defining [payment paths](paths.html) |
| `paths_computed` | Array | Array of arrays of objects defining [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) |
| `source_amount` | String or Object | [Currency Amount][] that the source would have to send along this path for the destination to receive the desired amount. |
| `destination_amount` | String or Object | _(May be omitted)_ [Currency Amount][] that the destination would receive along this path. Only included if the `destination_amount` from the request was the "-1" special case. |
@@ -467,16 +467,15 @@ Each element in the `alternatives` array is an object that represents a path fro
### Asynchronous Follow-ups
In addition to the initial response, the server sends more messages in a similar format to update on the status of [payment paths](paths.html) over time. These messages include the `id` of the original WebSocket request so you can tell which request prompted them, and the field `"type": "path_find"` at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.
In addition to the initial response, the server sends more messages in a similar format to update on the status of [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) over time. These messages include the `id` of the original WebSocket request so you can tell which request prompted them, and the field `"type": "path_find"` at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.
If the follow-up includes `"full_reply": true`, then this is the best path that rippled can find as of the current ledger.
Here is an example of an asynchronous follow-up from a path_find create request:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -493,8 +492,9 @@ Here is an example of an asynchronous follow-up from a path_find create request:
"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
## path_find close
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L58-L67 "Source")
@@ -504,10 +504,9 @@ The `close` sub-command of `path_find` instructs the server to stop sending info
### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 57,
@@ -515,8 +514,9 @@ An example of the request format:
"subcommand": "close"
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -549,10 +549,9 @@ The `status` sub-command of `path_find` requests an immediate update about the c
### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 58,
@@ -560,8 +559,9 @@ An example of the request format:
"subcommand": "status"
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -586,6 +586,4 @@ If there was no outstanding pathfinding request, an error is returned instead.
* `noEvents` - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See the [ripple_path_find method][] for a pathfinding method that _is_ compatible with JSON-RPC.)
* `noPathRequest` - You tried to check the status of a pathfinding request when there is not an open one.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

45
content/references/http-websocket-apis/public-api-methods/path-and-order-book-methods/ripple_path_find.md
View File

@@ -9,7 +9,7 @@ labels:
# ripple_path_find
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/RipplePathFind.cpp "Source")
The `ripple_path_find` method is a simplified version of the [path_find method][] that provides a single response with a [payment path](paths.html) you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making multiple calls to stay updated, you should instead use the [path_find method][] to subscribe to continued updates where possible.
The `ripple_path_find` method is a simplified version of the [path_find method][] that provides a single response with a [payment path](../../../../concepts/tokens/fungible-tokens/paths.md) you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making multiple calls to stay updated, you should instead use the [path_find method][] to subscribe to continued updates where possible.
Although the `rippled` server tries to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths.
@@ -18,10 +18,9 @@ Although the `rippled` server tries to find the cheapest path or combination of
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 8,
@@ -43,9 +42,9 @@ An example of the request format:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ripple_path_find",
@@ -70,17 +69,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax ripple_path_find json ledger_index|ledger_hash
rippled ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "source_currencies": [ { "currency": "XRP" }, { "currency": "USD" } ], "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "destination_amount": { "value": "0.001", "currency": "USD", "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B" } }'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ripple_path_find)
[Try it! >](/resources/dev-tools/websocket-api-tool#ripple_path_find)
The request includes the following parameters:
@@ -88,8 +88,8 @@ The request includes the following parameters:
|:----------------------|:---------------------------|:------------------------|
| `source_account` | String | Unique address of the account that would send funds in a transaction |
| `destination_account` | String | Unique address of the account that would receive funds in a transaction |
| `destination_amount` | String or Object | [Currency Amount][] that the destination account would receive in a transaction. **Special case:** [New in: rippled 0.30.0][] You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
| `send_max` | String or Object | _(Optional)_ [Currency Amount][] that would be spent in the transaction. Cannot be used with `source_currencies`. [New in: rippled 0.30.0][] |
| `destination_amount` | String or Object | [Currency Amount][] that the destination account would receive in a transaction. **Special case:** {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.30.0" %}New in: rippled 0.30.0{% /badge %} You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
| `send_max` | String or Object | _(Optional)_ [Currency Amount][] that would be spent in the transaction. Cannot be used with `source_currencies`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.30.0" %}New in: rippled 0.30.0{% /badge %} |
| `source_currencies` | Array | _(Optional)_ Array of currencies that the source account might want to spend. Each entry in the array should be a JSON object with a mandatory `currency` field and optional `issuer` field, like how [currency amounts][Currency Amount] are specified. Cannot contain more than **18** source currencies. By default, uses all source currencies available up to a maximum of **88** different currency/issuer pairs. |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying Ledgers][]) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The [ledger index][] of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers][]) |
@@ -98,10 +98,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 8,
@@ -208,9 +207,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -317,8 +316,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -419,8 +419,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -434,7 +435,7 @@ Each element in the `alternatives` array is an object that represents a path fro
| `Field` | Type | Description |
|:-----------------|:-----------------|:---------------------------------------|
| `paths_computed` | Array | Array of arrays of objects defining [payment paths](paths.html) |
| `paths_computed` | Array | Array of arrays of objects defining [payment paths](../../../../concepts/tokens/fungible-tokens/paths.md) |
| `source_amount` | String or Object | [Currency Amount][] that the source would have to send along this path for the destination to receive the desired amount |
The following fields are deprecated, and may be omitted: `paths_canonical`, and `paths_expanded`. If they appear, you should disregard them.
@@ -451,6 +452,4 @@ The following fields are deprecated, and may be omitted: `paths_canonical`, and
* `srcCurMalformed` - The `source_currencies` field is not formatted properly.
* `srcIsrMalformed` - The `issuer` field of one or more of the currency objects in the request is not valid.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

53
content/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_authorize.md
View File

@@ -8,17 +8,16 @@ labels:
# channel_authorize
[[Source]](https://github.com/XRPLF/rippled/blob/d4a56f223a3b80f64ff70b4e90ab6792806929ca/src/ripple/rpc/handlers/PayChanClaim.cpp#L41 "Source")
_(Added by the [PayChan amendment][] to be enabled. [New in: rippled 0.33.0][])_
_(Added by the [PayChan amendment][] to be enabled. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.33.0" %}New in: rippled 0.33.0{% /badge %})_
The `channel_authorize` method creates a signature that can be used to redeem a specific amount of XRP from a payment channel.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "channel_authorize_example_id1",
@@ -29,9 +28,9 @@ An example of the request format:
"amount": "1000000",
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
POST http://localhost:5005/
Content-Type: application/json
@@ -46,40 +45,40 @@ Content-Type: application/json
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: channel_authorize <private_key> [<key_type>] <channel_id> <drops>
rippled channel_authorize s████████████████████████████ secp256k1 5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3 1000000
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
| Field | Type | Description |
|-------|------|-------------|
| `channel_id` | String | The unique ID of the payment channel to use.
| `secret` | String | _(Optional)_ The secret key to use to sign the claim. This must be the same key pair as the public key specified in the channel. Cannot be used with `seed`, `seed_hex`, or `passphrase`. [Updated in: rippled 1.4.0][] |
| `seed` | String | _(Optional)_ The secret seed to use to sign the claim. This must be the same key pair as the public key specified in the channel. Must be in the XRP Ledger's [base58][] format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed_hex`, or `passphrase`. [New in: rippled 1.4.0][] |
| `seed_hex` | String | _(Optional)_ The secret seed to use to sign the claim. This must be the same key pair as the public key specified in the channel. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. [New in: rippled 1.4.0][] |
| `passphrase` | String | _(Optional)_ A string passphrase to use to sign the claim. This must be the same key pair as the public key specified in the channel. The [key derived from this passphrase](cryptographic-keys.html#key-derivation) must match the public key specified in the channel. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. [New in: rippled 1.4.0][] |
| `key_type` | String | _(Optional)_ The [signing algorithm](cryptographic-keys.html#signing-algorithms) of the cryptographic key pair provided. Valid types are `secp256k1` or `ed25519`. The default is `secp256k1`. [New in: rippled 1.4.0][] |
| `secret` | String | _(Optional)_ The secret key to use to sign the claim. This must be the same key pair as the public key specified in the channel. Cannot be used with `seed`, `seed_hex`, or `passphrase`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}Updated in: rippled 1.4.0{% /badge %} |
| `seed` | String | _(Optional)_ The secret seed to use to sign the claim. This must be the same key pair as the public key specified in the channel. Must be in the XRP Ledger's [base58][] format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed_hex`, or `passphrase`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %} |
| `seed_hex` | String | _(Optional)_ The secret seed to use to sign the claim. This must be the same key pair as the public key specified in the channel. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %} |
| `passphrase` | String | _(Optional)_ A string passphrase to use to sign the claim. This must be the same key pair as the public key specified in the channel. The [key derived from this passphrase](../../../../concepts/accounts/cryptographic-keys.md#key-derivation) must match the public key specified in the channel. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %} |
| `key_type` | String | _(Optional)_ The [signing algorithm](../../../../concepts/accounts/cryptographic-keys.md#signing-algorithms) of the cryptographic key pair provided. Valid types are `secp256k1` or `ed25519`. The default is `secp256k1`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %} |
| `amount` | String | Cumulative amount of XRP, in drops, to authorize. If the destination has already received a lesser amount of XRP from this channel, the signature created by this method can be redeemed for the difference. |
The request **must** specify exactly one of `secret`, `seed`, `seed_hex`, or `passphrase`.
**Warning:** Do not send secret keys to untrusted servers or through unsecured network connections. (This includes the `secret`, `seed`, `seed_hex`, or `passphrase` fields of this request.) You should only use this method on a secure, encrypted network connection to a server you run or fully trust with your funds. Otherwise, eavesdroppers could use your secret key to sign claims and take all the money from this payment channel and anything else using the same key pair. See [Set Up Secure Signing](secure-signing.html) for instructions.
**Warning:** Do not send secret keys to untrusted servers or through unsecured network connections. (This includes the `secret`, `seed`, `seed_hex`, or `passphrase` fields of this request.) You should only use this method on a secure, encrypted network connection to a server you run or fully trust with your funds. Otherwise, eavesdroppers could use your secret key to sign claims and take all the money from this payment channel and anything else using the same key pair. See [Set Up Secure Signing](../../../../concepts/transactions/secure-signing.md) for instructions.
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "channel_authorize_example_id1",
@@ -89,9 +88,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -102,9 +101,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result": {
@@ -113,8 +112,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -125,12 +125,9 @@ The response follows the [standard format][], with a successful result containin
## Possible Errors
* Any of the [universal error types][].
* `badKeyType` - The `key_type` parameter in the request is not a valid key type. (Valid types are `secp256k1` or `ed25519`.) [New in: rippled 1.4.0][]
* `badKeyType` - The `key_type` parameter in the request is not a valid key type. (Valid types are `secp256k1` or `ed25519`.) {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %}
* `badSeed` - The `secret` in the request is not a valid secret key.
* `channelAmtMalformed` - The `amount` in the request is not a valid [XRP amount][XRP, in drops].
* `channelMalformed` - The `channel_id` in the request is not a valid Channel ID. The Channel ID should be a 256-bit (64-character) hexadecimal string.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

42
content/references/http-websocket-apis/public-api-methods/payment-channel-methods/channel_verify.md
View File

@@ -8,17 +8,16 @@ labels:
# channel_verify
[[Source]](https://github.com/XRPLF/rippled/blob/d4a56f223a3b80f64ff70b4e90ab6792806929ca/src/ripple/rpc/handlers/PayChanClaim.cpp#L89 "Source")
_(Added by the [PayChan amendment][] to be enabled. [New in: rippled 0.33.0][])_
_(Added by the [PayChan amendment][] to be enabled. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.33.0" %}New in: rippled 0.33.0{% /badge %})_
The `channel_verify` method checks the validity of a signature that can be used to redeem a specific amount of XRP from a payment channel.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -29,9 +28,9 @@ An example of the request format:
"amount": "1000000"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "channel_verify",
@@ -43,15 +42,16 @@ An example of the request format:
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: channel_verify <public_key> <channel_id> <amount> <signature>
rippled channel_verify aB44YfzW24VDEJQ2UuLPV2PvqcPCSoLnL7y5M1EzhdW4LnK5xMS3 5DB01B7FFED6B67E6B0414DED11E051D2EE2B7619CE0EAA6286D67A3A4D5BDB3 1000000 304402204EF0AFB78AC23ED1C472E74F4299C0C21F1B21D07EFC0A3838A420F76D783A400220154FB11B6F54320666E4C36CA7F686C16A3A0456800BBC43746F34AF50290064
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -59,17 +59,16 @@ The request includes the following parameters:
|-------|------|-------------|
| `amount` | String | The amount of [XRP, in drops][], the provided `signature` authorizes. |
| `channel_id` | String | The Channel ID of the channel that provides the XRP. This is a 64-character hexadecimal string. |
| `public_key` | String | The public key of the channel and the key pair that was used to create the signature, in hexadecimal or the XRP Ledger's [base58][] format. [Updated in: rippled 0.90.0][] |
| `public_key` | String | The public key of the channel and the key pair that was used to create the signature, in hexadecimal or the XRP Ledger's [base58][] format. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.90.0" %}Updated in: rippled 0.90.0{% /badge %} |
| `signature` | String | The signature to verify, in hexadecimal. |
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -80,9 +79,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -93,9 +92,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result": {
@@ -104,8 +103,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -119,10 +119,8 @@ The response follows the [standard format][], with a successful result containin
* Any of the [universal error types][].
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `publicMalformed` - The `public_key` field of the request is not a valid public key in the correct format. Public keys are 33 bytes and must be represented in base58 or hexadecimal. The [base58 representation of account public keys starts with the letter `a`](base58-encodings.html). The hexadecimal representation is 66 characters long.
* `publicMalformed` - The `public_key` field of the request is not a valid public key in the correct format. Public keys are 33 bytes and must be represented in base58 or hexadecimal. The [base58 representation of account public keys starts with the letter `a`](../../../protocol/data-types/base58-encodings.md). The hexadecimal representation is 66 characters long.
* `channelMalformed` - The `channel_id` field of the request is not a valid Channel ID. The Channel ID must be a 256-bit (64-character) hexadecimal string.
* `channelAmtMalformed` - The value specified in the `amount` field was not a valid [XRP amount][XRP, in drops].
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/payment-channel-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: payment-channel-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Payment Channel Methods
Payment channels are a tool for facilitating repeated, unidirectional payments, or temporary credit between two parties. Use these methods to work with payment channels.
Payment channels are a tool for facilitating repeated, unidirectional payments, or temporary credit between two parties. Use these methods to work with payment channels.
{% child-pages /%}

52
content/references/http-websocket-apis/public-api-methods/server-info-methods/fee.md
View File

@@ -8,41 +8,41 @@ labels:
# fee
[[Source]](https://github.com/XRPLF/rippled/blob/release/src/ripple/rpc/handlers/Fee1.cpp "Source")
The `fee` command reports the current state of the open-ledger requirements for the [transaction cost](transaction-cost.html). This requires the [FeeEscalation amendment][] to be enabled. [New in: rippled 0.31.0][]
The `fee` command reports the current state of the open-ledger requirements for the [transaction cost](../../../../concepts/transactions/transaction-cost.md). This requires the [FeeEscalation amendment][] to be enabled. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.31.0" %}New in: rippled 0.31.0{% /badge %}
This is a public command available to unprivileged users. [Updated in: rippled 0.32.0][]
This is a public command available to unprivileged users. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}Updated in: rippled 0.32.0{% /badge %}
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "fee_websocket_example",
"command": "fee"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "fee",
"params": [{}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: fee
rippled fee
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request does not include any parameters.
@@ -50,10 +50,9 @@ The request does not include any parameters.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "fee_websocket_example",
@@ -80,9 +79,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -109,9 +108,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
@@ -139,8 +138,9 @@ Connecting to 127.0.0.1:5005
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -149,25 +149,21 @@ The response follows the [standard format][], with a successful result containin
| `current_ledger_size` | String (Integer) | Number of transactions provisionally included in the in-progress ledger. |
| `current_queue_size` | String (Integer) | Number of transactions currently queued for the next ledger. |
| `drops` | Object | Various information about the transaction cost (the `Fee` field of a transaction), in [drops of XRP][]. |
| `drops.base_fee` | String (Integer) | The transaction cost required for a [reference transaction](transaction-cost.html#reference-transaction-cost) to be included in a ledger under minimum load, represented in drops of XRP. |
| `drops.base_fee` | String (Integer) | The transaction cost required for a [reference transaction](../../../../concepts/transactions/transaction-cost.md#reference-transaction-cost) to be included in a ledger under minimum load, represented in drops of XRP. |
| `drops.median_fee` | String (Integer) | An approximation of the median transaction cost among transactions included in the previous validated ledger, represented in drops of XRP. |
| `drops.minimum_fee` | String (Integer) | The minimum transaction cost for a [reference transaction](transaction-cost.html#reference-transaction-cost) to be queued for a later ledger, represented in drops of XRP. If greater than `base_fee`, the transaction queue is full. |
| `drops.open_ledger_fee` | String (Integer) | The minimum transaction cost that a [reference transaction](transaction-cost.html#reference-transaction-cost) must pay to be included in the current open ledger, represented in drops of XRP. |
| `drops.minimum_fee` | String (Integer) | The minimum transaction cost for a [reference transaction](../../../../concepts/transactions/transaction-cost.md#reference-transaction-cost) to be queued for a later ledger, represented in drops of XRP. If greater than `base_fee`, the transaction queue is full. |
| `drops.open_ledger_fee` | String (Integer) | The minimum transaction cost that a [reference transaction](../../../../concepts/transactions/transaction-cost.md#reference-transaction-cost) must pay to be included in the current open ledger, represented in drops of XRP. |
| `expected_ledger_size` | String (Integer) | The approximate number of transactions expected to be included in the current ledger. This is based on the number of transactions in the previous ledger. |
| `ledger_current_index` | Number | The [Ledger Index][] of the current open ledger these stats describe. [New in: rippled 0.50.0][] |
| `ledger_current_index` | Number | The [Ledger Index][] of the current open ledger these stats describe. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.50.0" %}New in: rippled 0.50.0{% /badge %} |
| `levels` | Object | Various information about the transaction cost, in [fee levels][]. The ratio in fee levels applies to any transaction relative to the minimum cost of that particular transaction. |
| `levels.median_level` | String (Integer) | The median transaction cost among transactions in the previous validated ledger, represented in [fee levels][]. |
| `levels.minimum_level` | String (Integer) | The minimum transaction cost required to be queued for a future ledger, represented in [fee levels][]. |
| `levels.open_ledger_level` | String (Integer) | The minimum transaction cost required to be included in the current open ledger, represented in [fee levels][]. |
| `levels.reference_level` | String (Integer) | The equivalent of the minimum transaction cost, represented in [fee levels][]. |
| `max_queue_size` | String (Integer) | The maximum number of transactions that the [transaction queue](transaction-cost.html#queued-transactions) can currently hold. |
| `max_queue_size` | String (Integer) | The maximum number of transactions that the [transaction queue](../../../../concepts/transactions/transaction-cost.md#queued-transactions) can currently hold. |
## Possible Errors
- Any of the [universal error types][].
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/server-info-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: server-info-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Server Info Methods
Use these methods to retrieve information about the current state of the rippled server.
Use these methods to retrieve information about the current state of the rippled server.
{% child-pages /%}

49
content/references/http-websocket-apis/public-api-methods/server-info-methods/manifest.md
View File

@@ -8,43 +8,43 @@ labels:
# manifest
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/Manifest.cpp "Source")
The `{{currentpage.name}}` method reports the current "manifest" information for a given validator public key. The "manifest" is a block of data that authorizes an ephemeral signing key with a signature from the validator's master key pair. [Updated in: rippled 1.7.0][]
The {% code-page-name /%} method reports the current "manifest" information for a given validator public key. The "manifest" is a block of data that authorizes an ephemeral signing key with a signature from the validator's master key pair. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.7.0" %}Updated in: rippled 1.7.0{% /badge %}
### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"command": "{{currentpage.name}}",
"command": "{% $frontmatter.seo.title %}",
"public_key": "nHUFE9prPXPrHcG3SkwP1UzAQbSphqyQkQK9ATXLZsfkezhhda3p"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "{{currentpage.name}}",
"method": "{% $frontmatter.seo.title %}",
"params": [{
"public_key":"nHUFE9prPXPrHcG3SkwP1UzAQbSphqyQkQK9ATXLZsfkezhhda3p"
}]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: {{currentpage.name}} public_key
rippled {{currentpage.name}} nHUFE9prPXPrHcG3SkwP1UzAQbSphqyQkQK9ATXLZsfkezhhda3p
#Syntax: {% $frontmatter.seo.title %} public_key
rippled {% $frontmatter.seo.title %} nHUFE9prPXPrHcG3SkwP1UzAQbSphqyQkQK9ATXLZsfkezhhda3p
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -57,10 +57,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"result": {
@@ -77,9 +76,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -97,9 +96,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
@@ -118,8 +117,9 @@ Connecting to 127.0.0.1:5005
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
<!-- Note, the CLI response above is mocked up to compensate for https://github.com/XRPLF/rippled/issues/3317 -->
@@ -128,7 +128,7 @@ The response follows the [standard format][], with a successful result containin
| `Field` | Type | Description |
|:------------|:-------|:------------------------------------------------------|
| `details` | Object | _(May be omitted)_ The data contained in this manifest. Omitted if the server does not have a manifest for the `public_key` from the request. See **Details Object** below for a full description of its contents. |
| `manifest` | String | _(May be omitted)_ The full manifest data in base64 format. This data is [serialized](serialization.html) to binary before being base64-encoded. Omitted if the server does not have a manifest for the `public_key` from the request. |
| `manifest` | String | _(May be omitted)_ The full manifest data in base64 format. This data is [serialized](../../../protocol/binary-format.md) to binary before being base64-encoded. Omitted if the server does not have a manifest for the `public_key` from the request. |
| `requested` | String | The `public_key` from the request. |
#### Details Object
@@ -149,7 +149,4 @@ If provided, the `details` object contains the following fields:
- `invalidParams` - The `public_key` field was missing or specified incorrectly.
- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

26
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_definitions.md
View File

@@ -15,20 +15,20 @@ The `server_definitions` command returns an SDK-compatible `definitions.json`, g
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
"command": "server_definitions"
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#server_definitions)
[Try it! >](/resources/dev-tools/websocket-api-tool#server_definitions)
The request does not take any parameters.
@@ -37,10 +37,9 @@ The request does not take any parameters.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -91,18 +90,15 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
To see a full `definitions.json` file and descriptions of the top-level fields, see: [Definitions File](serialization.html#definitions-file).
To see a full `definitions.json` file and descriptions of the top-level fields, see: [Definitions File](../../../protocol/binary-format.md#definitions-file).
## Possible Errors
Any of the [universal error types][].
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

87
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
View File

@@ -8,24 +8,23 @@ labels:
# server_info (rippled)
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/ServerInfo.cpp "Source")
The `server_info` command asks the server for a human-readable version of various information about [the `rippled` server](xrpl-servers.html) being queried. For [Clio servers](the-clio-server.html), see [`server_info` (Clio)](server_info-clio.html) instead.
The `server_info` command asks the server for a human-readable version of various information about [the `rippled` server](../../../../concepts/networks-and-servers/index.md) being queried. For [Clio servers](../../../../concepts/networks-and-servers/the-clio-server.md), see [`server_info` (Clio)](../clio-methods/server_info-clio.md) instead.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
"command": "server_info"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "server_info",
@@ -34,17 +33,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: server_info
rippled server_info
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#server_info)
[Try it! >](/resources/dev-tools/websocket-api-tool#server_info)
The request does not take any parameters.
@@ -52,32 +52,21 @@ The request does not take any parameters.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
{% tabs %}
*WebSocket*
{% tab label="WebSocket" %}
{% code-snippet file="/_api-examples/server_info/ws-response.json" language="json" /%}
{% /tab %}
```json
{% include '_api-examples/server_info/ws-response.json' %}
```
{% tab label="JSON-RPC" %}
{% code-snippet file="/_api-examples/server_info/jsonrpc-response.json" language="json" prefix="200 OK\n\n" /%}
{% /tab %}
*JSON-RPC*
{% tab label="Commandline" %}
{% code-snippet file="/_api-examples/server_info/jsonrpc-response.json" language="json" prefix="Loading: \"/etc/opt/ripple/rippled.cfg\"\n2023-Sep-13 22:19:39.404596100 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005\n\n" /%}
{% /tab %}
```json
200 OK
{% include '_api-examples/server_info/jsonrpc-response.json' %}
```
*Commandline*
```json
Loading: "/etc/opt/ripple/rippled.cfg"
2023-Sep-13 22:19:39.404596100 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005
{% include '_api-examples/server_info/jsonrpc-response.json' %}
```
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing an `info` object as its only field.
@@ -85,13 +74,13 @@ The `info` object may have some arrangement of the following fields:
| `Field` | Type | Description |
|:------------------------------------|:----------------|:---------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. |
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](../../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. |
| `build_version` | String | The version number of the running `rippled` server. |
| `closed_ledger` | Object | _(May be omitted)_ Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. |
| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. |
| `hostid` | String | On an admin request, returns the hostname of the server running the `rippled` instance; otherwise, returns a single [RFC-1751][] word based on the [node public key](peer-protocol.html#node-key-pair). |
| `hostid` | String | On an admin request, returns the hostname of the server running the `rippled` instance; otherwise, returns a single [RFC-1751][] word based on the [node public key](../../../../concepts/networks-and-servers/peer-protocol.md#node-key-pair). |
| `io_latency_ms` | Number | Amount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the `rippled` server is probably having serious load issues. |
| `jq_trans_overflow` | String - Number | The number of times (since starting up) that this server has had over 250 transactions waiting to be processed at once. A large number here may mean that your server is unable to handle the transaction load of the XRP Ledger network. For detailed recommendations of future-proof server specifications, see [Capacity Planning](capacity-planning.html). |
| `jq_trans_overflow` | String - Number | The number of times (since starting up) that this server has had over 250 transactions waiting to be processed at once. A large number here may mean that your server is unable to handle the transaction load of the XRP Ledger network. For detailed recommendations of future-proof server specifications, see [Capacity Planning](../../../../infrastructure/installation/capacity-planning.md). |
| `last_close` | Object | Information about the last time the server closed a ledger, including the amount of time it took to reach a consensus and the number of trusted validators participating. |
| `last_close.converge_time_s` | Number | The amount of time it took to reach a consensus on the most recently validated ledger version, in seconds. |
| `last_close.proposers` | Number | How many trusted validators the server considered (including itself, if configured as a validator) in the consensus process for the most recently validated ledger version. |
@@ -101,21 +90,21 @@ The `info` object may have some arrangement of the following fields:
| `load_factor` | Number | The multiplier to the [transaction cost][] the server is currently enforcing. For example, at `1000` load factor and a reference transaction cost of 10 drops of XRP, the load-scaled transaction cost is 10,000 drops (0.01 XRP). The load factor is determined by the highest of the individual server's load factor, the cluster's load factor, the open ledger cost, and the overall network's load factor. |
| `load_factor_local` | Number | _(May be omitted)_ The current multiplier to the transaction cost based on load to this server. |
| `load_factor_net` | Number | _(May be omitted)_ The current multiplier to the transaction cost being used by the rest of the network (estimated from other servers' reported load values). |
| `load_factor_cluster` | Number | _(May be omitted)_ The current multiplier to the transaction cost based on load to servers in this [cluster](clustering.html). |
| `load_factor_cluster` | Number | _(May be omitted)_ The current multiplier to the transaction cost based on load to servers in this [cluster](../../../../concepts/networks-and-servers/clustering.md). |
| `load_factor_fee_escalation` | Number | _(May be omitted)_ The current multiplier to the transaction cost that a transaction must pay to get into the open ledger. |
| `load_factor_fee_queue` | Number | _(May be omitted)_ The current multiplier to the transaction cost that a transaction must pay to get into the queue, if the queue is full. |
| `load_factor_server` | Number | _(May be omitted)_ The current multiplier to the transaction cost based on load to the server, cluster, and network, but not factoring in the open ledger cost. |
| `peers` | Number | _(Omitted by [reporting mode][Reporting mode] servers)_ How many other `rippled` servers this one is currently connected to. |
| `ports` | Array | A list of ports where the server is listening for API commands. Each entry in the array is a [Port Descriptor object](#port-descriptor-object). [New in: rippled 1.12.0][] |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This [_node key pair_](peer-protocol.html#node-key-pair) is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](clustering.html). |
| `ports` | Array | A list of ports where the server is listening for API commands. Each entry in the array is a [Port Descriptor object](#port-descriptor-object). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.12.0" %}New in: rippled 1.12.0{% /badge %} |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This [_node key pair_](../../../../concepts/networks-and-servers/peer-protocol.md#node-key-pair) is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](../../../../concepts/networks-and-servers/clustering.md). |
| `pubkey_validator` | String | _(Admin only)_ Public key used by this node to sign ledger validations. This _validation key pair_ is derived from the `[validator_token]` or `[validation_seed]` config field. |
| `reporting` | Object | _([Reporting mode](rippled-server-modes.html) servers only)_ Information about this server's reporting-mode specific configurations. |
| `reporting.etl_sources` | Array | _([Reporting mode](rippled-server-modes.html) servers only)_ A list of P2P-mode servers this reporting mode is retrieving data from. Each entry in this array is an [ETL Source object](#etl-source-object). |
| `reporting.is_writer` | Boolean | _([Reporting mode](rippled-server-modes.html) servers only)_ If `true`, this server is writing to the external database with ledger data. If `false`, it is not currently writing, possibly because another reporting mode server is currently populating a shared database, or because it's configured as read-only. |
| `reporting.last_publish_time` | String | _([Reporting mode](rippled-server-modes.html) servers only)_ An ISO 8601 timestamp indicating when this server last published a validated ledger to its [subscription streams](subscribe.html). |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](rippled-server-states.html) for more details. |
| `reporting` | Object | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ Information about this server's reporting-mode specific configurations. |
| `reporting.etl_sources` | Array | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ A list of P2P-mode servers this reporting mode is retrieving data from. Each entry in this array is an [ETL Source object](#etl-source-object). |
| `reporting.is_writer` | Boolean | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ If `true`, this server is writing to the external database with ledger data. If `false`, it is not currently writing, possibly because another reporting mode server is currently populating a shared database, or because it's configured as read-only. |
| `reporting.last_publish_time` | String | _([Reporting mode](../../../../concepts/networks-and-servers/rippled-server-modes.md) servers only)_ An ISO 8601 timestamp indicating when this server last published a validated ledger to its [subscription streams](../subscription-methods/subscribe.md). |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](../../api-conventions/rippled-server-states.md) for more details. |
| `server_state_duration_us` | Number | The number of consecutive microseconds the server has been in the current state. |
| `state_accounting` | Object | A map of various [server states](rippled-server-states.html) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. |
| `state_accounting` | Object | A map of various [server states](../../api-conventions/rippled-server-states.md) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. |
| `state_accounting.*.duration_us` | String | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) |
| `state_accounting.*.transitions` | String | The number of times the server has changed into this state. |
| `time` | String | The current time in UTC, according to the server's clock. |
@@ -132,16 +121,12 @@ The `info` object may have some arrangement of the following fields:
**Note:** If the `closed_ledger` field is present and has a small `seq` value (less than 8 digits), that indicates `rippled` does not currently have a copy of the validated ledger from the peer-to-peer network. This could mean your server is still syncing. Typically, it takes about 5 minutes to sync with the network, depending on your connection speed and hardware specs.
{% include '_snippets/etl-source-object.md' %}
{% partial file="/_snippets/etl-source-object.md" /%}
{% include '_snippets/port-descriptor-object.md' %}
{% partial file="/_snippets/port-descriptor-object.md" /%}
## Possible Errors
* Any of the [universal error types][].
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

64
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md
View File

@@ -11,15 +11,14 @@ labels:
The `server_state` command asks the server for various machine-readable information about the `rippled` server's current state. The response is almost the same as the [server_info method][], but uses units that are easier to process instead of easier to read. (For example, XRP values are given in integer drops instead of scientific notation or decimal values, and time is given in milliseconds instead of seconds.)
The [Clio server](the-clio-server.html) does not support `server_state` directly, but you can ask for the `server_state` of the `rippled` server that Clio is connected to. Specify `"ledger_index": "current"` (WebSocket) or `"params": [{"ledger_index": "current"}]` (JSON-RPC).
The [Clio server](../../../../concepts/networks-and-servers/the-clio-server.md) does not support `server_state` directly, but you can ask for the `server_state` of the `rippled` server that Clio is connected to. Specify `"ledger_index": "current"` (WebSocket) or `"params": [{"ledger_index": "current"}]` (JSON-RPC).
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -27,9 +26,9 @@ An example of the request format:
"ledger_index": "current"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "server_state",
@@ -38,17 +37,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: server_state
rippled server_state
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#server_state)
[Try it! >](/resources/dev-tools/websocket-api-tool#server_state)
The request does not takes any parameters.
@@ -56,10 +56,9 @@ The request does not takes any parameters.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -124,9 +123,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -193,9 +192,9 @@ Headers
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
Loading: "/etc/opt/ripple/rippled.cfg"
2020-Mar-24 01:30:08.646201720 UTC HTTPClient:NFO Connecting to 127.0.0.1:5005
@@ -263,8 +262,9 @@ Headers
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing a `state` object as its only field.
@@ -272,12 +272,12 @@ The `state` object may have some arrangement of the following fields:
| `Field` | Type | Description |
|:---------------------------------|:----------------|:------------------------|
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](amendments.html#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. |
| `amendment_blocked` | Boolean | _(May be omitted)_ If `true`, this server is [amendment blocked](../../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers). If the server is not amendment blocked, the response omits this field. |
| `build_version` | String | The version number of the running `rippled` version. |
| `complete_ledgers` | String | Range expression indicating the sequence numbers of the ledger versions the local `rippled` has in its database. It is possible to be a disjoint sequence, e.g. "2500-5000,32570-7695432". If the server does not have any complete ledgers (for example, it recently started syncing with the network), this is the string `empty`. |
| `closed_ledger` | Object | _(May be omitted)_ Information on the most recently closed ledger that has not been validated by consensus. If the most recently validated ledger is available, the response omits this field and includes `validated_ledger` instead. The member fields are the same as the `validated_ledger` field. |
| `io_latency_ms` | Number | Amount of time spent waiting for I/O operations, in milliseconds. If this number is not very, very low, then the `rippled` server is probably having serious load issues. |
| `jq_trans_overflow` | String - Number | The number of times this server has had over 250 transactions waiting to be processed at once. A large number here may mean that your server is unable to handle the transaction load of the XRP Ledger network. For detailed recommendations of future-proof server specifications, see [Capacity Planning](capacity-planning.html). |
| `jq_trans_overflow` | String - Number | The number of times this server has had over 250 transactions waiting to be processed at once. A large number here may mean that your server is unable to handle the transaction load of the XRP Ledger network. For detailed recommendations of future-proof server specifications, see [Capacity Planning](../../../../infrastructure/installation/capacity-planning.md). |
| `last_close` | Object | Information about the last time the server closed a ledger, including the amount of time it took to reach a consensus and the number of trusted validators participating. |
| `last_close.converge_time` | Number | The amount of time it took to reach a consensus on the most recently validated ledger version, in milliseconds. |
| `last_close.proposers` | Number | How many trusted validators the server considered (including itself, if configured as a validator) in the consensus process for the most recently validated ledger version. |
@@ -291,16 +291,16 @@ The `state` object may have some arrangement of the following fields:
| `load_factor_fee_reference` | Number | _(May be omitted)_ The transaction cost with no load scaling, in fee levels. |
| `load_factor_server` | Number | _(May be omitted)_ The load factor the server is enforcing, based on load to the server, cluster, and network, but not factoring in the open ledger cost. |
| `peers` | Number | _(Omitted by [reporting mode][Reporting mode] servers)_ How many other `rippled` servers this one is currently connected to. |
| `ports` | Array | A list of ports where the server is listening for API commands. Each entry in the array is a [Port Descriptor object](#port-descriptor-object). [New in: rippled 1.12.0][] |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This _node key pair_ is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](clustering.html). |
| `ports` | Array | A list of ports where the server is listening for API commands. Each entry in the array is a [Port Descriptor object](#port-descriptor-object). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.12.0" %}New in: rippled 1.12.0{% /badge %} |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This _node key pair_ is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](../../../../concepts/networks-and-servers/clustering.md). |
| `pubkey_validator` | String | _(Admin only)_ Public key used by this node to sign ledger validations. This _validation key pair_ is derived from the `[validator_token]` or `[validation_seed]` config field. |
| `reporting` | Object | _([Reporting mode][] servers only)_ Information about this server's reporting-mode specific configurations. |
| `reporting.etl_sources` | Array | _([Reporting mode][] servers only)_ A list of P2P-mode servers this reporting mode is retrieving data from. Each entry in this array is an [ETL Source object](#etl-source-object). |
| `reporting.is_writer` | Boolean | _([Reporting mode][] servers only)_ If `true`, this server is writing to the external database with ledger data. If `false`, it is not currently writing, possibly because another reporting mode server is currently populating a shared database, or because it's configured as read-only. |
| `reporting.last_publish_time` | String | _([Reporting mode][] servers only)_ An ISO 8601 timestamp indicating when this server last saw a new validated ledger from any of its P2P mode sources. |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](rippled-server-states.html) for more details. |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](../../api-conventions/rippled-server-states.md) for more details. |
| `server_state_duration_us` | Number | The number of consecutive microseconds the server has been in the current state. |
| `state_accounting` | Object | A map of various [server states](rippled-server-states.html) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. |
| `state_accounting` | Object | A map of various [server states](../../api-conventions/rippled-server-states.md) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. |
| `state_accounting.*.duration_us` | String | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) |
| `state_accounting.*.transitions` | String | The number of times the server has changed into this state. |
| `time` | String | The current time in UTC, according to the server's clock. |
@@ -309,24 +309,20 @@ The `state` object may have some arrangement of the following fields:
| `validated_ledger.base_fee` | Number | Base fee, in drops of XRP, for propagating a transaction to the network. |
| `validated_ledger.close_time` | Number | Time this ledger was closed, in [seconds since the Ripple Epoch][]. |
| `validated_ledger.hash` | String | Unique hash of this ledger version, as hexadecimal. |
| `validated_ledger.reserve_base` | Number | The minimum [account reserve](reserves.html), as of the most recent validated ledger version. |
| `validated_ledger.reserve_inc` | Number | The [owner reserve](reserves.html) for each item an account owns, as of the most recent validated ledger version. |
| `validated_ledger.reserve_base` | Number | The minimum [account reserve](../../../../concepts/accounts/reserves.md), as of the most recent validated ledger version. |
| `validated_ledger.reserve_inc` | Number | The [owner reserve](../../../../concepts/accounts/reserves.md) for each item an account owns, as of the most recent validated ledger version. |
| `validated_ledger.seq` | Number | The [ledger index][] of the most recently validated ledger version. |
| `validation_quorum` | Number | Minimum number of trusted validations required to validate a ledger version. Some circumstances may cause the server to require more validations. |
| `validator_list_expires` | Number | _(Admin only)_ When the current validator list expires, in [seconds since the Ripple Epoch][], or 0 if the server has yet to load a published validator list. |
[Reporting mode]: rippled-server-modes.html
[Reporting mode]: ../../../../concepts/networks-and-servers/rippled-server-modes.md
{% include '_snippets/etl-source-object.md' %}
{% partial file="/_snippets/etl-source-object.md" /%}
{% include '_snippets/port-descriptor-object.md' %}
{% partial file="/_snippets/port-descriptor-object.md" /%}
## Possible Errors
* Any of the [universal error types][].
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/subscription-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: subscription-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Subscription Methods
Use these methods to enable the server to push updates to your client when various events happen, so that you can know and react right away. WebSocket API only.
Use these methods to enable the server to push updates to your client when various events happen, so that you can know and react right away. WebSocket API only.
{% child-pages /%}

94
content/references/http-websocket-apis/public-api-methods/subscription-methods/subscribe.md
View File

@@ -16,10 +16,9 @@ The `subscribe` method requests periodic notifications from the server when cert
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*Subscribe to accounts*
{% tabs %}
{% tab label="Subscribe to accounts" %}
```json
{
"id": "Example watch Bitstamp's hot wallet",
@@ -27,9 +26,9 @@ An example of the request format:
"accounts": ["rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1"]
}
```
{% /tab %}
*Subscribe to order book*
{% tab label="Subscribe to order book" %}
```json
{
"id": "Example subscribe to XRP/GateHub USD order book",
@@ -48,9 +47,9 @@ An example of the request format:
]
}
```
{% /tab %}
*Subscribe to ledger stream*
{% tab label="Subscribe to ledger stream" %}
```json
{
"id": "Example watch for new validated ledgers",
@@ -58,10 +57,11 @@ An example of the request format:
"streams": ["ledger"]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#subscribe)
[Try it! >](/resources/dev-tools/websocket-api-tool#subscribe)
The request includes the following parameters:
@@ -85,19 +85,19 @@ The `streams` parameter provides access to the following default streams of info
- `peer_status` - **(Admin only)** Information about connected peer `rippled` servers, especially with regards to the consensus process.
- `transactions` - Sends a message whenever a transaction is included in a closed ledger.
- `transactions_proposed` - Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation.
**Note:** [Even some transactions that don't succeed are included](transaction-results.html) in validated ledgers, because they take the anti-spam transaction fee.
**Note:** [Even some transactions that don't succeed are included](../../../protocol/transactions/transaction-results/transaction-results.md) in validated ledgers, because they take the anti-spam transaction fee.
- `server` - Sends a message whenever the status of the `rippled` server (for example, network connectivity) changes.
- `validations` - Sends a message whenever the server receives a validation message, regardless of if the server trusts the validator. (An individual `rippled` declares a ledger validated when the server receives validation messages from at least a quorum of trusted validators.)
**Note:** The following streams are not available from Clio and `rippled` servers in [Reporting Mode][]: `server`, `peer_status`, `consensus`. Both will return the `reportingUnsupported` error if you request one of these streams. [Updated in: rippled 1.8.1][] [New in: Clio v2.0](https://github.com/XRPLF/clio/releases/tag/2.0.0 "BADGE_BLUE")
**Note:** The following streams are not available from Clio and `rippled` servers in [Reporting Mode][]: `server`, `peer_status`, `consensus`. Both will return the `reportingUnsupported` error if you request one of these streams. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.8.1" %}Updated in: rippled 1.8.1{% /badge %} {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" %}New in: Clio v2.0{% /badge %}
Each member of the `books` array, if provided, is an object with the following fields:
| `Field` | Type | Description |
|:-------------|:--------|:----------------------------------------------------|
| `taker_gets` | Object | Specification of which currency the account taking the Offer would receive, as a [currency object with no amount](currency-formats.html#specifying-without-amounts). |
| `taker_pays` | Object | Specification of which currency the account taking the Offer would pay, as a [currency object with no amount](currency-formats.html#specifying-without-amounts). |
| `taker` | String | Unique [account address](accounts.html) to use as a perspective for viewing offers, in the XRP Ledger's [base58][] format. (This affects the funding status and fees of [Offers](offers.html).) |
| `taker_gets` | Object | Specification of which currency the account taking the Offer would receive, as a [currency object with no amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). |
| `taker_pays` | Object | Specification of which currency the account taking the Offer would pay, as a [currency object with no amount](../../../protocol/data-types/currency-formats.md#specifying-without-amounts). |
| `taker` | String | Unique [account address](../../../../concepts/accounts/accounts.md) to use as a perspective for viewing offers, in the XRP Ledger's [base58][] format. (This affects the funding status and fees of [Offers](../../../../concepts/tokens/decentralized-exchange/offers.md).) |
| `snapshot` | Boolean | _(Optional)_ If `true`, return the current state of the order book once when you subscribe before sending updates. The default is `false`. |
| `both` | Boolean | _(Optional)_ If `true`, return both sides of the order book. The default is `false`. |
@@ -105,10 +105,9 @@ Each member of the `books` array, if provided, is an object with the following f
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "Example watch Bitstamp's hot wallet",
@@ -117,8 +116,9 @@ An example of a successful response:
"result": {}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][]. The fields contained in the response vary depending on what subscriptions were included in the request.
@@ -146,7 +146,7 @@ When you subscribe to a particular stream, you receive periodic responses on tha
## Ledger Stream
The `ledger` stream only sends `ledgerClosed` messages when [the consensus process](consensus.html) declares a new validated ledger. The message identifies the ledger and provides some information about its contents.
The `ledger` stream only sends `ledgerClosed` messages when [the consensus process](../../../../concepts/consensus-protocol/index.md) declares a new validated ledger. The message identifies the ledger and provides some information about its contents.
```json
{
@@ -168,20 +168,20 @@ The fields from a ledger stream message are as follows:
| `Field` | Type | Description |
|:--------------------|:--------------------------|:---------------------------|
| `type` | String | `ledgerClosed` indicates this is from the ledger stream |
| `fee_base` | Number | The [reference transaction cost](transaction-cost.html#reference-transaction-cost) as of this ledger version, in [drops of XRP][]. If this ledger version includes a [SetFee pseudo-transaction](setfee.html) the new transaction cost applies starting with the following ledger version. |
| `fee_ref` | Number | _(May be omitted)_ The [reference transaction cost](transaction-cost.html#reference-transaction-cost) in "fee units". If the _[XRPFees amendment][]_ is enabled, this field is permanently omitted as it will no longer be relevant. |
| `fee_base` | Number | The [reference transaction cost](../../../../concepts/transactions/transaction-cost.md#reference-transaction-cost) as of this ledger version, in [drops of XRP][]. If this ledger version includes a [SetFee pseudo-transaction](../../../protocol/transactions/pseudo-transaction-types/setfee.md) the new transaction cost applies starting with the following ledger version. |
| `fee_ref` | Number | _(May be omitted)_ The [reference transaction cost](../../../../concepts/transactions/transaction-cost.md#reference-transaction-cost) in "fee units". If the _[XRPFees amendment][]_ is enabled, this field is permanently omitted as it will no longer be relevant. |
| `ledger_hash` | String - [Hash][] | The identifying hash of the ledger version that was closed. |
| `ledger_index` | Number - [Ledger Index][] | The ledger index of the ledger that was closed. |
| `ledger_time` | Number | The time this ledger was closed, in [seconds since the Ripple Epoch][] |
| `reserve_base` | Number | The minimum [reserve](reserves.html), in [drops of XRP][], that is required for an account. If this ledger version includes a [SetFee pseudo-transaction](setfee.html) the new base reserve applies starting with the following ledger version. |
| `reserve_inc` | Number | The [owner reserve](reserves.html#owner-reserves) for each object an account owns in the ledger, in [drops of XRP][]. If the ledger includes a [SetFee pseudo-transaction](setfee.html) the new owner reserve applies after this ledger. |
| `reserve_base` | Number | The minimum [reserve](../../../../concepts/accounts/reserves.md), in [drops of XRP][], that is required for an account. If this ledger version includes a [SetFee pseudo-transaction](../../../protocol/transactions/pseudo-transaction-types/setfee.md) the new base reserve applies starting with the following ledger version. |
| `reserve_inc` | Number | The [owner reserve](../../../../concepts/accounts/reserves.md#owner-reserves) for each object an account owns in the ledger, in [drops of XRP][]. If the ledger includes a [SetFee pseudo-transaction](../../../protocol/transactions/pseudo-transaction-types/setfee.md) the new owner reserve applies after this ledger. |
| `txn_count` | Number | Number of new transactions included in this ledger version. |
| `validated_ledgers` | String | _(May be omitted)_ Range of ledgers that the server has available. This may be a disjoint sequence such as `24900901-24900984,24901116-24901158`. This field is not returned if the server is not connected to the network, or if it is connected but has not yet obtained a ledger from the network. |
## Validations Stream
[New in: rippled 0.29.0][]
{% badge href="https://github.com/XRPLF/rippled/releases/tag/0.29.0" %}New in: rippled 0.29.0{% /badge %}
The validations stream sends messages whenever it receives validation messages, also called validation votes, regardless of whether or not the validation message is from a trusted validator. The message looks like the following:
@@ -215,21 +215,21 @@ The fields from a validations stream message are as follows:
| `Field` | Type | Description |
|:------------------------|:-----------------|:--------------------------------|
| `type` | String | The value `validationReceived` indicates this is from the validations stream. |
| `amendments` | Array of Strings | _(May be omitted)_ The [amendments](amendments.html) this server wants to be added to the protocol. [New in: rippled 0.32.0][] |
| `base_fee` | Integer | _(May be omitted)_ The unscaled transaction cost (`reference_fee` value) this server wants to set by [Fee Voting](fee-voting.html). [New in: rippled 0.32.0][] |
| `cookie` | String - Number | _(May be omitted)_ An arbitrary value chosen by the server at startup. If the same validation key pair signs validations with different cookies concurrently, that usually indicates that multiple servers are incorrectly configured to use the same validation key pair. [New in: rippled 1.8.1][] |
| `flags` | Number | Bit-mask of flags added to this validation message. The flag `0x80000000` indicates that the validation signature is fully-canonical. The flag `0x00000001` indicates that this is a full validation; otherwise it's a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. [New in: rippled 0.32.0][] |
| `full` | Boolean | If `true`, this is a full validation. Otherwise, this is a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. [New in: rippled 0.32.0][] |
| `amendments` | Array of Strings | _(May be omitted)_ The [amendments](../../../../concepts/networks-and-servers/amendments.md) this server wants to be added to the protocol. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `base_fee` | Integer | _(May be omitted)_ The unscaled transaction cost (`reference_fee` value) this server wants to set by [Fee Voting](../../../../concepts/consensus-protocol/fee-voting.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `cookie` | String - Number | _(May be omitted)_ An arbitrary value chosen by the server at startup. If the same validation key pair signs validations with different cookies concurrently, that usually indicates that multiple servers are incorrectly configured to use the same validation key pair. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.8.1" %}New in: rippled 1.8.1{% /badge %} |
| `flags` | Number | Bit-mask of flags added to this validation message. The flag `0x80000000` indicates that the validation signature is fully-canonical. The flag `0x00000001` indicates that this is a full validation; otherwise it's a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `full` | Boolean | If `true`, this is a full validation. Otherwise, this is a partial validation. Partial validations are not meant to vote for any particular ledger. A partial validation indicates that the validator is still online but not keeping up with consensus. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `ledger_hash` | String | The identifying hash of the proposed ledger is being validated. |
| `ledger_index` | String - Number | The [Ledger Index][] of the proposed ledger. [New in: rippled 0.31.0][] |
| `load_fee` | Integer | _(May be omitted)_ The local load-scaled transaction cost this validator is currently enforcing, in fee units. [New in: rippled 0.32.0][] |
| `master_key` | String | _(May be omitted)_ The validator's master public key, if the validator is using a validator token, in the XRP Ledger's [base58][] format. (See also: [Enable Validation on your `rippled` Server](run-rippled-as-a-validator.html#3-enable-validation-on-your-rippled-server).) [New in: rippled 1.4.0][] |
| `reserve_base` | Integer | _(May be omitted)_ The minimum reserve requirement (`account_reserve` value) this validator wants to set by [Fee Voting](fee-voting.html). [New in: rippled 0.32.0][] |
| `reserve_inc` | Integer | _(May be omitted)_ The increment in the reserve requirement (`owner_reserve` value) this validator wants to set by [Fee Voting](fee-voting.html). [New in: rippled 0.32.0][] |
| `server_version` | String - Number | _(May be omitted)_ An 64-bit integer that encodes the version number of the validating server. For example, `"1745990410175512576"`. Only provided once every 256 ledgers. [New in: rippled 1.8.1][] |
| `ledger_index` | String - Number | The [Ledger Index][] of the proposed ledger. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.31.0" %}New in: rippled 0.31.0{% /badge %} |
| `load_fee` | Integer | _(May be omitted)_ The local load-scaled transaction cost this validator is currently enforcing, in fee units. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `master_key` | String | _(May be omitted)_ The validator's master public key, if the validator is using a validator token, in the XRP Ledger's [base58][] format. (See also: [Enable Validation on your `rippled` Server](../../../../infrastructure/configuration/server-modes/run-rippled-as-a-validator.md#3-enable-validation-on-your-rippled-server).) {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %} |
| `reserve_base` | Integer | _(May be omitted)_ The minimum reserve requirement (`account_reserve` value) this validator wants to set by [Fee Voting](../../../../concepts/consensus-protocol/fee-voting.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `reserve_inc` | Integer | _(May be omitted)_ The increment in the reserve requirement (`owner_reserve` value) this validator wants to set by [Fee Voting](../../../../concepts/consensus-protocol/fee-voting.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `server_version` | String - Number | _(May be omitted)_ An 64-bit integer that encodes the version number of the validating server. For example, `"1745990410175512576"`. Only provided once every 256 ledgers. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.8.1" %}New in: rippled 1.8.1{% /badge %} |
| `signature` | String | The signature that the validator used to sign its vote for this ledger. |
| `signing_time` | Number | When this validation vote was signed, in [seconds since the Ripple Epoch][]. [New in: rippled 0.32.0][] |
| `validated_hash` | String | The unique hash of the proposed ledger this validation applies to. [New in: rippled 1.8.1][] |
| `signing_time` | Number | When this validation vote was signed, in [seconds since the Ripple Epoch][]. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.32.0" %}New in: rippled 0.32.0{% /badge %} |
| `validated_hash` | String | The unique hash of the proposed ledger this validation applies to. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.8.1" %}New in: rippled 1.8.1{% /badge %} |
| `validation_public_key` | String | The public key from the key-pair that the validator used to sign the message, in the XRP Ledger's [base58][] format. This identifies the validator sending the message and can also be used to verify the `signature`. If the validator is using a token, this is an ephemeral public key. |
@@ -360,14 +360,14 @@ Transaction stream messages have the following fields:
| `Field` | Type | Description |
|:------------------------|:--------------------------|:-----------------------|
| `type` | String | `transaction` indicates this is the notification of a transaction, which could come from several possible streams. |
| `engine_result` | String | String [Transaction result code](transaction-results.html) |
| `engine_result_code` | Number | Numeric [transaction response code](transaction-results.html), if applicable. |
| `engine_result` | String | String [Transaction result code](../../../protocol/transactions/transaction-results/transaction-results.md) |
| `engine_result_code` | Number | Numeric [transaction response code](../../../protocol/transactions/transaction-results/transaction-results.md), if applicable. |
| `engine_result_message` | String | Human-readable explanation for the transaction response |
| `ledger_current_index` | Number - [Ledger Index][] | _(Unvalidated transactions only)_ The ledger index of the current in-progress [ledger version](ledgers.html) for which this transaction is currently proposed. |
| `ledger_current_index` | Number - [Ledger Index][] | _(Unvalidated transactions only)_ The ledger index of the current in-progress [ledger version](../../../../concepts/ledgers/index.md) for which this transaction is currently proposed. |
| `ledger_hash` | String - [Hash][] | _(Validated transactions only)_ The identifying hash of the ledger version that includes this transaction |
| `ledger_index` | Number - [Ledger Index][] | _(Validated transactions only)_ The ledger index of the ledger version that includes this transaction. |
| `meta` | Object | _(Validated transactions only)_ The [transaction metadata](transaction-metadata.html), which shows the exact outcome of the transaction in detail. |
| `transaction` | Object | The [definition of the transaction](transaction-formats.html) in JSON format |
| `meta` | Object | _(Validated transactions only)_ The [transaction metadata](../../../protocol/transactions/metadata.md), which shows the exact outcome of the transaction in detail. |
| `transaction` | Object | The [definition of the transaction](../../../protocol/transactions/index.md) in JSON format |
| `validated` | Boolean | If `true`, this transaction is included in a validated ledger and its outcome is final. Responses from the `transaction` stream should always be validated. |
@@ -548,14 +548,14 @@ The format of an order book stream message is the same as that of [transaction s
| `Field` | Value | Description |
|:--------------------------|:-------|:----------------------------------------|
| `transaction.owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is [frozen](freezes.html). |
| `transaction.owner_funds` | String | Numeric amount of the `TakerGets` currency that the `Account` sending this OfferCreate transaction has after executing this transaction. This does not check whether the currency amount is [frozen](../../../../concepts/tokens/fungible-tokens/freezes.md). |
## Consensus Stream
[New in: rippled 1.4.0][]
{% badge href="https://github.com/XRPLF/rippled/releases/tag/1.4.0" %}New in: rippled 1.4.0{% /badge %}
The `consensus` stream sends `consensusPhase` messages when [the consensus process](consensus.html) changes phase. The message contains the new phase of consensus the server is in.
The `consensus` stream sends `consensusPhase` messages when [the consensus process](../../../../concepts/consensus-protocol/index.md) changes phase. The message contains the new phase of consensus the server is in.
```json
{
@@ -571,6 +571,4 @@ The fields from a consensus stream message are as follows:
| `type` | String | `consensusPhase` indicates this is from the consensus stream |
| `consensus` | String | The new consensus phase the server is in. Possible values are `open`, `establish`, and `accepted`. |
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

22
content/references/http-websocket-apis/public-api-methods/subscription-methods/unsubscribe.md
View File

@@ -17,10 +17,9 @@ The `unsubscribe` command tells the server to stop sending messages for a partic
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "Unsubscribe a lot of stuff",
@@ -42,10 +41,11 @@ An example of the request format:
]
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#unsubscribe)
[Try it! >](/resources/dev-tools/websocket-api-tool#unsubscribe)
The parameters in the request are specified almost exactly like the parameters to the [subscribe method][], except that they are used to define which subscriptions to end instead. The parameters are:
@@ -70,10 +70,9 @@ The objects in the `books` array are defined almost like the ones from subscribe
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "Unsubscribe a lot of stuff",
@@ -82,8 +81,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing no fields.
@@ -101,6 +101,4 @@ The response follows the [standard format][], with a successful result containin
* `dstIsrMalformed` - The `issuer` field of one or more `taker_gets` sub-fields of the `books` field in the request is not valid.
* `badMarket` - One or more desired order books in the `books` field does not exist; for example, offers to exchange a currency for itself.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/transaction-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: transaction-methods.html # watch for clashes w/ this filename
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Transaction Methods
Transactions are the only thing that can modify the shared state of the XRP Ledger. All business on the XRP Ledger takes the form of transactions. Use these methods to work with transactions.
Transactions are the only thing that can modify the shared state of the XRP Ledger. All business on the XRP Ledger takes the form of transactions. Use these methods to work with transactions.
{% child-pages /%}

102
content/references/http-websocket-apis/public-api-methods/transaction-methods/submit.md
View File

@@ -9,7 +9,7 @@ labels:
# submit
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/Submit.cpp "Source")
The `submit` method applies a [transaction](transaction-formats.html) and sends it to the network to be confirmed and included in future ledgers.
The `submit` method applies a [transaction](../../../protocol/transactions/index.md) and sends it to the network to be confirmed and included in future ledgers.
This command has two modes:
@@ -24,15 +24,14 @@ A submit-only request includes the following parameters:
| `Field` | Type | Required? | Description |
|:------------|:--------|:----------|:-----------------------------------------------------|
| `tx_blob` | String | Yes | Hex representation of the signed transaction to submit. This can be a [multi-signed transaction](multi-signing.html). |
| `tx_blob` | String | Yes | Hex representation of the signed transaction to submit. This can be a [multi-signed transaction](../../../../concepts/accounts/multi-signing.md). |
| `fail_hard` | Boolean | No | If `true`, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is `false`. |
### Request Format
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 3,
@@ -40,9 +39,9 @@ A submit-only request includes the following parameters:
"tx_blob": "1200002280000000240000001E61D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000B732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB7447304502210095D23D8AF107DF50651F266259CC7139D0CD0C64ABBA3A958156352A0D95A21E02207FCF9B77D7510380E49FF250C21B57169E14E9B4ACFD314CEDC79DDD0A38B8A681144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "submit",
@@ -53,24 +52,25 @@ A submit-only request includes the following parameters:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: submit tx_blob
submit 1200002280000000240000000361D4838D7EA4C6800000000000000000000000000055534400000000004B4E9C06F24296074F7BC48F92A97916C6DC5EA968400000000000000A732103AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB74473045022100D184EB4AE5956FF600E7536EE459345C7BBCF097A84CC61A93B9AF7197EDB98702201CEA8009B7BEEBAA2AACC0359B41C427C1C5B550A4CA4B80CF2174AF2D6D5DCE81144B4E9C06F24296074F7BC48F92A97916C6DC5EA983143E9D4A2B8AA0780F682D136F7A56D6724EF53754
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#submit)
[Try it! >](/resources/dev-tools/websocket-api-tool#submit)
## Sign-and-Submit Mode
This mode signs a transaction and immediately submits it. This mode is intended to be used for testing. You cannot use this mode for [multi-signed transactions](multi-signing.html).
This mode signs a transaction and immediately submits it. This mode is intended to be used for testing. You cannot use this mode for [multi-signed transactions](../../../../concepts/accounts/multi-signing.md).
_By default, sign-and-submit mode is [admin-only](admin-api-methods.html)._ It can be used as a public method if the server has [enabled public signing](enable-public-signing.html).
_By default, sign-and-submit mode is [admin-only](../../admin-api-methods/index.md)._ It can be used as a public method if the server has [enabled public signing](../../../../infrastructure/configuration/enable-public-signing.md).
You can provide the secret key used to sign the transaction in the following ways:
@@ -81,27 +81,26 @@ The request includes the following parameters:
| `Field` | Type | Description |
|:---------------|:--------|:--------------------------------------------------|
| `tx_json` | Object | [Transaction definition](transaction-formats.html) in JSON format, optionally omitting any auto-fillable fields. |
| `tx_json` | Object | [Transaction definition](../../../protocol/transactions/index.md) in JSON format, optionally omitting any auto-fillable fields. |
| `secret` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Do not send your secret to untrusted servers or through unsecured network connections. Cannot be used with `key_type`, `seed`, `seed_hex`, or `passphrase`. |
| `seed` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Must be in the XRP Ledger's [base58][] format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed_hex`, or `passphrase`. |
| `seed_hex` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it. Must be in hexadecimal format. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `passphrase`. |
| `passphrase` | String | _(Optional)_ Secret key of the account supplying the transaction, used to sign it, as a string passphrase. If provided, you must also specify the `key_type`. Cannot be used with `secret`, `seed`, or `seed_hex`. |
| `key_type` | String | _(Optional)_ Type of cryptographic key provided in this request. Valid types are `secp256k1` or `ed25519`. Defaults to `secp256k1`. Cannot be used with `secret`. **Caution:** Ed25519 support is experimental. |
| `fail_hard` | Boolean | _(Optional)_ If `true`, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is `false`. [Updated in: rippled 1.5.0][] |
| `fail_hard` | Boolean | _(Optional)_ If `true`, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is `false`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}Updated in: rippled 1.5.0{% /badge %} |
| `offline` | Boolean | _(Optional)_ If `true`, when constructing the transaction, do not try to automatically fill in or validate values. The default is `false`. |
| `build_path` | Boolean | _(Optional)_ If this field is provided, the server [auto-fills](transaction-common-fields.html#auto-fillable-fields) the `Paths` field of a [Payment transaction][] before signing. You must omit this field if the transaction is a [direct XRP payment](direct-xrp-payments.html) or if it is not a Payment-type transaction. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. ([Issue #3272](https://github.com/XRPLF/rippled/issues/3272)) |
| `fee_mult_max` | Integer | _(Optional)_ Sign-and-submit fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](transaction-common-fields.html#auto-fillable-fields) would be greater than the [reference transaction cost](transaction-cost.html#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `10`. |
| `fee_div_max` | Integer | _(Optional)_ Sign-and-submit fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](transaction-common-fields.html#auto-fillable-fields) would be greater than the [reference transaction cost](transaction-cost.html#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `1`. [New in: rippled 0.30.1][] |
| `build_path` | Boolean | _(Optional)_ If this field is provided, the server [auto-fills](../../../protocol/transactions/common-fields.md#auto-fillable-fields) the `Paths` field of a [Payment transaction][] before signing. You must omit this field if the transaction is a [direct XRP payment](../../../../concepts/payment-types/direct-xrp-payments.md) or if it is not a Payment-type transaction. **Caution:** The server looks for the presence or absence of this field, not its value. This behavior may change. ([Issue #3272](https://github.com/XRPLF/rippled/issues/3272)) |
| `fee_mult_max` | Integer | _(Optional)_ Sign-and-submit fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](../../../protocol/transactions/common-fields.md#auto-fillable-fields) would be greater than the [reference transaction cost](../../../../concepts/transactions/transaction-cost.md#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `10`. |
| `fee_div_max` | Integer | _(Optional)_ Sign-and-submit fails with the error `rpcHIGH_FEE` if the [auto-filled `Fee` value](../../../protocol/transactions/common-fields.md#auto-fillable-fields) would be greater than the [reference transaction cost](../../../../concepts/transactions/transaction-cost.md#special-transaction-costs) × `fee_mult_max` ÷ `fee_div_max`. This field has no effect if you explicitly specify the `Fee` field of the transaction. The default is `1`. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.30.1" %}New in: rippled 0.30.1{% /badge %} |
See the [sign method][] for detailed information on how the server automatically fills in certain fields.
### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -121,9 +120,9 @@ An example of the request format:
"fee_mult_max": 1000
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "submit",
@@ -146,26 +145,26 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: submit secret json [offline]
rippled submit s████████████████████████████ '{"Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "Amount": { "currency": "USD", "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", "value": "1" }, "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", "TransactionType": "Payment", "Fee": "10000"}'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#submit)
[Try it! >](/resources/dev-tools/websocket-api-tool#submit)
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -204,9 +203,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -243,9 +242,9 @@ An example of a successful response:
"validated_ledger_index" : 21184416
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
@@ -285,29 +284,30 @@ Connecting to 127.0.0.1:5005
"validated_ledger_index" : 21184416
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
| `Field` | Type | Description |
|:------------------------|:--------|:-----------------------------------------|
| `engine_result` | String | Text [result code](transaction-results.html) indicating the preliminary result of the transaction, for example `tesSUCCESS` |
| `engine_result_code` | Integer | Numeric version of the [result code](transaction-results.html). **Not recommended.** |
| `engine_result` | String | Text [result code](../../../protocol/transactions/transaction-results/transaction-results.md) indicating the preliminary result of the transaction, for example `tesSUCCESS` |
| `engine_result_code` | Integer | Numeric version of the [result code](../../../protocol/transactions/transaction-results/transaction-results.md). **Not recommended.** |
| `engine_result_message` | String | Human-readable explanation of the transaction's preliminary result |
| `tx_blob` | String | The complete transaction in hex string format |
| `tx_json` | Object | The complete transaction in JSON format |
| `accepted` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. The value `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. [New in: rippled 1.5.0][] |
| `account_sequence_available` | Number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] available for the sending account after all pending and [queued](transaction-queue.html) transactions. [New in: rippled 1.5.0][] |
| `account_sequence_next` | number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] for the sending account after all transactions that have been provisionally applied, but not transactions in the [queue](transaction-queue.html). [New in: rippled 1.5.0][] |
| `applied` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version. [New in: rippled 1.5.0][] |
| `broadcast` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode][], the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. [New in: rippled 1.5.0][] |
| `kept` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was kept to be retried later. [New in: rippled 1.5.0][] |
| `queued` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates the transaction was put in the [Transaction Queue](transaction-queue.html), which means it is likely to be included in a future ledger version. [New in: rippled 1.5.0][] |
| `open_ledger_cost` | String | _(Omitted in sign-and-submit mode)_ The current [open ledger cost](transaction-cost.html#open-ledger-cost) before processing this transaction. Transactions with a lower cost are likely to be [queued](transaction-queue.html). [New in: rippled 1.5.0][] |
| `accepted` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was applied, queued, broadcast, or kept for later. The value `false` indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `account_sequence_available` | Number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] available for the sending account after all pending and [queued](../../../../concepts/transactions/transaction-queue.md) transactions. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `account_sequence_next` | number | _(Omitted in sign-and-submit mode)_ The next [Sequence Number][] for the sending account after all transactions that have been provisionally applied, but not transactions in the [queue](../../../../concepts/transactions/transaction-queue.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `applied` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `broadcast` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates this transaction was broadcast to peer servers in the peer-to-peer XRP Ledger network. (Note: if the server has no peers, such as in [stand-alone mode][], the server uses the value `true` for cases where it _would_ have broadcast the transaction.) The value `false` indicates the transaction was not broadcast to any other servers. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `kept` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates that the transaction was kept to be retried later. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `queued` | Boolean | _(Omitted in sign-and-submit mode)_ The value `true` indicates the transaction was put in the [Transaction Queue](../../../../concepts/transactions/transaction-queue.md), which means it is likely to be included in a future ledger version. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `open_ledger_cost` | String | _(Omitted in sign-and-submit mode)_ The current [open ledger cost](../../../../concepts/transactions/transaction-cost.md#open-ledger-cost) before processing this transaction. Transactions with a lower cost are likely to be [queued](../../../../concepts/transactions/transaction-queue.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.5.0" %}New in: rippled 1.5.0{% /badge %} |
| `validated_ledger_index` | Integer | _(Omitted in sign-and-submit mode)_ The [ledger index][] of the newest validated ledger at the time of submission. This provides a lower bound on the ledger versions that the transaction can appear in as a result of this request. (The transaction could only have been validated in this ledger version or earlier if it had already been submitted before.) |
**Warning:** Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](transaction-results.html) for details, and do not consider the transaction's results final until they appear in a validated ledger version.
**Warning:** Even if the WebSocket response has `"status":"success"`, indicating that the command was successfully received, that does _not_ indicate that the transaction executed successfully. Many situations can prevent a transaction from processing successfully, such as a lack of trust lines connecting the two accounts in a payment, or changes in the state of the ledger since the time the transaction was constructed. Even if nothing is wrong, it may take several seconds to close and validate the ledger version that includes the transaction. See the [full list of transaction responses](../../../protocol/transactions/transaction-results/transaction-results.md) for details, and do not consider the transaction's results final until they appear in a validated ledger version.
**Caution:** If this command results in an error message, the message can contain the secret key from the request. (This can only happen in sign-and-submit mode.) Make sure that these errors are not visible to others.
@@ -319,7 +319,7 @@ The response follows the [standard format][], with a successful result containin
## Possible Errors
* Any of the [universal error types][].
* `amendmentBlocked` - The transaction cannot be submitted to the network because the `rippled` server is [amendment blocked](amendments.html#amendment-blocked-servers).
* `amendmentBlocked` - The transaction cannot be submitted to the network because the `rippled` server is [amendment blocked](../../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers).
* `highFee` - The `fee_mult_max` parameter was specified, but the server's current fee multiplier exceeds the specified one. (Sign-and-Submit mode only)
* `internalJson` - An internal error occurred when serializing the transaction to JSON. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
* `internalSubmit` - An internal error occurred when submitting the transaction. This could be caused by many aspects of the transaction, including a bad signature or some fields being malformed.
@@ -328,10 +328,6 @@ The response follows the [standard format][], with a successful result containin
* `invalidTransaction` - The transaction is malformed or otherwise invalid.
* `noPath` - The transaction did not include paths, and the server was unable to find a path by which this payment can occur. (Sign-and-Submit mode only)
* `tooBusy` - The transaction did not include paths, but the server is too busy to do pathfinding right now. Does not occur if you are connected as an admin. (Sign-and-Submit mode only)
* `notSupported` - Signing is not supported by this server (Sign-and-Submit mode only.) If you are the server admin, you can still access signing when connected [as an admin](admin-api-methods.html), or you could [enable public signing](enable-public-signing.html). [New in: rippled 1.1.0][]
* `notSupported` - Signing is not supported by this server (Sign-and-Submit mode only.) If you are the server admin, you can still access signing when connected [as an admin](../../admin-api-methods/index.md), or you could [enable public signing](../../../../infrastructure/configuration/enable-public-signing.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.1.0" %}New in: rippled 1.1.0{% /badge %}
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

46
content/references/http-websocket-apis/public-api-methods/transaction-methods/submit_multisigned.md
View File

@@ -8,17 +8,16 @@ labels:
# submit_multisigned
[[Source]](https://github.com/XRPLF/rippled/blob/release/src/ripple/rpc/handlers/SubmitMultiSigned.cpp "Source")
The `submit_multisigned` command applies a [multi-signed](multi-signing.html) transaction and sends it to the network to be included in future ledgers. (You can also submit multi-signed transactions in binary form using the [`submit` command in submit-only mode](submit.html#submit-only-mode).)
The `submit_multisigned` command applies a [multi-signed](../../../../concepts/accounts/multi-signing.md) transaction and sends it to the network to be included in future ledgers. (You can also submit multi-signed transactions in binary form using the [`submit` command in submit-only mode](submit.md#submit-only-mode).)
This command requires the [MultiSign amendment][] to be enabled. [New in: rippled 0.31.0][]
This command requires the [MultiSign amendment][] to be enabled. {% badge href="https://github.com/XRPLF/rippled/releases/tag/0.31.0" %}New in: rippled 0.31.0{% /badge %}
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "submit_multisigned_example",
@@ -52,9 +51,9 @@ An example of the request format:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "submit_multisigned",
@@ -94,9 +93,9 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: submit_multisigned <tx_json>
rippled submit_multisigned '{
@@ -130,24 +129,24 @@ rippled submit_multisigned '{
"hash": "81A477E2A362D171BB16BE17B4120D9F809A327FA00242ABCA867283BEA2F4F8"
}'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
| `Field` | Type | Required? | Description |
|:------------|:--------|:----------|:-----------------------------------------------------|
| `tx_json` | Object | Yes | [Transaction in JSON format](transaction-formats.html) with an array of `Signers`. To be successful, the weights of the signatures must be equal or higher than the quorum of the [SignerList](signerlist.html). |
| `tx_json` | Object | Yes | [Transaction in JSON format](../../../protocol/transactions/index.md) with an array of `Signers`. To be successful, the weights of the signatures must be equal or higher than the quorum of the [SignerList](../../../protocol/ledger-data/ledger-entry-types/signerlist.md). |
| `fail_hard` | Boolean | No | If `true`, and the transaction fails locally, do not retry or relay the transaction to other servers. The default is `false`. |
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": "submit_multisigned_example",
@@ -191,9 +190,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -237,9 +236,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```
Loading: "/etc/rippled.cfg"
Connecting to 127.0.0.1:5005
@@ -284,8 +283,9 @@ Connecting to 127.0.0.1:5005
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -294,8 +294,8 @@ The response follows the [standard format][], with a successful result containin
| `engine_result` | String | Code indicating the preliminary result of the transaction, for example `tesSUCCESS` |
| `engine_result_code` | Integer | Numeric code indicating the preliminary result of the transaction, directly correlated to `engine_result` |
| `engine_result_message` | String | Human-readable explanation of the preliminary transaction result |
| `tx_blob` | String | The complete [transaction](transaction-formats.html) in hex string format |
| `tx_json` | Object | The complete [transaction](transaction-formats.html) in JSON format |
| `tx_blob` | String | The complete [transaction](../../../protocol/transactions/index.md) in hex string format |
| `tx_json` | Object | The complete [transaction](../../../protocol/transactions/index.md) in JSON format |
## Possible Errors
@@ -304,6 +304,4 @@ The response follows the [standard format][], with a successful result containin
* `srcActMalformed` - The `Account` field from the `tx_json` was invalid or missing.
* `internal` - An internal error occurred. This includes the case where a signature is not valid for the transaction JSON provided.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

43
content/references/http-websocket-apis/public-api-methods/transaction-methods/transaction_entry.md
View File

@@ -14,10 +14,9 @@ The `transaction_entry` method retrieves information on a single transaction fro
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 4,
@@ -26,9 +25,9 @@ An example of the request format:
"ledger_index": 56865245
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "transaction_entry",
@@ -40,17 +39,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: transaction_entry transaction_hash ledger_index|ledger_hash
rippled transaction_entry C53ECF838647FA5A4C780377025FEC7999AB4182590510CA461444B207AB74A9 56865245
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#transaction_entry)
[Try it! >](/resources/dev-tools/websocket-api-tool#transaction_entry)
The request includes the following parameters:
@@ -66,10 +66,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 4,
@@ -192,9 +191,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"result": {
@@ -315,9 +314,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -438,8 +437,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -447,8 +447,8 @@ The response follows the [standard format][], with a successful result containin
|:---------------|:--------------------------|:--------------------------------|
| `ledger_index` | Number - [Ledger Index][] | The ledger index of the ledger version the transaction was found in; this is the same as the one from the request. |
| `ledger_hash` | String - [Hash][] | _(May be omitted)_ The identifying hash of the ledger version the transaction was found in; this is the same as the one from the request. |
| `metadata` | Object | The [transaction metadata](transaction-metadata.html), which shows the exact results of the transaction in detail. |
| `tx_json` | Object | JSON representation of the [Transaction object](transaction-formats.html) |
| `metadata` | Object | The [transaction metadata](../../../protocol/transactions/metadata.md), which shows the exact results of the transaction in detail. |
| `tx_json` | Object | JSON representation of the [Transaction object](../../../protocol/transactions/index.md) |
There are a couple possible reasons the server may fail to find the transaction:
@@ -464,7 +464,4 @@ There are a couple possible reasons the server may fail to find the transaction:
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `transactionNotFound` - The transaction specified in the request could not be found in the specified ledger. (It might be in a different ledger version, or it might not be available at all.)
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

102
content/references/http-websocket-apis/public-api-methods/transaction-methods/tx.md
View File

@@ -10,16 +10,15 @@ labels:
[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/Tx.cpp "Source")
The `tx` method retrieves information on a single [transaction](transaction-formats.html), by its [identifying hash][] or its [CTID](ctid.html).
The `tx` method retrieves information on a single [transaction](../../../protocol/transactions/index.md), by its [identifying hash][] or its [CTID](../../api-conventions/ctid.md).
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket (Hash)*
{% tabs %}
{% tab label="WebSocket (Hash)" %}
```json
{
"id": 1,
@@ -28,10 +27,9 @@ An example of the request format:
"binary": false
}
```
{% /tab %}
*WebSocket (CTID)*
{% tab label="WebSocket (CTID)" %}
```json
{
"id": "CTID example",
@@ -40,10 +38,9 @@ An example of the request format:
"binary": false
}
```
{% /tab %}
*JSON-RPC (Hash)*
{% tab label="JSON-RPC (Hash)" %}
```json
{
"method": "tx",
@@ -55,9 +52,9 @@ An example of the request format:
]
}
```
{% /tab %}
*JSON-RPC (CTID)*
{% tab label="JSON-RPC (CTID)" %}
```json
{
"method": "tx",
@@ -69,25 +66,26 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: tx transaction [binary]
rippled tx C53ECF838647FA5A4C780377025FEC7999AB4182590510CA461444B207AB74A9 false
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#tx)
[Try it! >](/resources/dev-tools/websocket-api-tool#tx)
The request includes the following parameters:
| Field | Type | Required? | Description |
|:--------------|:--------|:----------|----------------------------------------|
| `ctid` | String | No | The [compact transaction identifier](ctid.html) of the transaction to look up. Must use uppercase hexadecimal only. [New in: rippled 1.12.0][] _(Not supported in Clio v2.0 and earlier)_ |
| `ctid` | String | No | The [compact transaction identifier](../../api-conventions/ctid.md) of the transaction to look up. Must use uppercase hexadecimal only. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.12.0" %}New in: rippled 1.12.0{% /badge %} _(Not supported in Clio v2.0 and earlier)_ |
| `transaction` | String | No | The 256-bit hash of the transaction to look up, as hexadecimal. |
| `binary` | Boolean | No | If `true`, return transaction data and metadata as binary [serialized](serialization.html) to hexadecimal strings. If `false`, return transaction data and metadata as JSON. The default is `false`. |
| `binary` | Boolean | No | If `true`, return transaction data and metadata as binary [serialized](../../../protocol/binary-format.md) to hexadecimal strings. If `false`, return transaction data and metadata as JSON. The default is `false`. |
| `min_ledger` | Number | No | Use this with `max_ledger` to specify a range of up to 1000 [ledger indexes][ledger index], starting with this ledger (inclusive). If the server [cannot find the transaction](#not-found-response), it confirms whether it was able to search all the ledgers in this range. |
| `max_ledger` | Number | No | Use this with `min_ledger` to specify a range of up to 1000 [ledger indexes][ledger index], ending with this ledger (inclusive). If the server [cannot find the transaction](#not-found-response), it confirms whether it was able to search all the ledgers in the requested range. |
@@ -99,34 +97,25 @@ You must provide _either_ `ctid` or `transaction`, but not both.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
{% tabs %}
*WebSocket (Hash)*
{% tab label="WebSocket (Hash)" %}
{% code-snippet file="/_api-examples/tx/ws-response-hash.json" language="json" /%}
{% /tab %}
```json
{% include '_api-examples/tx/ws-response-hash.json' %}
```
{% tab label="WebSocket (CTID)" %}
{% code-snippet file="/_api-examples/tx/ws-response-ctid.json" language="json" /%}
{% /tab %}
*WebSocket (CTID)*
{% tab label="JSON-RPC (Hash)" %}
{% code-snippet file="/_api-examples/tx/jsonrpc-response-hash.json" language="json" /%}
{% /tab %}
```json
{% include '_api-examples/tx/ws-response-ctid.json' %}
```
*JSON-RPC (Hash)*
```json
{% include '_api-examples/tx/jsonrpc-response-hash.json' %}
```
*JSON-RPC (CTID)*
```json
{% include '_api-examples/tx/jsonrpc-response-ctid.json' %}
```
*Commandline*
{% tab label="JSON-RPC (CTID)" %}
{% code-snippet file="/_api-examples/tx/jsonrpc-response-ctid.json" language="json" /%}
{% /tab %}
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -246,21 +235,22 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the fields of the [Transaction object](transaction-formats.html) as well as the following additional fields:
The response follows the [standard format][], with a successful result containing the fields of the [Transaction object](../../../protocol/transactions/index.md) as well as the following additional fields:
| `Field` | Type | Description |
|:---------------|:---------------------------------|:-------------------------|
| `ctid` | String | The transaction's [compact transaction identifier](ctid.html). [New in: rippled 1.12.0][] _(Not supported in Clio v2.0 and earlier.)_ |
| `date` | Number | The [close time](ledger-close-times.html) of the ledger in which the transaction was applied, in [seconds since the Ripple Epoch][]. |
| `ctid` | String | The transaction's [compact transaction identifier](../../api-conventions/ctid.md). {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.12.0" %}New in: rippled 1.12.0{% /badge %} _(Not supported in Clio v2.0 and earlier.)_ |
| `date` | Number | The [close time](../../../../concepts/ledgers/ledger-close-times.md) of the ledger in which the transaction was applied, in [seconds since the Ripple Epoch][]. |
| `hash` | String | The unique [identifying hash][] of the transaction |
| `inLedger` | Number | _(Deprecated)_ Alias for `ledger_index`. |
| `ledger_index` | Number | The [ledger index][] of the ledger that includes this transaction. |
| `meta` | Object (JSON) or String (binary) | [Transaction metadata](transaction-metadata.html), which describes the results of the transaction. |
| `meta` | Object (JSON) or String (binary) | [Transaction metadata](../../../protocol/transactions/metadata.md), which describes the results of the transaction. |
| `validated` | Boolean | If `true`, this data comes from a validated ledger version; if omitted or set to `false`, this data is not final. |
| (Various) | (Various) | Other fields from the [Transaction object](transaction-formats.html) |
| (Various) | (Various) | Other fields from the [Transaction object](../../../protocol/transactions/index.md) |
### Not Found Response
@@ -270,7 +260,7 @@ If the server does not find the transaction, it returns a `txnNotFound` error, w
- The transaction has not been included in any ledger version, and has not been executed.
- The transaction was included in a ledger version that the server does not have available.
This means that a `txnNotFound` on its own is not enough to know the [final outcome of a transaction](finality-of-results.html).
This means that a `txnNotFound` on its own is not enough to know the [final outcome of a transaction](../../../../concepts/transactions/finality-of-results/index.md).
To further narrow down the possibilities, you can provide a range of ledgers to search using the `min_ledger` and `max_ledger` fields in the request. If you provide **both** of those fields, the `txnNotFound` response includes the following field:
@@ -280,10 +270,9 @@ To further narrow down the possibilities, you can provide a range of ledgers to
An example of a `txnNotFound` response that fully searched a requested range of ledgers:
<!-- MULTICODE_BLOCK_START -->
_WebSocket_
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"error": "txnNotFound",
@@ -303,9 +292,9 @@ _WebSocket_
"type": "response"
}
```
{% /tab %}
_JSON-RPC_
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -326,8 +315,9 @@ _JSON-RPC_
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
## Possible Errors
@@ -337,6 +327,4 @@ _JSON-RPC_
* `excessiveLgrRange` - The `min_ledger` and `max_ledger` fields of the request are more than 1000 apart.
* `invalidLgrRange` - The specified `min_ledger` is larger than the `max_ledger`, or one of those parameters is not a valid ledger index.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

38
content/references/http-websocket-apis/public-api-methods/transaction-methods/tx_history.md
View File

@@ -13,10 +13,9 @@ The `tx_history` method retrieves some of the most recent transactions made.
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 5,
@@ -24,9 +23,9 @@ An example of the request format:
"start": 0
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "tx_history",
@@ -37,15 +36,16 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: tx_history [start]
rippled tx_history 0
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes the following parameters:
@@ -57,10 +57,9 @@ The request includes the following parameters:
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 2,
@@ -511,9 +510,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -879,9 +878,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -1431,8 +1430,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following fields:
@@ -1441,7 +1441,7 @@ The response follows the [standard format][], with a successful result containin
| `index` | Unsigned Integer | The value of `start` used in the request. |
| `txs` | Array | Array of transaction objects. |
The fields included in each transaction object vary slightly depending on the type of transaction. See [Transaction Format](transaction-formats.html) for details.
The fields included in each transaction object vary slightly depending on the type of transaction. See [Transaction Format](../../../protocol/transactions/index.md) for details.
## Possible Errors
@@ -1449,6 +1449,4 @@ The fields included in each transaction object vary slightly depending on the ty
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `noPermission` - The `start` field specified was greater than 10000, but you are not connected to the server as an admin.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

8
content/references/http-websocket-apis/public-api-methods/utility-methods/index.md
View File

@@ -1,8 +1,12 @@
---
html: utility-methods.html
parent: public-api-methods.html
template: pagetype-category.html.jinja
metadata:
indexPage: true
---
# Utility Methods
Use these methods to perform convenient tasks, such as ping and random number generation.
Use these methods to perform convenient tasks, such as ping and random number generation.
{% child-pages /%}

20
content/references/http-websocket-apis/public-api-methods/utility-methods/json.md
View File

@@ -12,25 +12,24 @@ The `json` method is a proxy to running other commands, and accepts the paramete
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*Commandline*
{% tabs %}
{% tab label="Commandline" %}
```sh
# Syntax: json method json_stanza
rippled -q json ledger_closed '{}'
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
## Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"result" : {
@@ -40,11 +39,10 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with whichever fields are appropriate to the type of command made.
{% include '_snippets/rippled_versions.md' %}
{% include '_snippets/rippled-api-links.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

35
content/references/http-websocket-apis/public-api-methods/utility-methods/ping.md
View File

@@ -13,19 +13,18 @@ The `ping` command returns an acknowledgement, so that clients can test the conn
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
"command": "ping"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "ping",
@@ -34,17 +33,18 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: ping
rippled ping
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
[Try it! >](websocket-api-tool.html#ping)
[Try it! >](/resources/dev-tools/websocket-api-tool#ping)
The request includes no parameters.
@@ -52,10 +52,9 @@ The request includes no parameters.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -64,9 +63,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -76,8 +75,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing no fields. The client can measure the round-trip time from request to response as latency.
@@ -85,7 +85,4 @@ The response follows the [standard format][], with a successful result containin
* Any of the [universal error types][].
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}

37
content/references/http-websocket-apis/public-api-methods/utility-methods/random.md
View File

@@ -14,19 +14,18 @@ The `random` command provides a random number to be used as a source of entropy
## Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
"command": "random"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
{
"method": "random",
@@ -35,15 +34,16 @@ An example of the request format:
]
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```sh
#Syntax: random
rippled random
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The request includes no parameters.
@@ -51,10 +51,9 @@ The request includes no parameters.
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
{% tabs %}
{% tab label="WebSocket" %}
```json
{
"id": 1,
@@ -65,9 +64,9 @@ An example of a successful response:
"type": "response"
}
```
{% /tab %}
*JSON-RPC*
{% tab label="JSON-RPC" %}
```json
200 OK
@@ -78,9 +77,9 @@ An example of a successful response:
}
}
```
{% /tab %}
*Commandline*
{% tab label="Commandline" %}
```json
{
"result" : {
@@ -89,8 +88,9 @@ An example of a successful response:
}
}
```
{% /tab %}
<!-- MULTICODE_BLOCK_END -->
{% /tabs %}
The response follows the [standard format][], with a successful result containing the following field:
@@ -103,7 +103,4 @@ The response follows the [standard format][], with a successful result containin
* Any of the [universal error types][].
* `internal` - Some internal error occurred, possibly relating to the random number generator.
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}
{% raw-partial file="/_snippets/common-links.md" /%}